title: "What's the Difference Between a Claude Code Skill and an Agent?" description: "Skills run defined processes. Agents make decisions and use tools. Here is exactly where the boundary falls and when each one is the right choice." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "claude-agents", "agents-vs-skills"] cluster: 2 cluster_name: "Skills vs Agents vs Prompts" difficulty: beginner source_question: "What's the difference between a Claude Code skill and an agent?" source_ref: "2.Beginner.2" word_count: 1440 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What's the Difference Between a Claude Code Skill and an Agent?

Quick answer: A Claude Code skill executes a defined, linear process that is fully specified before the run starts. An agent makes decisions at runtime, uses external tools, and routes based on what it finds. Skills are for workflows with deterministic paths. Agents are for tasks where the path depends on tool output you cannot know in advance.

What Is a Claude Code Skill?

A Claude Code skill is a SKILL.md file that defines one repeatable task. It specifies the trigger, the step-by-step process, and the output format. Claude reads it and follows it. The path through the skill does not change based on external conditions.

A commit message skill always runs the same sequence: read the staged diff, generate a conventional commits message, present it for review. A code review skill always reads the files, checks against the defined criteria, and produces a structured report. The process is fully specified. There is nothing to decide at runtime.

Skills handle the majority of workflows developers use Claude for:

  • Code generation
  • Code review
  • Commit messages
  • PR descriptions
  • Test writing
  • Refactoring
  • Documentation
  • Data formatting
  • Report compilation

These tasks have defined paths. They do not require tool calls that return unpredictable output.

What Is a Claude Code Agent?

An agent is an autonomous process that uses tools and branches based on what those tools return. The path through an agent cannot be fully specified before execution. The agent reads a result, decides what to do next, and proceeds accordingly.

Agents use Claude Code tools like WebFetch, Bash, or MCP-connected external services. They can spawn sub-agents for parallel work. They can stop, evaluate intermediate results, and take different paths depending on what they find.

A research agent that searches three sources, decides which results are relevant, follows cited links, and synthesizes a final report is a genuine agent. The intermediate decisions depend on what the web search returns. No amount of pre-specification fully determines the path.

Where Is the Boundary Between a Skill and an Agent?

The boundary is where the process stops being deterministic. A workflow is a skill when every step can be fully described before execution starts. It becomes an agent when the next step depends on tool output that cannot be pre-specified. If you can write out all the steps before running, it is a skill.

A workflow is deterministic when every step can be fully described before execution starts. The inputs change but the process does not. A commit message skill is deterministic: the diff input changes, but the process is always the same sequence.

A workflow is non-deterministic when the next step depends on tool output that cannot be pre-specified. If step 3 is "decide whether to continue based on what the search returned," you have crossed into agent territory.

"LLMs perform worse as context expands. This isn't just about hitting token limits — the more information in the context window, the harder it is for the model to focus on what matters right now." — Addy Osmani, Engineering Lead, Google (2026, https://addyosmani.com/blog/claude-code-agent-teams/)

An agent that has no external tool calls and makes no branching decisions based on runtime output is a skill with extra overhead. The file format may say "agent," but the function is a skill. Building it as an agent costs you the 4.6x token coordination overhead documented for multi-agent architectures (Source: Anthropic internal benchmarking, 2026) without any of the benefits.

In AEM's production skill builds, we've found that the majority of workflows initially scoped as agents turned out to be skills once the conditional branches were written out. The branching that appeared to require runtime decision-making was fully specifiable before execution in all but a small number of cases.

When Does a Task Actually Require an Agent?

A task actually requires an agent when it uses external tools, and the output of those tools determines what the task does next in ways that cannot be pre-specified. The three conditions below all have to be true simultaneously — failing any one of them means a skill is sufficient.

A task needs an agent when all three of the following are true:

  1. The task requires external tool calls (web search, database query, file system access, API calls)
  2. The output of those tools determines what happens next
  3. The resulting paths cannot be fully pre-specified as conditional branches in a skill

Most tasks fail at condition 2 or 3. A code review task that calls a linter tool and includes the linter output in its report is not necessarily an agent task. The path is still deterministic: run linter, include output, format report. The tool call does not change the structure of the process.

A task genuinely needs an agent when the tool output reveals unexpected structure that changes the nature of the work, when branching paths are too numerous to enumerate in advance, or when the task requires iterative refinement based on intermediate results that cannot be predicted.

Anthropic's own documentation explicitly describes agentic systems as a last resort: they are more complex and more expensive than well-designed skills for most tasks (Source: Anthropic Claude Code documentation, 2026).

Before building an agent, check whether conditional skill logic covers the branching. A skill with three conditional paths is simpler, faster, and cheaper than an agent. In practice, most workflows that feel non-deterministic at first pass resolve correctly as conditional skills once the branching logic is written down explicitly.

What Does a Combined Skill-Agent Architecture Look Like?

In a combined architecture, skills handle the deterministic phases of a workflow and agents handle the non-deterministic phases. The choice is not "pick one" — it is placing the boundary correctly so each tool operates in the zone where it has an advantage over the other.

Skills and agents work together in production systems. The choice is not "pick one" but "use each where it fits."

A typical production architecture:

  • Skills handle the deterministic phases: formatting, code generation, documentation, structured output production
  • Agents handle the non-deterministic phases: research, live data retrieval, adaptive workflows where inputs change the path

The boundary is placed where the workflow stops being deterministic. Everything before that boundary is a skill. Everything after it gets evaluated: is an agent actually required, or does a well-structured conditional skill cover it?

Take a research-and-report workflow. An agent retrieves and synthesizes the source material, genuinely non-deterministic, depends on web content. A skill then formats and delivers the final report, fully deterministic, defined output structure. Each tool does what it is built for. In practice, extracting the deterministic tail of a pipeline into a skill rather than keeping it in the agent reduces token overhead for that phase while making the output contract explicit and testable.

For a complete breakdown of this decision across all Claude Code tool types, see Claude Code Skills vs Agents vs Prompts: When to Use Which.

For the specific distinction between skills and prompts, see What's the Difference Between a Claude Code Skill and a Prompt?.

FAQ

Can a Claude Code skill call other skills or spawn subagents?

Yes — a skill can reference other skills by name and chain them in sequence, or instruct Claude to spawn a subagent via the Task tool. A skill can reference other skills by name and instruct Claude to invoke them in sequence. A skill can also instruct Claude to use the Task tool to spawn a subagent, provided Claude Code is configured with the required permissions. The skill does not execute code directly. It instructs Claude, which then takes the described actions.

When should I use a subagent instead of a skill?

Use a subagent when a sub-task is genuinely independent of other sub-tasks, benefits from parallel execution, and requires runtime decision-making that a skill cannot provide. Use a skill when the sub-task has a defined, pre-specifiable path. A coding task that requires multiple independent file edits might use parallel subagents for speed. A code review task with a defined checklist should be a skill.

Is it better to have one complex skill or several simple ones?

One well-structured skill is better for tasks with a single clear scope. Split into multiple skills when trigger conditions differ, when a single file exceeds 500 lines, or when task domains are unrelated enough that loading both creates noise. Three simple skills are not inherently better than one complex one.

What's the economic tradeoff between a skill and a multi-agent system?

Multi-agent systems carry a documented 4.6x token overhead vs single-agent equivalents (Source: Anthropic internal benchmarking, 2026). Skills avoid this entirely. The tradeoff is justified when parallelization provides a proportional gain and the task genuinely requires tool-dependent branching. For most workflows, the overhead is not justified.

When should I use an MCP tool vs encoding logic in a skill?

Use an MCP tool when the capability does not exist in Claude Code natively: browser access, database queries, external API integrations, file system access beyond the project. Encode logic in a skill when the work is instruction-based and Claude can execute it with its built-in tools. MCP tools extend what Claude can do. Skills define how Claude does it.

Last updated: 2026-04-13