RSS 中文
⌕

Chapter 14 | What is a Subagent

5 MIN READ | UPDATED: 2026-05-15

Chapter 14: What is a Subagent

Learning Objectives

Understand the relationship between subagents and main Claude, and know the cost and value of dispatching.

Key Facts Checklist

flowchart TB
    MC["main Claude
(You converse with it)"] -->|Agent Tool| SA["subagent
(Dispatched)"]

    SA --> F1["Independent Context
(Cannot see main conversation)"]
    SA --> F2["Model selected by frontmatter
(Can differ from main)"]
    SA --> F3["Independent Toolset
(Can be restricted)"]
    SA --> F4["Returns only text upon completion
(No tool history)"]

    style MC fill:#bbdefb
    style SA fill:#fff9c4

Lifecycle of a Dispatch

sequenceDiagram
    participant U as User
    participant MC as main Claude
    participant SA as subagent

    U->>MC: Make Group 3 run
    MC->>SA: dispatch developer
+ briefing prompt
    Note over SA: cold start
Reads frontmatter
Loads system prompt
    SA->>SA: Reads project files
    SA->>SA: Modifies code
    SA->>SA: commit
    SA->>MC: Completion report (text)
    Note over MC: Doesn't know which tools SA used
Only sees the final summary
    MC->>U: Group 3 completed

Key = "Cold Start"

✗ Subagents don't know what you discussed with main Claude previously
✗ Subagents don't know implicit project conventions unless you tell them
✗ Subagents don't automatically read CLAUDE.md (requires Claude Code configuration)
✓ Subagents read their system prompt (from .claude/agents/<name>.md)
✓ Subagents read the briefing prompt (the message main Claude gives them)

→ Briefings must be self-contained—include all necessary context.

Directory Conventions

Project-level:  <project>/.claude/agents/<name>.md      Project-specific, shared by team
User-level:  ~/.claude/agents/<name>.md               Account-specific, available across all projects

→ Use project-level agents for project-specific tasks, and user-level agents for general-purpose tasks.

Subagent vs. Skill vs. Slash Command

Concept What it is Who triggers it Example
subagent A system prompt + toolset, can be dispatched main Claude using Agent Tool developer.md
skill A standardized process, can be called by main Claude main Claude using Skill Tool opsx:propose
slash command A prompt template triggered by user input User types /xxx /dev

The three work together: User types /dev (slash command) → main Claude dispatches the developer (subagent) according to rules → the developer might use a skill internally.

Cost of Dispatch

Each dispatch ≈ a new session start
- Reading system prompt: costs 1k~10k tokens
- Reloading project-related files: costs 5k~50k tokens
- Model inference: billed by input/output

→ Avoid dispatching for minor tasks. Too fine-grained = wasted money. Group-level dispatch (as designed in our dev.md) offers the best cost-effectiveness.

What You Can Do Now

  • Explain the differences between subagent / skill / slash command
  • Understand why briefings must be self-contained
  • Estimate the cost of a single dispatch

The next chapter covers designing roles—the soul of a multi-agent system.