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>