write-an-agent

Write an agent

Create a new agent file that matches the house template, so the whole fleet stays consistent. Write it to the plugin's agents/<name>.md (when extending this plugin) or the project's .claude/agents/<name>.md.

Steps

1. Know the role. If the role's real-world capabilities aren't clear, dispatch @researcher (role / job-requirement research) to produce a Competency Dossier and persist it to research/<role-slug>.md (project: .claude/research/…; bundled: ${CLAUDE_PLUGIN_ROOT}/research/…), named by discipline. Author the agent from it — its Recommendation for the AI version maps straight onto the agent's job, tools, and scope.
2. Copy the template at templates/agent.md and fill every section (delete any you deliberately omit — leave no placeholder behind).
3. Frontmatter:
   • name — lowercase-kebab, unique, matches the filename. This becomes the @role and subagent type.
   • description — what routes here plus explicit guards (a "Do NOT use…" clause). The orchestrator sees only this when routing, so make it discriminative against the other agents.
   • model — choose deliberately: inherit to follow the session, or pin (claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5-…) for cost/latency.
   • tools — least privilege. Read/Grep/Glob to analyse; add Write/Edit only if it produces files; Bash/WebSearch/WebFetch only if needed. Omit Agent unless the role legitimately orchestrates.
4. Body (in template order) — a one-line identity hook; lean ## Your job; ## Operating principles that open with the disposition (what the role cares about / is allergic to) then the imperative rules — only persona-heavy roles need a separate ## Identity; for deep roles an ## Expertise that synthesises the dossier (load-bearing facts inline) and references research/<role-slug>.md by path — never a re-paste; inline a ## Workflows entry only if the procedure is worth spelling out; ## What you don't do scoped by capability/domain, handing out-of-scope work back to the orchestrator — don't hardcode peer agent names (routing is description-driven; the fleet varies per project).
5. Keep it self-contained — reference bundled docs by repo-relative path, never a GitHub/external URL. For workstream participation, point at the task dir's PROTOCOL.md (it travels with the run).
6. Single source of truth — don't restate rules another doc owns; reference them. When a second role needs the same procedure, promote it to a shared doc and reference it from both.

Checklist

• name lowercase-kebab, matches filename
• description has a "Use when…" trigger AND a "Do NOT use…" guard
• tools least-privilege; model chosen on purpose
• Every template section filled or deliberately removed — no leftover <placeholders>
• No external URLs; any workstream reference points at the in-dir PROTOCOL.md
• Deep roles: Expertise synthesises the dossier and links research/<role-slug>.md — not a re-paste
• What you don't do is capability-scoped and hands back to the orchestrator — no hardcoded peer names