---

name: create-sub-agent description: >- This skill should be used when the user asks to "create a sub-agent", "build an agent", "make a new agent", "scaffold an agent", "design an agent", "set up a worker agent", "create a specialist agent", "add a custom agent", "建立子代理", "建立 agent", "新增 agent", mentions sub-agent creation, agent design, agent scaffolding, agent configuration, or custom agent setup for Claude Code. version: 0.1.0 tools: Read, Glob, Grep, Bash, Edit, Write argument-hint: "<agent name or purpose>"

Create Sub-Agent for Claude Code

Guide the creation of well-designed sub-agents — specialized AI workers that run in isolated context windows with specific model, tool, and permission constraints.

Sub-agents are Markdown files at ~/.claude/agents/ (user-level) or .claude/agents/ (project-level). The filename becomes the agent name. Frontmatter defines constraints; the body becomes the system prompt.

When to Create a Sub-Agent vs. a Skill

| Signal | Create Sub-Agent | Create Skill | |--------|-----------------|-------------| | Need isolated context (prevent pollution) | Yes | No | | Need specific model (haiku for speed, opus for quality) | Yes | Skill also has model but less precise | | Need tool sandboxing (read-only, no-bash) | Yes | Skill has allowed-tools but agent is stricter | | Need persistent memory for the agent | Yes (memory field) | No | | Need reusable knowledge/procedures | No — use a skill | Yes | | Need supporting files (e.g. helper scripts) | No — load a skill into the agent | Yes |

Best practice: Create a sub-agent that loads skills via the skills field. The agent defines WHO does it (model, tools, permissions); skills define HOW.

Pre-Creation Assessment

Before creating any agent, check for overlap:

# List existing agents
ls ~/.claude/agents/ .claude/agents/ 2>/dev/null

# List existing skills that might already cover this
ls ~/.claude/skills/ | head -30

Ask: "Does this need an isolated context and specific constraints, or is a skill enough?"

Agent Creation Workflow

Phase 1: Define the Agent

Collect from the user:

1. Name: kebab-case, descriptive (e.g., code-reviewer, security-scanner)
2. Purpose: What task does this agent handle?
3. Read/Write: Does it need to modify files, or just read?
4. Quality tier: Is speed or accuracy more important?

Phase 2: Select Model

Use the model decision tree:

Task needs to modify code?
├── No (read-only / analysis)
│   ├── Simple (search, classify, summarize) → haiku
│   └── Complex (security audit, architecture review) → sonnet or opus
└── Yes (writes/edits files)
    ├── High-risk (production, security-related) → opus
    ├── Standard development → sonnet
    └── Mechanical (formatting, simple edits) → haiku

Quick reference:

| Task Type | Model | Cost | Speed | |-----------|-------|------|-------| | Codebase search/exploration | haiku | $ | Fast | | Classification / routing | haiku | $ | Fast | | Log analysis / summarization | haiku | $ | Fast | | Lint / format checking | haiku | $ | Fast | | Code review (read-only) | sonnet | $$ | Medium | | Bug debugging | sonnet | $$ | Medium | | Test generation | sonnet | $$ | Medium | | Refactoring | sonnet | $$ | Medium | | Documentation writing | sonnet | $$ | Medium | | Architecture design | opus | $$$ | Slow | | Security audit | opus | $$$ | Slow | | Complex multi-step reasoning | opus | $$$ | Slow | | Production-critical code gen | opus | $$$ | Slow |

For full model details, see references/model-guide.md.

Phase 3: Configure Tools

Apply the principle of least privilege:

| Agent Role | Recommended Tools | |-----------|------------------| | Explorer (read-only) | Read, Glob, Grep | | Reviewer (read + report) | Read, Glob, Grep, Bash | | Worker (can modify files) | Read, Glob, Grep, Edit, Write, Bash | | Researcher (web access) | Read, Glob, Grep, Bash, WebSearch, WebFetch | | Full access (trusted) | (omit tools to inherit all) |

Use disallowedTools to deny specific tools:

disallowedTools: Write, Edit    # can read but not modify

Phase 4: Configure Permissions

| Permission Mode | Use When | |----------------|----------| | default | Standard interactive use | | plan | Read-only exploration mode | | acceptEdits | Trusted worker, auto-accept file changes | | dontAsk | Strict deny-by-default, only allowed tools work |

Phase 5: Scaffold

Run the initialization script:

python3 ~/.claude/skills/create-sub-agent/scripts/init_agent.py <agent-name> \
  [--scope user|project] \
  [--model haiku|sonnet|opus] \
  [--role explorer|reviewer|worker|researcher|full]

Default: --scope user --model sonnet --role worker

This generates the agent Markdown file with frontmatter and a starter system prompt.

Phase 6: Write the System Prompt

The body of the agent file is its system prompt. Key principles:

1. Start with role definition: "You are a [role] specialized in [domain]."
2. State constraints clearly: "Only read files. Never modify code."
3. Define output format: "Return findings as a markdown checklist."
4. Include domain knowledge: Add specific patterns, rules, or standards.
5. Reference skills if needed: Use the skills frontmatter field.

Example system prompt structure:

You are a code reviewer specialized in TypeScript/React applications.

## Your Role
- Review code for quality, security, and best practices
- Identify bugs, performance issues, and anti-patterns
- Provide specific, actionable feedback with line references

## Constraints
- NEVER modify files — read only
- Focus on issues, not style preferences
- Prioritize: security > correctness > performance > readability

## Output Format
Return a markdown report:
- Summary (1-2 sentences)
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (nice to have)

Phase 7: Validate

python3 ~/.claude/skills/create-sub-agent/scripts/validate_agent.py <path-to-agent.md>

Checks: valid frontmatter, required fields, naming conventions, tool consistency.

Phase 8: Test

Invoke the agent to verify it works:

# Claude auto-delegates based on description
# Or explicitly: "use the <agent-name> agent to..."

Verify:

• Agent activates for the intended task type
• Model and tool constraints are respected
• Output quality matches expectations

Agent File Format Reference

File-Based Agent (Recommended)

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: plan
maxTurns: 20
skills:
  - review
  - scan
memory: user
---

You are a senior code reviewer...

All Frontmatter Fields

| Field | Required | Values | |-------|----------|--------| | name | Yes | kebab-case identifier | | description | Yes | When Claude should delegate to this agent | | tools | No | Comma-separated tool names (inherits all if omitted) | | disallowedTools | No | Tools to explicitly deny | | model | No | haiku, sonnet, opus, inherit (default: inherit) | | permissionMode | No | default, plan, acceptEdits, dontAsk, bypassPermissions | | maxTurns | No | Max agentic turns before stopping | | skills | No | Array of skill names to preload | | mcpServers | No | MCP servers available to this agent | | hooks | No | Lifecycle hooks (PreToolUse, PostToolUse, Stop) | | memory | No | Persistent memory scope: user, project, local |

File Locations

| Location | Scope | Priority | |----------|-------|----------| | --agents CLI flag | Session only | Highest | | .claude/agents/ | Current project | High | | ~/.claude/agents/ | All projects | Medium | | Plugin agents/ | Where plugin enabled | Lowest |

Common Agent Templates

Quick-Start Templates

Explorer (read-only, fast):

python3 ~/.claude/skills/create-sub-agent/scripts/init_agent.py explorer \
  --model haiku --role explorer

Code Reviewer (read-only, thorough):

python3 ~/.claude/skills/create-sub-agent/scripts/init_agent.py code-reviewer \
  --model sonnet --role reviewer

Security Scanner (read-only, maximum quality):

python3 ~/.claude/skills/create-sub-agent/scripts/init_agent.py security-scanner \
  --model opus --role reviewer

Doc Writer (can write files):

python3 ~/.claude/skills/create-sub-agent/scripts/init_agent.py doc-writer \
  --model sonnet --role worker

For more patterns, see references/agent-patterns.md.

What NOT to Do

• Do not give agents more tools than they need (least privilege)
• Do not use opus for simple tasks (waste of money, 5x cost vs haiku)
• Do not put complex logic in the system prompt — load a skill instead
• Do not create agents that duplicate existing skills
• Do not use bypassPermissions unless absolutely necessary

Continuous Improvement

After every invocation:

1. Reflect -- What worked, what caused friction
2. Record -- Append to lessons.md
3. Refine -- Update SKILL.md when patterns recur (2+ times)

lessons.md Entry Format

### YYYY-MM-DD -- Brief title
- **Friction**: What went wrong
- **Fix**: How it was resolved
- **Rule**: Generalizable takeaway

Additional Resources

Reference Files

• references/model-guide.md -- Detailed model selection with cost/speed/quality analysis
• references/agent-patterns.md -- Common agent architectures with full examples

Scripts

• scripts/init_agent.py -- Scaffold a new sub-agent
• scripts/validate_agent.py -- Validate agent structure and configuration