sub-agent-patterns
Comprehensive guide to sub-agents in Claude Code: built-in agents (Explore, Plan, general-purpose), custom agent creation, configuration, and delegation patterns. Use when: creating custom sub-agents, delegating bulk operations, parallel research, understanding built-in agents, or configuring agent tools/models.
npx skills add majiayu000/claude-skill-registry --skill sub-agent-patterns-jezweb-claude-skills-2 --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Guides the use of sub-agents in Claude Code, detailing built-in sub-agents (Explore, Plan, General-Purpose), how to create custom sub-agents, configuration fields, tool inheritance rules, and patterns for delegation and orchestration. It also explains when to use sub-agents, how to invoke them explicitly or automatically, and how to resume or disable them.
How it works
- Describes built-in sub-agents with their models, modes, and available tools (Explore: read-only exploration; Plan: read-only research; General-Purpose: read and write with all tools).
- Provides file locations and formatting for custom sub-agents: Markdown files with YAML frontmatter specifying fields like name, description, tools, model, permissionMode, skills, and optional hooks.
- Explains MCP tool inheritance: omitting the tools field yields full tool access; explicitly listing tools creates an allowlist.
- Lists available tools and recommended tool sets per agent type, plus patterns for tool access and avoidance of Bash when not needed.
- Details how to create an orchestrator using the Task tool to spawn other sub-agents and coordinate multi-phase workflows; includes examples of orchestrator configurations and practical workflows.
- Covers usage patterns: automatic delegation, explicit invocation, resumable sub-agents, and disabling sub-agents via permissions or CLI.
- Includes cautions about session Restart Required when adding new agents and best practices to keep orchestration within two levels of depth.
When to use it
- Use for creating custom sub-agents to perform specialized tasks or workflows.
- Use for delegating bulk operations, parallel research, or multi-step, multi-agent workflows.
- Use to understand built-in agents and how to configure agent tools/models for efficient context management.
What it can touch
- Tools listed under Available Tools Reference for sub-agents (Read, Write, Edit, MultiEdit, Glob, Grep, LS, Bash, BashOutput, KillShell, Task, WebFetch, WebSearch, TodoWrite, TodoRead, NotebookRead, NotebookEdit, AskUserQuestion, EnterPlanMode, ExitPlanMode, Skill, LSP, MCPSearch).
- Orchestration patterns rely on the Task tool to spawn and coordinate sub-agents.
Caveats
- Emphasizes the need to restart Claude Code session to discover newly created agents.
- Highlights the MCP tool inheritance rule: omitting tools grants all tools including MCP; specifying any tools creates an allowlist.
- Warns about Bash approval spam when Bash remains in a sub-agent’s tools list; suggests removing Bash when not required.
- Recommends limiting orchestration depth ( Best practice: Keep orchestration to 2 levels deep ).
# Sub-Agents in Claude Code **Status**: Production Ready ✅ **Last Updated**: 2026-02-02 **Source**: https://code.claude.com/docs/en/sub-agents Sub-agents are specialized AI assistants that Claude Code can delegate tasks to. Each sub-agent has its own context window, configurable tools, and custom system prompt. --- ## Why Use Sub-Agents: Context Hygiene The primary value of sub-agents isn't specialization—it's **keeping your main context clean**. **Without agent** (context bloat): ``` Main context accumulates: ├─ git status output (50 lines) ├─ npm run build output (200 lines) ├─ tsc --noEmit output (100 lines) ├─ wrangler deploy output (100 lines) ├─ curl health check responses ├─ All reasoning about what to do next └─ Context: 📈 500+ lines consumed ``` **With agent** (context hygiene): ``` Main context: ├─ "Deploy to cloudflare" ├─ [agent summary - 30 lines] └─ Context: 📊 ~50 lines consumed Agent context (isolated): ├─ All verbose tool outputs ├─ All intermediate reasoning └─ Discarded after returning summary ``` **The math**: A deploy workflow runs ~10 tool calls. That's 500+ lines in main context vs 30-line summary with an agent. Over a session, this compounds dramatically. *
- Why Use Sub-Agents: Context Hygiene
- Built-in Sub-Agents
- Explore Agent
- Plan Agent
- General-Purpose Agent
- Creating Custom Sub-Agents
- File Locations
- File Format
- Configuration Fields
- MCP Tool Inheritance (CRITICAL)
- Available Tools Reference
- Avoiding Bash Approval Spam (CRITICAL)
- Using /agents Command (Recommended)
- CLI Configuration
claude --agents '{
claude --disallowedTools "Task(Explore)"
git add [files] && git commit -m "$(cat <<'EOF'What does the sub-agent-patterns skill do?
Comprehensive guide to sub-agents in Claude Code: built-in agents (Explore, Plan, general-purpose), custom agent creation, configuration, and delegation patterns. Use when: creating custom sub-agents, delegating bulk operations, parallel research, understanding built-in agents, or configuring agent tools/models.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill sub-agent-patterns-jezweb-claude-skills-2 --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.