Subagent Implementation

File Structure

Subagent files are Markdown with YAML frontmatter:

---
name: agent-name
description: When to use this agent...
model: inherit
color: blue
tools: ["Read", "Grep"]
---

You are [agent role]...

**Responsibilities:**
1. [Task 1]
2. [Task 2]

Location: .claude/agents/ or .claude-plugin/agents/ Naming: kebab-case, 3-50 chars (e.g., code-reviewer)

Frontmatter Fields

Required Fields

Description Format

Include 2-4 <example> blocks:

description: |
  Use when reviewing code for quality. Examples:
  <example>
  Context: User wrote new code
  user: "Review this"
  assistant: "I'll use the code-reviewer"
  <commentary>Code review is core function</commentary>
  </example>

Optional Fields

Permission modes: default, acceptEdits, dontAsk, bypassPermissions, plan

See references/frontmatter-reference.md for complete field documentation.

System Prompt Template

You are a [role] specializing in [domain].

**Responsibilities:**
1. [Primary task]
2. [Secondary task]

**Process:**
1. [Step 1]
2. [Step 2]
3. [Verification]

**Output Format:**
[Specify exact output structure]

**Edge Cases:**
- [Case 1]: [How to handle]

Writing Guidelines

DO:

• Use second person ("You are...")
• Be specific and concrete
• Define output format clearly
• Keep under 10,000 characters

DON'T:

• Use first person ("I am...")
• Be vague
• Skip process steps
• Exceed 10k chars

See references/system-prompt-patterns.md for detailed templates.

Quick Checklists

Frontmatter

• name: 3-50 chars, kebab-case
• description: 2-4 examples
• model: valid option
• color: valid option
• tools: (optional) minimum needed

System Prompt

• Clear role statement
• Numbered responsibilities
• Step-by-step process
• Explicit output format
• Edge cases addressed
• Under 10k chars

Testing

1. Syntax: Valid YAML frontmatter
2. Trigger: Questions activate agent
3. Behavior: Matches description
4. Output: Follows format

References

For complete documentation:

• references/frontmatter-reference.md - All fields with examples
• references/system-prompt-patterns.md - Detailed templates
• examples/complete-analyzer-example.md - Working example

For distribution via marketplaces, see the Anthropic docs on Plugin Marketplaces.