/writing-agents

name: writing-agents
description: "How to write Claude Code agents: example blocks, model choice, least-privilege tools."
version: 0.2.0
user-invocable: false

Writing Agents

> Scope: covers Claude Code agent `.md` file authoring (Markdown + frontmatter at `.claude/agents/`). Codex CLI defines agents differently — as `[agents.<name>]` TOML tables in `.codex/config.toml`; see [[nlpm:conventions-codex]]. Antigravity subagents are under-documented at this writing; see [[nlpm:conventions-antigravity]]. For multi-agent orchestration, see [[orchestration]]. For plugin architecture, see [[writing-plugins]].

1. Example Blocks Make or Break Triggering

Without `<example>` blocks, Claude guesses when to dispatch your agent. With them, it pattern-matches against real scenarios.

**Target**: 1 well-chosen example + 1 "Not for …" sentence, whole description ≤1,200 characters.

The description sits in the Agent tool's text on every turn and is the only thing Claude sees when choosing an agent. Examples therefore stay in the description -- moved into the body, they are invisible to routing -- but every extra example is always-on context. One example that shows the main positive trigger, trigger phrases in the prose, and an explicit exclusion carry the routing signal at a fraction of the tokens.

Example Block Anatomy

<example>
Context: [what the user is doing -- not just "user needs help"]
user: "[realistic user message that should trigger this agent]"
assistant: "[what Claude says when dispatching -- shows the decision logic]"
</example>

Bad Example (too vague -- 40% trigger accuracy)

<example>
Context: User needs code review
user: "review my code"
assistant: "I'll use the reviewer agent."
</example>

**Problems**: generic context, generic query, no decision logic shown.

Good Example (specific scenario -- 92% trigger accuracy)

<example>
Context: User just pushed changes to the authentication module and wants feedback before merging
user: "Can you check if the auth changes look good before I create the PR?"
assistant: "I'll dispatch the security-reviewer agent to check the auth changes for vulnerabilities, token handling, and session management best practices."
</example>

**Why it works**: specific context (auth module, pre-PR), realistic query (how users actually talk), decision logic visible (what the agent will check).

One Example, Prose Triggers, One Exclusion

| Part | Purpose | What it carries | |------|---------|-----------------| | Prose trigger phrases | Breadth | Obvious, edge-case and non-obvious triggers, one short phrase each | | 1 `<example>` | Anchor | The main positive trigger: user asks, assistant dispatches | | "Not for …" sentence | Boundary | The adjacent request that belongs to a sibling agent or to no agent |

Example for a "performance-profiler" agent:

description: |
  Profiles slow endpoints, memory growth and query plans. Use when a request is
  slow, memory climbs over time (possible leak), or the user is choosing between
  two implementations on speed. Not for fixing the code it measures; it reports
  hot spots only.

  <example>
  Context: User wants to profile their API
  user: "Profile the /api/users endpoint, it's slow"
  assistant: "I'll dispatch the performance-profiler to trace the /api/users endpoint..."
  </example>

A second example is allowed when a distinct trigger cannot be said in prose, but it costs context on every turn; nlpm's R09 gives full credit for one.

2. Model Selection

| Task type | Model | Signal words in body | Examples | |-----------|-------|---------------------|----------| | Mechanical / parsing / formatting / counting | haiku | count, list, extract, format, parse, scan | scanner, parser, formatter, counter, lister | | Analysis / reasoning / moderate judgment | sonnet | analyze, review, evaluate, summarize, compare | linter, reviewer, extractor, summarizer | | Complex judgment / orchestration / multi-agent | opus | coordinate, decide, assess, synthesize, architect | QC coordinator, architect, strategy planner |

Quick Heuristic

Count the instruction lines in your agent body. Then check for judgment words.

< 20 instruction lines AND no judgment words → haiku
20-50 instruction lines OR judgment words → sonnet
> 50 instruction lines OR coordination logic → opus

Judgment words: evaluate, decide, assess, determine, weigh, prioritize, recommend, judge, infer, synthesize.

Cost Impact

| Model | Relative cost | When to upgrade | |-------|--------------|-----------------| | haiku | 1x | Agent produces wrong output on edge cases | | sonnet | 10x | Agent produces wrong output on easy cases | | opus | 30x | Agent coordinates other agents or makes architectural decisions |

**Rule**: start with haiku, upgrade only when output quality requires it.

3. Tool Least-Privilege

Only list tools the agent body actually references. Every extra tool is a potential misuse vector.

Common Mistakes

| Agent type | Common over-grant | Correct tools | |-----------|-------------------|---------------| | Audit/review agent | Write, Edit, Bash | Read, Glob, Grep | | Code generator | Read, Grep (unused) | Write, Edit, Bash | | Orchestrator | Read, Write (does no IO) | Task | | Scanner | Bash (uses grep) | Grep, Glob, Read |

Tool Reference

| Tool | When to include | |------|----------------| | Read | Agent reads file contents | | Write | Agent creates new files | | Edit | Agent modifies existing files | | Glob | Agent searches for files by pattern | | Grep | Agent searches file contents | | Bash | Agent runs shell commands (linters, tests, builds) | | Task | Agent dispatches sub-agents | | WebFetch | Agent fetches a URL |

4. Output Format

Every agent MUST define its output format in the body. Without it, output varies between invocations -- making results unparseable by parent agents.

Pattern: Structured Report

## Output Format

### {Sec