agent-development

What this skill does

# Agent Development for Claude Code Plugins

## Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Each agent is a markdown file in the `agents/` directory with YAML frontmatter defining its configuration and a markdown body serving as its system prompt.

## Canonical agent frontmatter template (MANDATORY shape)

This is the template every new agent MUST follow. Deviating from this shape is the #1 cause of agents that never trigger.

```yaml
---
name: my-agent                                    # REQUIRED: kebab-case, 3-50 chars, alphanumeric start/end
model: inherit                                    # REQUIRED: always `inherit` unless you have a hard reason
color: blue                                       # RECOMMENDED: one of blue/cyan/green/yellow/magenta/red
tools: Read, Write, Edit, Glob, Grep, Bash        # RECOMMENDED: minimal set; omit for full access
description: |
  One-sentence summary of what the agent does. PROACTIVELY activate for: (1) concrete trigger, (2) concrete trigger, ..., (N) concrete trigger. Provides: comma-separated capability nouns.

  <example>
  Context: Realistic situation where the agent should fire
  user: "A realistic user quote -- the kind of thing someone would actually type"
  assistant: "Short 1-2 sentence response. Mention loading a specific skill if relevant."
  <commentary>Triggers for specific-keyword-1, specific-keyword-2, specific-keyword-3</commentary>
  </example>

  <example>
  Context: Another realistic situation covering a different capability
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A debugging / troubleshooting scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A "when to pick this vs. that" scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>
---

You are [role] specializing in [domain]. [Lean orchestrator body -- see "Lean Orchestrator Pattern" below.]
```

### Hard rules for the frontmatter

1. **`name:` is required.** Do NOT use the deprecated `agent: true` flag — that pattern is legacy and results in an unnamed agent that cannot be referenced or routed to reliably. If you find `agent: true` in an existing file, replace it with `name: <kebab-name-from-filename>`.
2. **`model: inherit` is required.** Never hard-code a model unless the agent has a documented capability requirement.
3. **`description:` MUST include the enumerated `PROACTIVELY activate for: (1)... (2)... (N)...` pattern AND a `Provides: ...` capability list.** A description that only says "Use this agent for help with X" will not route reliably.
4. **`<example>` blocks are conditional, not unconditional.** Whether the description needs `<example>` blocks depends on the agent's body word count — see **"Example-block requirement by agent body size"** below. Lean orchestrators deliberately omit them; fat agents need them. Do not blanket-require examples on every agent.
5. **Use `description: |` (YAML block scalar)** whenever the description spans multiple lines or contains `<example>` blocks. A folded scalar (`>`) or implicit flow scalar will mangle the examples.
6. **Do NOT put cross-cutting boilerplate (Windows path rules, documentation policy, etc.) inside the YAML `description:` block.** That text is used for routing-match, and boilerplate that appears in many agents poisons the signal. Put it in the markdown body under a clearly named `## Windows file path requirements` section (or similar) instead.

### Example-block requirement by agent body size (UNIFIED RULE)

The number of `<example>` blocks a description needs is a function of the agent's markdown body word count. This rule reconciles two earlier conflicting recommendations ("always add 4-6 examples" vs. "lean orchestrators don't need examples") into a single tier table that authoring guidance, the canonical checklist, and `scripts/validate_plugins.py` all share.

| Agent body word count | Tier | Example-block requirement |
|---|---|---|
| < 1,500 words | Sub-target | Optional |
| 1,500-2,500 words | **Lean orchestrator (target band)** | **Optional, often omitted by design** |
| 2,500-3,000 words | Above-target | **Recommended (3-5)** |
| > 3,000 words | Oversized | **Required (3-5) AND extraction mandatory** |

The validator only flags "missing examples" when the body crosses 2,500 words (`AGENT_EXAMPLES_THRESHOLD_WORDS`). Lean orchestrators under that threshold pass cleanly without examples — that absence is by design.

**Authoring distilled:** decide lean-orchestrator vs. fat-agent first; if lean, the `PROACTIVELY activate for:` enumeration carries routing and examples are not required. When refactoring fat -> lean, stripping examples is a legitimate part of the refactor. When auditing, compute body word count BEFORE recommending example-block fixes — see "Pre-recommendation intent check" below.

### Deprecated / broken patterns to migrate

| Broken pattern | What it does | Fix |
|---|---|---|
| `agent: true` (no `name:`) | Agent cannot be named/routed reliably | Replace with `name: <kebab-name>` |
| `description:` without `<example>` blocks (agent body > 2,500 words) | Fat agent that routes ambiguously without examples | Add 3-5 `<example>` blocks OR split into orchestrator + skills (preferred) |
| `description:` with "Use this agent for X" prose only | Vague routing, poor trigger | Rewrite with `PROACTIVELY activate for: (1)...` enumeration |
| Windows boilerplate inside YAML `description:` | Pollutes routing signal | Move to `## Windows file path requirements` in body |
| `model:` missing or hard-coded (e.g. `model: sonnet`) | Fails to inherit session model | Set `model: inherit` |
| Single `<example>` block with full code in `assistant:` | Dilutes matching, bloats description | Keep assistant replies to 1-2 sentences; put code in skills |

## Frontmatter Fields Reference

Detailed rules for each frontmatter field (`name`, `description`, `model`, `color`, `tools`) live in `references/frontmatter-fields-reference.md`. Highlights:

- **name** — kebab-case, 3-50 chars, alphanumeric start/end; role-based convention (`code-reviewer`, `domain-expert`).
- **description** — most critical field; must include `PROACTIVELY activate for: (1)... (N)...` enumeration and `Provides: ...` capability list. `<example>` blocks gated by the body-word-count tier table above.
- **model** — `inherit` is the default; only deviate with a documented capability reason.
- **color** — `blue`/`cyan` (analysis), `green` (generation), `yellow` (validation), `red` (critical/security), `magenta` (creative/architecture).
- **tools** — principle of least privilege; common: `Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent`. MCP tools as `mcp__server__tool`.

Load `references/frontmatter-fields-reference.md` when authoring or auditing a real agent.


## System Prompt Design

The markdown body becomes the agent's system prompt. Write in **second person** ("You are...", "You will..."). Required sections: Core Responsibilities, Process, Quality Standards, Output Format, Edge Cases. DO be specific and define output clearly; DON'T write in first person, be vague, or embed domain knowledge that belongs in skills. Full template + DO/DON'T list: `references/design-principles-and-mistakes.md`.

## Lean Orchestrator Pattern (CRITICAL)

An agent body must be a **lean orchestrator**, NOT a domain knowledge dump. The agent delegates to skills for detailed knowledge.

### Agent Body Size Limits

| Metric | Target | Hard Maximum |
|--------|--------|-------------|
| Word count | 1,500-2,500 words | 3,000 words |
| Character count | ~10,000-15,000 chars | 20,000 chars |

### What Belongs in the Agent Body

| Section | Required | Purpose |
|---------|----------|---------|
| Role identity | Yes | "You are [role] specializing in [domain]" |
| Skill activation rules |