Skill + Agent Pattern

Subagents handle context-heavy subtasks for orchestrator skills. Each runs in isolated context, performs work, and returns results (or modifies files directly).

Why Subagents

The orchestrator's context window is limited. Loading a skill, conversation history, and project context already consumes significant space. If the orchestrator opens many files, runs extensive analysis, or generates verbose output, context fills up and quality degrades.

Solution: Delegate heavy work to subagents. Each runs in isolated context, performs its task, and returns a structured result. The orchestrator receives only what it needs.

Impact: According to Anthropic research, multi-agent systems with Claude Opus orchestrator and Claude Sonnet subagents outperform single-agent Claude Opus by 90.2% on research tasks.

Orchestration Rules

Subagents cannot call other subagents — Claude Code supports only one level of orchestration. Nested calls fail silently:

Orchestrator (main skill)
    ├── code-reviewer (subagent) ✓
    ├── security-auditor (subagent) ✓
    └── test-reviewer (subagent) ✓

code-reviewer
    └── another-agent ✗ FORBIDDEN

If subagent needs more work → return to orchestrator → orchestrator launches another subagent.

When to Use Subagents

Inline Agents (Ad-hoc Tasks)

For simple, one-off tasks — use Task tool with built-in subagent types:

Use Explore subagent to find all files related to authentication
Use general-purpose subagent to analyze the error and suggest fixes
Use Plan subagent to design implementation approach for {feature}

The orchestrator calls Task tool with arbitrary prompt and subagent_type. No agent file needed.

Built-in subagent types:

• Explore — fast codebase exploration, file search, pattern matching
• general-purpose — flexible tasks, research, analysis
• Plan — designing implementation approaches

When to use:

• Simple research/exploration
• One-off file operations
• Tasks under 50 lines of instructions
• No reuse needed

Dedicated Agents (Skill + Agent Pattern)

For complex, reusable tasks — create Skill + Agent pair:

1. Skill — holds methodology (WHAT to do, HOW to analyze)
   • Usable inline via /skill-name
   • Contains knowledge
2. Agent — adds isolation + output contract
   • Uses skills: to preload methodology
   • Defines output: JSON, file changes, or actions
   • Runs in isolated context

Example:

# skills/code-reviewing/SKILL.md — methodology
---
name: code-reviewing
description: Code review methodology and quality standards.
---
## What to Check
- Architecture, error handling, edge cases...

## Severity Levels
- Critical, Major, Minor...

# agents/code-reviewer.md — isolation + format
---
name: code-reviewer
description: Review code quality after implementation.
color: blue
skills:
  - code-reviewing    # Full SKILL.md content loaded
allowed-tools: Read, Glob, Grep
---
Follow code-reviewing methodology.

## Output
{ "findings": [...], "summary": {...} }

Benefits:

• Methodology usable inline (/code-reviewing) OR in isolation (via agent)
• Multiple agents can run in parallel
• No methodology duplication — skill is single source of truth
• Agent adds structure (output contract) without bloating skill

Agent File Format

Agent files use YAML frontmatter + Markdown body. Store in ~/.claude/agents/{name}.md.

---
name: agent-name
description: |
  When Claude should delegate to this agent. Include:
  - Purpose and capabilities
  - Example triggers
  - What NOT to use it for
color: blue
skills:
  - methodology-skill
allowed-tools: Read, Glob, Grep
---

# Agent Instructions

## Input
[What the agent receives from the orchestrator]

## Process
[Step-by-step methodology — or reference preloaded skill]

## Output
[Output contract: JSON schema, file changes, or actions]

Required Fields

Color Recommendations

All agents must have a color for visual identification. Valid values: red, blue, green, yellow, purple, orange, pink, cyan.

Optional Fields

Output Contracts

Agents always return JSON report — even if they modify files or execute commands. Work is the process, output is the report.

Analysis agents — findings and recommendations:

{
  "status": "approved" | "changes_required",
  "findings": [...],
  "summary": "..."
}

Executor agents — report of changes made:

{
  "status": "success" | "partial" | "failed",
  "files_modified": ["path/to/file.ts", ...],
  "files_created": ["path/to/new.ts", ...],
  "summary": "Created 2 files, modified 3 files"
}

Automation agents — report of actions taken:

{
  "status": "success" | "failed",
  "actions": ["ran tests", "deployed to staging"],
  "results": {...},
  "errors": []
}

Resuming Agents

After agent completes, orchestrator receives agentId. Use it to continue work with same context:

Resume agent {agentId} to ask follow-up question about findings

When to resume:

• Need clarification on agent's findings
• Iterative refinement (agent found X, now do Y based on X)

When NOT to resume (start fresh):

• Different task, unrelated to previous
• Context would confuse agent
• Previous work is complete, new work begins

Writing Effective Descriptions

The description field is critical — Claude uses it to decide when to delegate. Include:

1. Purpose — what the agent does
2. Triggers — when to use (with examples)
3. Exclusions — what NOT to use it for

Example from code-reviewer:

description: |
  Use this agent when code has been written or modified and needs quality assessment.

  **Examples of when to use:**
  - After implementing a feature
  - After refactoring code
  - Before committing changes

  **Proactive usage**: Invoke automatically after any code implementation task.

Invoking from Skills

Reference agents by name in skill workflow:

## Post-work

1. **Run Reviews** (launch in parallel)
   - `code-reviewer` — quality, architecture, patterns
   - `security-auditing` — OWASP Top 10, vulnerabilities

2. **Process Findings**
   Evaluate each finding on merit — severity is metadata, not a filter.
   - Valid, improves result → apply (any severity)
   - Disagree or uncertain → discuss with user
   Log each finding with action taken.

For agents needing specific input:

Use `code-reviewer` subagent with:
- files: {list of modified files}
- userspec: {user requirements document}
- techspec: {technical specifications}

Best Practices

1. Define clear output contract — JSON for analysis, file changes for executors
2. Restrict tools — Most agents only need Read, Glob, Grep
3. Use model: inherit — Ensures maximum quality from orchestrator's model
4. Always preload skill — Agent must have methodology, not just output format
5. Include examples in description — Helps Claude know when to invoke
6. One level of orchestration — Subagents cannot call other subagents

Example Agents

See existing agents for full examples:

• ~/.claude/agents/code-reviewer.md — Detailed methodology with review dimensions
• ~/.claude/agents/security-auditor.md — OWASP-based security analysis
• ~/.claude/agents/skill-checker.md — Skill validation against standards

References

• Create custom subagents - Claude Code Docs
• Multi-agent research system - Anthropic