implement-sub-agents

name	implement-sub-agents
description	Create and validate Claude sub-agent definitions with correct frontmatter, tool permissions, and delegation boundaries.

Implement Sub-Agents

Create or update agent files under agents/ with explicit role boundaries, model/tool settings, and delegation patterns.

Workflow

1. Assess complexity: Verify that sub-agent is needed (score 7-8). If simpler approach works, use skill instead.
2. Define role: Clear purpose, responsibilities, and explicit boundaries
3. Set decision authority: What agent can/cannot do autonomously
4. Configure tools: Least privilege access to required tools only
5. Author/update: Agent markdown with valid frontmatter
6. Context strategy: Define how agent manages context (retrieval, summarization, state)
7. Plan evaluations: Identify 20-50 test scenarios covering success and failure modes
8. Validate: Check frontmatter and agent file structure
9. Connect selectively: Link related skills/hooks only when required

Progressive Disclosure

Best Practices (Anthropic Guidelines)

• Core principles: ../../docs/ANTHROPIC_BEST_PRACTICES.md
  • Links to detailed references for complexity scoring, context management, and evaluation strategy

Sub-Agent Design

• Agent frontmatter rules: references/subagent-frontmatter.md
• Tool access strategy: references/subagent-tools.md
• Model selection guidance: references/subagent-models.md
• Permission boundaries: references/subagent-permissions.md
• Delegation patterns: references/subagent-delegation.md

Validation Tools

• Agent file validator: scripts/validate-subagent.sh
• Frontmatter checker: scripts/check-subagent-frontmatter.sh

Templates (by Complexity)

• Level 3 - Autonomous Agent (Score 7-8): assets/templates/subagent-autonomous.md
• Base sub-agent template: assets/templates/subagent-template.md
• Read-only sub-agent example: assets/templates/subagent-readonly.md
• Sub-agent with skills example: assets/templates/subagent-with-skills.md
• Sub-agent with hooks example: assets/templates/subagent-with-hooks.md

Related Skills

• Umbrella routing and architecture: ../implement-claude-extensions/SKILL.md
• Agent team coordination: ../implement-agent-teams/SKILL.md

Sources

• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/plugins