writing-agents

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.

Minimum: 2 examples. Ideal: 3 -- one obvious trigger, one edge case, one non-obvious.

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).

The Three-Example Pattern

Example	Purpose	What it demonstrates
1. Obvious trigger	Baseline dispatch	User explicitly asks for what the agent does
2. Edge case	Boundary behavior	User asks something adjacent -- agent should still trigger
3. Non-obvious	Discovery	User doesn't know the agent exists but their need matches