_template.md — The canonical agent shape
This file is the source of truth for the structure of every agent under .claude/agents/. Copy it to <name>.md, replace the placeholders, and you have an agent that loads correctly into Claude Code and routes well via the auto-delegator.
The shape is built on Anthropic's canonical pattern for sub-agents (see Anthropic sub-agents docs) with two BeWith-specific additions (Handoff points and Cross-references) that the multi-agent architecture needs. Earlier drafts of this template used 9 sections inspired by architecture.md §12.2; the lighter shape below aligns with Claude Code's idioms while preserving the multi-agent discipline.
Size target: 15–25 KB per agent (~400–800 lines including code samples). Anthropic's reference agents (code-reviewer, debugger, data-scientist, db-reader) are smaller — 50–200 lines — because they cover narrow scopes. BeWith agents cover larger surfaces (e.g. "all of Backend development on NestJS+Mongo+Aurora+Redis+Cognito"), which justifies the larger size.
Frontmatter
Every agent file starts with YAML frontmatter:
---
name: <kebab-case-name> # required — must match filename without .md
description: <see below> # required — the auto-router reads this
tools: <restrictive allowlist> # recommended — restrict to what this agent actually needs
model: inherit # recommended — default; override only with reason
---
Choosing tools
This field is an allowlist (restrictive): if set, the agent can use only those tools. Sensible defaults by agent type:
| Agent type | Suggested allowlist | Reason |
|---|---|---|
| Reviewer / gatekeeper (process-guardian, code-reviewer) | Read, Grep, Glob, Bash | Reads code, runs validators; no Edit/Write — fixing is someone else's job |
| Designer (architect, decision-recorder) | Read, Grep, Glob, WebFetch, Write | Reads code, looks up patterns, writes ADRs; minimal modification |
| Implementer (backend-developer, frontend-developer, qa-engineer, database, devops-infra) | leave omitted (inherits all) | Needs Edit, Write, Bash, etc. to actually do the work |
| Domain advisor (auth-security, i18n-localization, analytics-observability, legacy-php-guide) | Read, Grep, Glob, Bash | Advises and reviews; rare to author code directly |
If you set tools, you also need to consider disallowedTools for cases where you inherit broadly but want to exclude one tool — but most agents only need one or the other, not both.
Writing the description
This is what Claude's auto-router reads to decide whether to delegate to the agent. Two rules from Anthropic's docs:
- Include "use proactively" (or "use immediately") if you want auto-delegation. Without it, Claude is biased to ask first.
- Be specific about trigger context. Generic descriptions ("reviews code") will lose to specific ones ("Reviews pre-PR diffs against the ten-point checklist; loaded automatically before PR open").
Example (from Anthropic's own code-reviewer):
"Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code."
Match this shape: <noun phrase> + <proactively phrasing> + <trigger context>.
Body sections (in order)
The body becomes the agent's custom system prompt when Claude Code invokes the agent (see Anthropic docs — Write subagent files). Claude Code does not parse anything from the body beyond plain markdown — there is no enforcement of section names. The sections below are a writing convention that keeps agents discoverable and consistent across the platform.
1. Role
One paragraph (~5–10 lines). What authority does this agent hold? What does it care about? What does it not care about? Frame the role around the outcome the agent owns, not the activities it performs.
Example: "The Code Reviewer is the last reader before a PR opens. Its authority is to block the PR from leaving draft state if any of the ten checks fail. It cares about correctness, regression risk, contract drift, security touch, and PR sizing. It does not care about style (Prettier handles that), naming (the relevant domain agent handles that), or product correctness (the Product Manager agent handles that)."
2. When invoked
A numbered workflow describing how the agent operates from "loaded" to "finished its turn." This is the canonical Anthropic pattern — every reference agent has it.
Format: numbered list, each step is one short sentence in the imperative ("Read the diff", "Check the lint result", "Emit the blocking message").
The workflow should be complete enough that a fresh session can execute it without re-deriving the steps. If a step needs nuance, the nuance goes in section 4 (Output format) or section 5 (Handoff points), not inflated into the workflow itself.
3. Checklist / Hard rules
The non-negotiables. Use one of:
- Markdown checklist (
- [ ]) — when the agent's job is to verify a list of items (Process Guardian, Code Reviewer). - Numbered MUST / MUST NOT statements — when the agent's job is to follow a rule set (Architect, Auth-Security).
Each item is one sentence, in the imperative. Items resolve to observable artifacts (a file, a CI result, a tool output) where possible — anything subjective belongs in section 4.
If an item is waivable, mark it explicitly (e.g. **WAIVABLE:** prefix).
4. Output format
The exact format of what the agent produces — the review comment, the blocking message, the ADR draft, the migration plan. Use real code/markdown templates, not abstract pseudo-code.
Why this section is load-bearing: a Process Guardian that emits "DoD not met" is useless; one that emits the canonical block format with named failed items + handoff target is the difference between a gate and a pile of text.
This is also where the patterns the agent looks for live — code patterns, prose patterns, structural patterns. Subdivide if the section grows:
- Patterns to look for in the input
- Patterns to emit as output
- Patterns to escalate to a handoff
5. Handoff points
When does this agent stop and bring another in? List the trigger and the receiving agent. BeWith-specific section — Anthropic's canonical agents are mostly standalone; BeWith's are explicitly multi-agent and need to declare handoff edges.
Format:
- **<trigger condition>** → handoff to [`<agent-name>`](./<agent-name>.md)
- **<trigger condition>** → escalate to human via <pathway>
A missing handoff in a multi-agent platform is a worse failure than a bad handoff. Be liberal here.
6. Cross-references
Pointers to related agents, policies, skills, and methodology docs. BeWith-specific section — keeps the platform documents stitched together.
Keep it tight (5–10 entries). Link methodology docs and platform files by their GitHub absolute URL (https://github.com/bewith-dev/bewith-docs/blob/master/<path>) — relative paths like ../../docs/methodology/X.md break in Docusaurus because the docs plugin and the agents plugin live in different routeBasePath instances. Link sibling agents that already exist by [name](./<name>.md) (relative, same instance). For agents that don't exist yet, drop the link and use backticked plain text — the IDE will flag the broken relative link, which is the intended signal that the forward reference is waiting on that file.
7. Anti-patterns (optional but recommended for high-stakes agents)
What this agent must never do, with examples. Differs from Hard Rules in that Anti-Patterns are illustrative ("here's what doing X looks like and why it's wrong"), not prescriptive ("MUST NOT do X").
Use the format: **Anti-pattern: <name>.** <description>. *Right behavior:* <correction>.
Drop this section for narrow / low-stakes agents.
Closing matter
After section 7, optionally include:
- Last reviewed: YYYY-MM-DD line, so consumers can spot stale content.
- Source: if the agent's body was migrated from an external file (e.g.
agents-developer-kit/agents/ARCHITECT.md), cite it.
Two final notes
- Tone. Agents are written in the second person ("You review …", "You block …") OR in third-person passive describing the agent's behavior. Avoid the first person — the AI shouldn't refer to itself across agent boundaries.
- Subagents cannot spawn subagents. Per Anthropic docs, an agent's body should not assume it can invoke another agent via the Agent tool. Handoffs in section 5 are recommendations to the main session, not in-band invocations.