subagents-vs-skills

Research Date: 2025-11-04

Overview

Claude Code provides two distinct extensibility mechanisms for specialized capabilities: Sub-Agents and Skills. While they may seem similar at first glance, they serve different purposes and operate in fundamentally different ways.

Sub-Agents

What They Are

Sub-agents are specialized AI assistants that Claude Code can delegate tasks to. Think of them as independent AI personalities, each with their own:

• Separate context window
• Custom system prompt
• Configurable tool access
• Specific domain expertise

Key Characteristics

Delegation Model: Sub-agents operate as separate entities that handle tasks independently and return results to the main conversation.

Invocation: Can be triggered in two ways:

1. Automatically - Claude decides when a task matches a sub-agent’s expertise
2. Explicitly - User or Claude requests a specific sub-agent by name

Configuration: Defined as Markdown files with YAML frontmatter stored in:

• .claude/agents/ (project-level, team-shared)
• ~/.claude/agents/ (user-level, personal)

Configuration Structure

---
name: agent-identifier
description: When and why this agent should be used
tools: Tool1, Tool2, Tool3  # Optional - restricts tool access
model: sonnet  # Optional - defaults to sonnet
---

System prompt describing the agent's role and behavior

Use Cases

• Specialized expertise: Code review, debugging, security analysis
• Context preservation: Keeps main conversation focused on high-level objectives
• Security: Grant specific tools only to specific sub-agents
• Reusability: Share configured sub-agents across projects and teams
• Complex workflows: Parallel processing of independent tasks

Examples

• Code reviewer that analyzes PRs
• Test generator that creates comprehensive test suites
• Diagram generator that creates architecture visualizations
• Collaboration analyst that tracks development patterns

Skills

What They Are

Skills are modular capabilities that extend Claude’s functionality through organized folders containing:

• A SKILL.md file defining the skill
• Optional supporting resources (scripts, templates, etc.)

Key Characteristics

Invocation Model: Skills are model-invoked - Claude autonomously decides when to use them based on context and the skill’s description. This is a critical difference from:

• Slash commands (user-invoked with /command)
• Sub-agents (explicitly or automatically delegated)

Discovery: Claude automatically discovers and activates skills when they’re contextually relevant to your request.

Storage Locations:

• ~/.claude/skills/ - Personal skills for individual workflows
• .claude/skills/ - Project skills shared with teams via git
• Plugin skills - Bundled with installed plugins

Configuration Structure

# SKILL.md structure
---
description: Critical field that helps Claude discover when to use the skill
---

Detailed instructions on how to execute the skill

Use Cases

• Team collaboration: Share expertise across teams via git
• Workflow automation: Reduce repetitive prompting for common tasks
• Capability extension: Customize Claude for specific workflows
• Complex problem-solving: Compose multiple skills together
• Consistent patterns: Enforce team conventions automatically

Examples

• PDF processing skill that extracts and analyzes content
• Database migration skill that handles schema changes
• Documentation generation that follows team standards
• API endpoint creation following architectural patterns

Key Differences

When to Use Which?

Choose Sub-Agents When:

• Task requires specialized, isolated expertise
• You need parallel processing of independent work
• Security requires restricted tool access
• Task needs its own context window to avoid cluttering main conversation
• You want to specify a different model for specific tasks
• Building reusable AI personalities for your team

Choose Skills When:

• Automating repetitive workflows
• Encoding team conventions and patterns
• Extending Claude’s capabilities for specific domains
• Creating discoverable, composable capabilities
• Reducing need to repeat similar prompts
• Building expertise library for team collaboration

Integration Patterns

Commands and skills can orchestrate sub-agents (but sub-agents cannot call other sub-agents or skills):

Pattern 1: Command Orchestration

1. User invokes command (/build-feature)
2. Command delegates to sub-agents for specialized work
3. Sub-agents execute in isolated contexts
4. Results return to command which continues the workflow

Example: A /build-api command might delegate to a “code-generator” sub-agent for implementation, then to a “test-generator” sub-agent for tests.

Pattern 2: Skill Orchestration

1. Claude discovers skill based on user request
2. Skill invokes sub-agents for specialized processing
3. Sub-agents process their respective tasks
4. Results return to skill which completes the workflow

Example: A “feature-implementation” skill might invoke a “test-generator” sub-agent to create comprehensive tests, then continue with implementation.

Pattern 3: Skill Composition

1. Skill A is discovered for a task
2. Skill A invokes Skill B for a sub-task
3. Both skills collaborate to complete the workflow

Example: An “api-endpoint” skill might invoke a “validation-pattern” skill to ensure proper input validation.

Configuration Examples

Sub-Agent Example

---
name: security-auditor
description: Performs security analysis on code changes, checking for OWASP vulnerabilities
tools: Read, Grep, Glob, WebFetch
model: sonnet
---

You are a security expert focused on identifying vulnerabilities.
Analyze code for: SQL injection, XSS, CSRF, authentication issues...

Skill Example

---
description: Generate REST API endpoints following team architecture patterns
---

# API Endpoint Generation Skill

When generating API endpoints:
1. Check existing patterns in src/api/
2. Follow team conventions for error handling
3. Include input validation
4. Add comprehensive tests
5. Update API documentation

References

• Claude Code Sub-Agents Documentation
• Claude Code Skills Documentation
• Claude Code Documentation Map

Can Sub-Agents Use Skills or Other Sub-Agents?

TL;DR: No. Based on testing, sub-agents CANNOT execute skills or other sub-agents.

Tested Behavior (2025-11-04)

Sub-Agents CANNOT execute:

• ❌ Other sub-agents
• ❌ Skills

Commands CAN execute:

• ✅ Sub-agents (via Task tool)
• ✅ Skills (via Skill tool)

Skills CAN execute:

• ✅ Other sub-agents (via Task tool)
• ✅ Other skills (via Skill tool)

Architecture Hierarchy

┌─────────────────────────────────────┐
│   Main Claude Conversation          │
│   - Can invoke commands (/)         │
│   - Can invoke skills (auto)        │
│   - Can invoke sub-agents (Task)    │
└─────────────────────────────────────┘
           │
           ├──────────────────┬──────────────────┐
           │                  │                  │
      ┌────▼────┐      ┌──────▼──────┐    ┌─────▼──────┐
      │Commands │      │   Skills    │    │ Sub-Agents │
      │  (/)    │      │ (auto-disc) │    │   (Task)   │
      └────┬────┘      └──────┬──────┘    └─────┬──────┘
           │                  │                  │
           │ Can invoke:      │ Can invoke:      │ Can invoke:
           │ • Sub-agents ✅  │ • Sub-agents ✅  │ • Nothing ❌
           │ • Skills ✅      │ • Skills ✅      │
           └──────────────────┴──────────────────┘

What This Means

Sub-Agents are “Leaf Nodes”:

• Sub-agents are terminal executors in the call hierarchy
• They handle tasks independently but cannot delegate further
• They have access to basic tools (Read, Write, Bash, Grep, etc.) but not orchestration tools (Task, Skill)

Commands and Skills are “Orchestrators”:

• Both can compose workflows by delegating to sub-agents and skills
• They sit higher in the execution hierarchy
• They enable complex multi-step automation

Practical Implications

❌ This Won’t Work:

# Sub-agent trying to use skills
---
name: feature-builder
description: Build complete features
tools: Read, Write, Skill  # Skill tool won't work in sub-agents
---

✅ This Will Work:

<!-- Slash command that orchestrates -->
---
description: Build complete features
---

Use the "api-pattern" skill to get team conventions.
Then delegate to the "code-generator" sub-agent to implement.
Finally use the "test-generator" sub-agent to create tests.

Corrected Integration Patterns

Pattern 1: Command → Sub-Agent

User types: /build-feature auth
  ↓
Command executes
  ↓
Delegates to "feature-builder" sub-agent
  ↓
Sub-agent implements using basic tools
  ↓
Returns to command → Returns to user

Pattern 2: Skill → Sub-Agent

Main Claude detects need for feature implementation
  ↓
Discovers "feature-implementation" skill
  ↓
Skill orchestrates by delegating to sub-agents
  ↓
Sub-agents execute their specialized tasks
  ↓
Returns to skill → Returns to main Claude

Pattern 3: Command → Skill → Sub-Agent

User types: /complex-workflow
  ↓
Command invokes skill for orchestration logic
  ↓
Skill delegates to multiple sub-agents
  ↓
Sub-agents execute in parallel/sequence
  ↓
Results flow back through skill → command → user

Design Implications

For Sub-Agents:

• Keep them focused and specialized
• Don’t expect them to orchestrate complex workflows
• Use them as expert executors for specific tasks
• Provide clear, complete system prompts

For Orchestration (use Commands or Skills):

• Use commands for user-invoked workflows
• Use skills for auto-discovered patterns
• Both can compose multiple sub-agents
• Both can leverage other skills

Why This Design Makes Sense

1. Separation of Concerns: Sub-agents focus on execution; commands/skills handle orchestration
2. Prevents Recursion Issues: Avoids infinite loops of agents calling agents
3. Clear Hierarchy: Simpler mental model for building workflows
4. Context Management: Prevents deeply nested contexts
5. Performance: Limits the depth of agent delegation chains

Notes

• Description is critical: For both sub-agents and skills, the description field determines when they’re activated
• Tool restriction: Sub-agents can have restricted tool access for security; skills use whatever tools are available
• Context management: Sub-agents help manage context by processing tasks separately
• Team sharing: Both can be shared via git in project directories
• Plugins: Can bundle both sub-agents and skills for distribution
• Execution hierarchy: Sub-agents are leaf nodes and CANNOT invoke skills or other sub-agents (tested 2025-11-04)
• Orchestration: Use commands or skills when you need to compose multiple sub-agents or skills together