Claude Code skills vs agents: Differences, use cases, and how to choose

The core difference between Claude Code Skills and subagents comes down to reusable instructions versus delegated execution. A Skill packages guidance and resources to ensure consistent procedures, while a subagent executes tasks in a separate context with dedicated tools and permissions. Depending on your needs, you can use a Skill for standard workflows, a subagent to isolate execution, or both when a specialized role requires shared standards.

Claude Code skills vs agents at a glance

Claude Code Skills standardize how work should be performed. Claude Code subagents separate who performs delegated work and where its conversational working material accumulates. They are complementary, but neither automatically makes a workflow more reliable.

According to Anthropic's documentation, Claude Code Skills use progressive disclosure-loading detailed guidance only as needed rather than bundling all resources upfront. In contrast, subagents operate within separate working contexts with configurable execution roles.

Note that an isolated context simply means a distinct conversational thread, not guaranteed filesystem or security sandboxing. Proper configuration is critical: a Skill can leverage context: fork to execute via a subagent, and subagents should have required Skills explicitly assigned rather than relying on automatic inheritance.

Version-sensitive behavior: invocation controls, configuration fields, and permission interactions should be checked against your installed Claude Code version. The architecture example below is illustrative, not a tested release configuration.

What is a Claude Code skill?

A Claude Code Skill is a package of instructions and optional resources that Claude applies to a relevant task. It can describe procedures, reference material, tool usage, and expected output. The package supplies knowledge to an execution context; it is not an independent reasoning worker with its own ongoing assignment.

How a skill loads

The lifecycle below is a practical model, not an invariant internal execution trace:

1. Claude receives discovery information about available Skills.
2. Claude selects a relevant Skill, or the user invokes it explicitly.
3. The execution context loads the Skill’s instructions.
4. Supporting resources are accessed when relevant.
5. Claude applies the guidance in the configured execution context.

Loading flow: Discovery → selection or invocation → instructions → optional resources → application.

Anthropic’s Claude Code Skills documentation describes automatic discovery and slash invocation. Invocation controls include disable-model-invocation, which prevents automatic model invocation, and user-invocable, which controls user-facing slash availability. These controls serve different purposes.

What a skill contains

• SKILL.md: YAML frontmatter-metadata at the file’s top-followed by instructions.
• Operating standards: Rules, procedures, decision criteria, and output expectations.
• Optional resources: References, templates, examples, and executable scripts.

Useful examples include pull-request review standards, a release checklist, and B2B SEO content brief requirements.

Keep essential decisions in the main instructions. Put extensive examples and reference documents in supporting files, with clear directions for when to consult them.

Boundary: A Skill normally guides the current session, but supported configuration can arrange forked subagent execution. Adding a script does not make the entire Skill deterministic: Fixed behavior belongs to the script’s implementation, not to every model decision surrounding it.

What is a Claude Code agent or subagent?

A Claude Code subagent is a configured assistant that receives delegated work and executes it in a separate conversational context. Its definition can specify instructions, available tools, a model, and permission behavior. It is useful when an assignment benefits from focused investigation, reduced main-session clutter, or a distinct execution role.

A typical execution pattern is: Assignment → inspect → use permitted tools → evaluate evidence → return findings.

This is bounded multi-step task delegation, not unlimited autonomy. The main session can follow a similar loop without creating a subagent.

What separate context actually changes

An isolated context window absorbs intermediate work like repository searches and draft hypotheses, allowing the main session to receive a clean, high-level summary. For pull-request review, the reviewer might inspect related authorization code across several directories. The coordinating session needs the relevant evidence-not every unsuccessful search.

The trade-off is information loss at the handoff. A short report may omit assumptions, unresolved questions, or evidence needed to validate a finding. Specify those fields in the return format.

Separate context also does not guarantee lower total token use or a separate filesystem.

Tool permissions need concrete enforcement

Consider a reviewer intended only to inspect supplied files. Configure inspection tools, omit editing tools, and restrict access to shell, external write-capable tools, and deployment capabilities. A prompt saying “do not edit” is insufficient. An unrestricted shell can modify files even when a dedicated editing tool is absent.

Anthropic’s Claude Code subagent and permissions documentation distinguish tool availability from permission behavior. Verify both, including inherited settings. Another execution role adds coordination overhead. Short formatting rules or a small transformation rarely justify that overhead alone.

The five practical differences between skills and agents

Choose according to the missing capability, not the apparent sophistication of the architecture. Shared instructions and separate execution solve different problems.

Reusable knowledge vs delegated work

Reusable knowledge defines what a good review looks like: Severity levels, evidence requirements, and reporting conventions. Delegated work means assigning someone to inspect the change and return findings.

Start with a Skill when the missing piece is consistent guidance. Introduce a subagent when a separately managed assignment provides a concrete benefit.

Shared working context vs isolated context

A small review may benefit from staying beside the developer’s explanation, constraints, and previous decisions. A broad investigation may generate enough intermediate material to justify separation.

Use a subagent when that material creates a real burden. Include necessary background in the assignment; separate context should not mean context-starved execution.

Guidance vs multi-step execution

A Skill can guide the main session through reading a diff, checking callers, examining tests, and writing findings. Multiple steps do not require a specialist worker.

Choose delegation because the task needs execution separation, not because the checklist is long. A well-scoped main session may remain the clearest implementation.

Tool guidance vs role-specific tool configuration

Skill settings such as allowed-tools can influence tool authorization while the Skill is active. They should not be confused with a universal sandbox or assumed exclusive tool boundary.

A subagent offers role-specific configuration. Choose scoped permissions only after checking actual tool availability, permission settings, inherited behavior, and shell access.

Lower overhead vs the agent tax

Using subagents introduces an “agent tax'“ - the extra overhead of loading initial context, preparing assignments, dealing with latency, reviewing handoffs, and maintaining custom configurations.

Accept these costs when delegation improves focus, enables useful independent work, or separates responsibilities. More agents do not inherently produce better findings, and context isolation alone does not establish a cost advantage.

Before introducing another reviewer, identify the failure you expect it to prevent. “The main conversation is overwhelmed by test output” is actionable. “Agents are more advanced” is not.

When to use a skill, an agent, both or neither

Start with the simplest mechanism that meets the requirement; this decision framework treats all four outcomes as legitimate.

Use a skill

Use a Skill when repeated tasks need consistent instructions without a separate execution role. Examples include API review rules and SEO brief requirements covering audience, evidence, structure, and acceptance criteria. Keep the current session responsible for execution.

A Skill is particularly useful when the same procedure should survive changes in the person initiating the task.

Use an agent

Use a subagent for log-heavy test diagnosis or a focused investigation that should return findings instead of extensive intermediate output.

Independent competitor-research assignments can also fit. Give each researcher a clear scope and evidence requirements.

Parallel task execution is appropriate only when assignments are separable, supported by the execution environment, and worth the coordination cost.

Use both

Combine them when a specialist needs reusable standards. A security reviewer could receive shared severity definitions and a consistent findings format through a Skill, while its subagent configuration restricts review capabilities.

Explicitly supply the Skill to that role. Require human validation before acting on consequential security recommendations or approving deployment.

Use neither

A one-off question may need only a prompt. CRM (customer relationship management) data normalization may need a deterministic script with validation tests.

Use an event-driven hook for supported lifecycle automation. Use MCP (Model Context Protocol) for exposing external tools, resources, and related capabilities.

Scripts and MCP can also support Skills or subagents. Slash invocation may invoke a Skill rather than represent a separate alternative.

Six-item decision checklist

1. If guidance repeats, choose a Skill.
2. If investigation needs separate context, consider a subagent.
3. If a separate role needs different tool controls, consider a subagent.
4. If specialists need shared standards, choose both.
5. If fixed rules fully determine the transformation, choose a script.
6. If the task is simple and one-off, start with a prompt.

Decision tree: Reusable guidance only → Skill. Separate execution only → subagent. Both requirements → both. Neither requirement → simpler mechanism.

Apply this checklist to one current task before adding components. Record the requirement that justifies each choice.

Practical architecture example: Pull-request review

Consider a B2B SaaS (software-as-a-service) repository with a reviewable pull-request diff. Every option below uses identical severity definitions and the same findings format:

Severity | file and line | evidence | impact | suggested action | uncertainty.

The task is review only. No option authorizes automatic merging or deployment.

For the combined option, configure the pull-request review agent to receive the shared Skill through the subagent’s supported skills setting. Anthropic’s subagent documentation describes this as preloading Skill content into the subagent’s context. That differs from assuming the specialist automatically inherits everything available to the parent session.

Conceptual architecture:

Main session ── delegates review ──> Review subagent
↑
Shared Skill ── supplies standards ────┘
│
├── reads ──> Repository files
│
Main session <── returns findings ──────┘

The Skill supplies standards. The subagent performs the review and returns findings.

Illustrative example, not a benchmark: No execution test, Claude Code version, model, configuration revision, or actual output is reported here. Proposed access is repository inspection without editing, shell execution, or deployment tools; effective restrictions require validation.

A meaningful comparison would record those details, the identical input diff, actual findings, and review effort for each option. Evaluate evidence quality and missed issues-not merely response length. Human review remains necessary for consequential changes.

Common architecture mistakes and where other Claude Code components fit

The most useful architecture prevents duplicated instructions, unnecessary execution roles, and excessive access. Components can coexist without becoming interchangeable.

• Creating an agent for static reference material: Prefer a Skill or reference file when separate execution adds no value. A standards document does not need its own worker.
• Duplicating common rules: Centralize shared definitions and explicitly supply them to relevant roles. Duplication creates a maintenance risk, although instruction drift is not inevitable.
• Granting broad tool access: Apply least privilege: provide only the capabilities necessary for the task. Inspect effective permissions, including shell commands and external integrations.
• Assuming more agents improve quality: Evaluate task independence, coordination cost, latency, and human review effort. Avoid concurrent edits to shared files without a conflict-management plan.
• Presenting a personal structure as official: Distinguish documented Claude Code behavior from team conventions and AgentKit recommendations. A useful organizational pattern is not a product-enforced hierarchy.

Where adjacent components belong: Anthropic’s Claude Code Skills, plugins, and hooks documentation explain these neighboring mechanisms. The Model Context Protocol documentation defines the connectivity layer.

Custom commands and Skills are related: Claude Code documentation describes custom slash commands as merged into Skills, with existing command files continuing to work.

Plugins are not inherently workers. MCP does not automatically authorize access or supply workflow reasoning. Scripts can run within larger workflows, while hooks require careful attention to the commands and permissions they execute. Treat third-party instructions and scripts as software dependencies-not automatically trusted text.

Frequently asked questions

What is the fundamental difference between Claude Code Skills and Agents?

A Claude Code Skill is a passive package of reusable instructions and resources that guides how Claude handles a specific domain task. In contrast, an Agent (or Subagent) is an active, autonomous execution loop that manages its own context window and performs multi-step tasks independently.

Can a Claude Code Skill be used to replace a Subagent?

No. A Skill provides domain-specific knowledge and procedural guidance but lacks its own execution context. If a task requires complex, multi-step investigation that would pollute your main conversation window, a Subagent is necessary to provide the required context isolation.

When should I use both Skills and Agents together?

You should combine them when you need to delegate a complex task (requiring an Agent) that must strictly follow specific team standards or data-normalization rules (provided by a Skill). This architecture allows you to maintain consistency while keeping your primary workspace clean and focused.

Do Claude Code Subagents automatically inherit all of my available Skills?

Not necessarily. While Skills can be shared, they must be explicitly configured or preloaded into the Subagent’s context to ensure they are available for use. Relying on assumed inheritance can lead to unpredictable behavior; always verify the configuration for each isolated role.

Why does using an Agent or Agent Team cost more tokens than a single session?

Agents and Agent Teams operate in isolated context windows, requiring the model to maintain separate internal states, perform independent reasoning loops, and generate redundant summary handoffs. Anthropic documentation indicates that multi-agent orchestration can consume significantly more tokens than a single-agent session focused on the same goal.

Is a Claude Code Skill the same as a System Prompt?

No. A System Prompt is static text loaded once at the start of a session. A Skill is a modular, file-based component that uses progressive disclosure; Claude dynamically loads the full content of a Skill only when it determines that the Skill is relevant to the current task.

How do I decide if a task is too simple for an Agent?

If your task involves straightforward, repeatable actions-such as formatting a commit message or generating a standardized document-start with a Skill. Avoid the "agent tax" of coordination overhead, increased latency, and higher token consumption unless the task truly requires autonomous, multi-step problem solving.

Read more:

• Claude Code AGENTS.md vs CLAUDE.md: The official guide
• Claude Code /skills guide: Master reusable developer workflows
• Claude Code specialized agents: Boost your coding efficiency

Conclusion

The choice between Claude Code Skills and subagents comes down to your immediate need: Use a Skill for reusable guidelines, a subagent for isolated execution or role-specific controls, both when a specialist requires shared standards, or neither if a simpler prompt, script, or hook is sufficient. Always start with the simplest setup on a real task and add delegation or complexity only when supported by clear operational needs.