Claude Agents vs Skills: When to Use Each

If you keep copy-pasting the same instructions into Claude, you probably do not need a better prompt. You need a Skill.

If you want Claude to read files, call tools, make decisions, and verify the result across multiple steps, you need an Agent.

This article explains the difference and shows when to use each.

What Are Agents and Skills?

Before we can talk about building with Claude, we need to agree on what we're actually building.

What Is an Agent?

An agent is Claude with the ability to act, not just respond, but act. Instead of answering a question and waiting for your next message, an agent can read files from your computer, run code, search the web, edit documents, and make decisions across multiple steps, all without you directing every move. Think of it as handing Claude a computer and a to-do list, then stepping back while it works.

The Claude Agent SDK is the toolkit that makes this possible. Using it, you can build agents in Python or TypeScript that run autonomously and report back only when they're done.

What Is a Skill?

A skill is a package of knowledge. It's a folder containing a special file called SKILL.md, which holds instructions, workflows, and best practices for a specific type of task. Skills can also include scripts and additional resources, which the agent can invoke using its available tools (such as Bash). The skill itself doesn't execute code. Execution depends on the runtime and what the agent is permitted to do. When an agent needs to handle specialized work, it loads the relevant skill and follows its guidance.

Agent Skills were published on October 16, 2025. They use a portable folder-based format built around Markdown instructions and optional scripts. In practice, compatibility with other AI tools depends on whether the tool supports the same skill format and loading behavior, so test before assuming portability.

The Mental Model That Makes This Click

Here's the analogy that ties it all together:

• Agent = a new employee. Capable, motivated, and ready to work. But on day one, they don't know your company's specific processes, formats, or standards.
• Skill = an onboarding manual. It contains step-by-step guides, company policies, and checklists. It doesn't do anything by itself. Someone has to read it and apply it.

The employee (agent) does the work. The manual (skill) teaches them how. Together, they produce a specialist. Separately, they're incomplete.

Agents vs Skills: The Comparison

The One-Line Difference

Agents take action. Skills provide knowledge.

That's the core distinction, and everything else follows from it.

Side-by-Side Comparison

Pay attention to the last row: the barrier to creating a skill is intentionally low. If you can write a markdown file, you can build a skill.

A Concrete Scenario

Imagine you need a daily report prepared every morning: gather data from three sources, analyze it, and format it using your company's style guide.

• The agent handles the orchestration. It reads the data files, runs the analysis, and writes the output, deciding at each step what to do next.
• The skill holds the style guide knowledge. It knows your company uses a specific header format, requires an executive summary first, and has rules for table formatting. The agent loads the skill at the start and applies that knowledge throughout.

Without the skill, the agent produces a generic report. Without the agent, the skill just sits in a folder doing nothing. Together, they produce exactly what you need, every morning, automatically.

Agent, Skill, MCP: What's the Difference?

If you've read anything about Claude lately, you've also seen MCP mentioned alongside agents and skills. Here's how the three relate:

The key distinction: agents and skills live inside your Claude environment. MCP is how the agent reaches outside it, to read from a database, post to Slack, query GitHub, or call any other external service that has an MCP server.

In a real workflow, all three work together: the agent orchestrates the task, the skill tells it how your team handles that type of work, and MCP gives it access to the data and systems it needs to act on.

How Agents Work

An agent doesn't just answer once and stop. It works in a loop, repeating three phases until the task is complete.

The 3-Phase Agent Loop

Phase 1 (Gather Context): What's the situation? The agent starts by learning everything it needs. It might read files, search the web, examine your codebase, or ask a subagent to investigate something specific. This phase is about understanding before acting. The agent never jumps straight to a solution.

Phase 2 (Take Action): What should I do? Armed with context, the agent acts. It might edit code, write a file, run a bash command, call an API, or generate content. Actions use tools, capabilities exposed by the runtime and governed by your permission configuration.

Phase 3 (Verify Work): Did it work? The agent checks its own output. Did the tests pass? Is the file formatted correctly? Did the API call succeed? If not, it loops back to Phase 1, gathers new context about what went wrong, and tries again.

This loop (not a single linear response) is what makes agents powerful. They iterate like a human professional, not like a one-shot chatbot.

The Agent's Toolbox

Depending on the runtime and permissions you configure, an agent can use tools such as:

• Read: read any file on your system
• Write: create new files
• Edit: modify existing files with precision
• Bash: run terminal commands (install packages, run scripts, and more)
• WebSearch: search the internet for current information
• WebFetch: retrieve content from a specific URL
• Glob: find files matching a pattern (e.g., all .py files)
• Grep: search file contents for a pattern
• AskUserQuestion: pause and ask you for input when needed

Subagents: Specialists Within Your Agent

For complex tasks, the main agent can spawn subagents: smaller, focused agents that each handle one piece of a larger job. Think of it like a project manager delegating to specialists: one subagent reviews security, another checks performance. Each works in its own isolated context window and reports its results back to the main agent when done.

Sessions: The Agent Remembers

When you use the Claude Agent SDK, interactions are tied to a session (identified by a session_id). The agent maintains context across multiple calls within a session, so if it reads your codebase on the first call, it still knows what it found on the second. You can pause and resume sessions later, picking up exactly where you left off.

Hello World: Your First Agent

Here's the simplest possible agent that reads a file and returns a summary:

# pip install claude-agent-sdk==0.1.0
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

# The SDK's internal loop handles all three phases automatically:
#   Phase 1 (Gather):  reads auth.py
#   Phase 2 (Act):     processes the content
#   Phase 3 (Verify):  confirms the summary is complete, then exits
async def main():
    async for message in query(
        prompt="Read auth.py and give me a one-paragraph summary of what it does.",
        options=ClaudeAgentOptions(allowed_tools=["Read"])
    ):
        if message.type == "result":
            print(message.content)

asyncio.run(main())

The agent handles everything: it decides to use the Read tool, reads the file, processes the content, and returns the summary. You didn't write a single line of tool-handling logic. The SDK's loop takes care of it.

How Skills Work

Every skill you add to Claude costs context space, measured in tokens, the units Claude uses to process information. Skills solve this with progressive disclosure: a 3-level loading system. Think of it like a well-organized manual: first a table of contents, then the specific chapter you need, then the full appendix only if required.

The 3 Levels of Skill Loading

Level 1: Metadata (~100 tokens per skill, always loaded at startup) Just the skill's name and a short description. This tells Claude that the skill exists and when it should consider using it. The overhead is minimal. You could have dozens of skills and barely notice the cost.

Level 2: Instructions (under 5,000 tokens, loaded when triggered) The full body of the SKILL.md file: step-by-step workflows, best practices, and guidance. Loaded only when the skill becomes relevant to the current task.

Level 3: Resources (unlimited, loaded as needed) Additional markdown files, Python scripts, templates, and reference materials. Scripts run via Bash, and crucially, the code never enters the context window, only the output does. This means a 500-line Python script costs almost no tokens to use.

What's Inside a SKILL.md?

Every skill requires exactly one file: SKILL.md. Here's what a complete example looks like:

---
name: pdf-processor
description: Extracts data from PDF forms and exports to structured formats (JSON, CSV, or plain summary)
---

## When to Use This Skill
Use when the user provides a PDF file and needs data extracted, tables parsed, or forms processed.

## Workflow
1. Identify the PDF type: form, report, or invoice
2. Run the extraction script: `python scripts/extract_fields.py <filename>`
3. Validate output: confirm field names match the PDF labels
4. Format results per user request: JSON, CSV, or prose summary

## Best Practices
- For scanned PDFs, note OCR limitations before delivering results
- If field extraction fails, fall back to section-by-section text parsing
- Always show the user a field count before the full output

The description field does double duty: it's what Claude reads at Level 1 to decide whether the skill is relevant, so writing it clearly is the single most important thing you can do when building a skill.

How Skills Get Triggered

Skills can be invoked in two ways:

• Automatic: Claude reads the task description and recognizes it matches a skill's description. It loads Level 2 without you asking.
• Explicit: You (or the agent) type /pdf-processor to invoke it directly. Useful for workflows with side effects (like deploying code or committing changes) where you want deliberate control rather than automatic triggering.

Once a skill is loaded, it stays in the session for all subsequent interactions.

Agents + Skills Together

A general-purpose agent is like that smart new employee on their first day: capable and motivated, but unfamiliar with your specific systems and standards. Skills are the onboarding materials that turn them into a specialist.

Example 1: Personal Assistant Agent

Three skills, one agent, one morning brief:

# pip install claude-agent-sdk==0.1.0
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="""
        Prepare my morning brief:
        1. /email-summarizer   : summarize inbox highlights and action items
        2. /calendar-manager   : surface today's meetings, flag conflicts
        3. /task-prioritizer   : rank open tasks by deadline and importance
        Write a single summary readable in under 2 minutes.
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Bash", "WebFetch"],
            session_id="morning-brief-session"
        )
    ):
        if message.type == "result":
            print(message.content)

asyncio.run(main())

The agent decides when to invoke each skill, loads only what it needs, and carries that knowledge forward for the rest of the session.

Example 2: Data Analysis Agent

A data analysis agent might carry five format-specific skills: excel-analyzer, pdf-extractor, csv-processor, json-normalizer, and sql-query-builder. Each contains specialized knowledge about one format. When the agent receives a file, it checks the type, loads the matching skill, and applies it. No branching logic is required on your part. The skills own the domain expertise; the agent owns the execution.

Example 3: Terraform PR Review (Platform Engineering)

This is closer to what platform and DevOps teams actually build. The agent reads a Terraform pull request; the skill encodes your platform team's review standards for IAM, networking, tagging, cost allocation, and public exposure. Deterministic checks run as scripts; the agent explains the findings.

terraform-aws-review/
  SKILL.md
  checklists/
    iam.md
    networking.md
    tagging.md
    cost.md
  scripts/
    check_required_tags.py
    detect_public_s3.py

# pip install claude-agent-sdk==0.1.0
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="""
        Review the Terraform changes in the open PR against our platform standards.
        /terraform-aws-review
        Flag any IAM over-permissions, missing required tags, public S3 buckets,
        or cost allocation gaps. Summarize findings by severity.
        """,
        options=ClaudeAgentOptions(allowed_tools=["Read", "Bash", "Glob"])
    ):
        if message.type == "result":
            print(message.content)

asyncio.run(main())

Scripts handle what's deterministic (tag presence, public exposure checks). The agent handles what requires judgment (IAM least-privilege intent, cost-allocation rationale). The skill tells it exactly what your team cares about.

The Session Advantage

Once a skill loads in a session, it stays. After the agent processes your first PR using terraform-aws-review, it can answer follow-up questions about the findings without reloading anything. The skill's knowledge is already in context, persistent and ready.

When to Use Agents vs Skills

Start with one question: Am I solving an automation problem or a knowledge problem?

• Automation problem (doing): multi-step tasks, repeated workflows, integrations with external systems → use an Agent
• Knowledge problem (knowing): specialized instructions you keep repeating, domain expertise you want Claude to follow consistently → use a Skill
• Both? → use an Agent with a Skill

When to Use an Agent

• ✅ You need Claude to complete a multi-step task autonomously (find bugs, write a report, research a topic)
• ✅ You're building a production application with Claude as the decision-making engine
• ✅ You need parallel processing: spawn subagents to analyze files or check multiple sources simultaneously
• ✅ You need to connect to external systems (GitHub, Slack, databases via MCP)
• ✅ You want to automate something that runs on a schedule (CI/CD pipelines, daily reports, monitoring jobs)

When to Use a Skill

• ✅ You keep pasting the same instructions into every Claude conversation. That's your clearest signal
• ✅ You have a repeatable domain workflow (Terraform reviews, security audits, brand writing guidelines)
• ✅ You want to share expertise across your team: Team and Enterprise plans support workspace-wide skills
• ✅ You want to bundle deterministic scripts with instructions for reliable, code-driven operations
• ✅ You want to specialize an existing agent without rebuilding it from scratch

Quick Decision Table

Common Mistakes

Mistake 1: Building an agent when a skill is enough

If you only need Claude to follow consistent instructions, you don't need an agent. You need a SKILL.md. Agents add complexity: sessions, tool access, looping logic. Don't reach for that complexity until you actually need actions, not just knowledge.

Mistake 2: Putting too much into one skill

A skill should be focused: terraform-review, pdf-invoice-extractor, security-audit. If your SKILL.md tries to cover everything your team does, it will load too much context and the relevant parts will be diluted. Build narrow, composable skills, then compose them in the agent prompt.

Mistake 3: Giving agents too many tools

An agent with unrestricted access to Read, Write, Bash, WebFetch, and secrets is asking for trouble. Every tool you add is a surface area for unintended actions. Limit allowed_tools to the minimum the task requires, and explicitly exclude Bash when the task doesn't need it.

Mistake 4: No verification step

If the agent changes code, it must run the tests. If it generates a report, it must check the sources. If it performs a deployment, it must have an approval gate before the final action. An agent that returns "done" without verifying is not production-ready.

Real Examples You Can Try

Here are three working examples that span from beginner to advanced, followed by the fastest possible on-ramp if you'd rather not write any code at all.

Example 1: Find and Fix the Bug (Agent Only)

# pip install claude-agent-sdk==0.1.0
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

# The agent runs the full 3-phase loop automatically:
#   Phase 1 (Gather):  reads auth.py to understand the code
#   Phase 2 (Act):     edits the file with the fix
#   Phase 3 (Verify):  runs tests via Bash to confirm nothing broke
async def main():
    async for message in query(
        prompt="Find and fix the authentication bug in auth.py. Explain what you changed and why.",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"])
    ):
        if message.type == "result":
            print(message.content)

asyncio.run(main())

What the agent does: It reads auth.py, reasons about what's wrong, edits the file, then runs the tests to verify. If the fix breaks something else, it loops back and tries again. You didn't write any of that logic. The 3-phase loop handles it.

Example 2: Code Audit Agent + 3 Skills (Advanced)

# pip install claude-agent-sdk==0.1.0
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

# Each /skill-name triggers automatic Level-2 loading for that skill.
# All three skill contexts stack in session; the agent synthesizes
# their combined knowledge into one report at the end.
async def main():
    async for message in query(
        prompt="""
        Audit the payments/ directory:
        1. /code-reviewer     : check logic errors and code quality
        2. /security-auditor  : flag security vulnerabilities
        3. /performance-optimizer : identify bottlenecks
        Synthesize all findings into one prioritized report.
        """,
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep", "Bash"])
    ):
        if message.type == "result":
            print(message.content)

asyncio.run(main())

What happens: The agent loads each skill sequentially. Each adds specialized knowledge to the session context. They stack, not replace. After all three are loaded, the agent synthesizes one report acting simultaneously as a senior engineer, a security expert, and a performance specialist.

Example 3: Use Built-In Claude Code Skills Today

Claude Code ships with bundled skills you can invoke immediately, no code required:

• /code-review: comprehensive code review against best practices
• /debug: systematic debugging workflow
• /loop: run an agent in a continuous improvement loop
• /verify: verify that a task was completed correctly

In Claude Code, type /code-review on any open file and watch an agent + skill combination work together in real time. This is the fastest way to experience the pattern before writing any SDK code.

Before Using Agents in Production

• Auto-approve only the minimum required tools with allowed_tools, and explicitly block unsafe tools with disallowed_tools or a custom permission policy.
• Run agents in a dedicated workspace or sandbox, not your main development environment.
• Never expose secrets directly in files the agent can read.
• Add approval gates for destructive actions: deploy, delete, commit, send email.
• Log every tool call: agent loops are hard to debug without a trace.
• Require a verification step before returning success.
• Prefer deterministic scripts inside skills for repeatable operations rather than relying on the agent to re-derive the same logic each time.
• Version your skills like code. If a skill changes behavior, treat it like a code change.

What You Now Know

• Agent = autonomous executor. Takes action, loops, verifies.
• Skill = reusable knowledge package. Tells the agent how to handle a specific type of work.
• MCP = external reach. Connects the agent to databases, APIs, and SaaS tools.

You have the decision framework, the 3-phase loop, the skill loading model, and working code. Apply it the next time you're staring at a workflow you keep doing manually.

Your Next Steps

Start small. Turn one repeated prompt into a skill. Then use an agent only when the workflow needs tools, decisions, and verification across multiple steps.

Start with what's already there. Claude Code ships with built-in skills you can try right now. Type /code-review or /debug to see an agent and skill working together in real time.

Then build your own. When you find yourself pasting the same instructions into Claude for the third time, write a SKILL.md, drop it in .claude/skills/, and it's immediately available to any agent or Claude Code session.

Then automate. When you have a workflow you want running autonomously (gathering data, making decisions, taking action, verifying the result), install the Claude Agent SDK (pip install claude-agent-sdk) and wire up your first agent.

References

• Agent SDK Overview - Claude Code Docs
• Agent Skills Overview - Claude API Docs
• Building Agents with the Claude Agent SDK - Anthropic Engineering Blog
• Equipping Agents for the Real World with Agent Skills - Anthropic Engineering
• What Are Skills? - Claude Help Center
• Extend Claude with Skills - Claude Code Docs
• Claude Agent SDK Python - GitHub Repository