Writing Agents

Scope: covers agent .md file authoring. 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>