Agent authoring standards

An agent (subagent) is a specialized Claude instance Claude Code spawns for a focused, contained task. It has its own system prompt, its own tool allowlist, and its own context window; it reports a result back and then its context is discarded. Agents ship standalone at agents/<name>.md or bundled at plugins/<plugin>/agents/<name>.md.

This page is two layers: Anthropic’s official guidance, then the RBA tailoring on top.

Anthropic’s best practices

Source: Claude Code — Subagents.

A subagent is a Markdown file with YAML frontmatter and a system prompt as the body. Anthropic’s core guidance:

Frontmatter

---
name: <agent-name>          # required — lowercase, hyphen-separated identifier
description: <when to use>  # required — natural-language statement of when to delegate here
tools: Read, Grep, Glob     # optional — comma-separated; if omitted, inherits ALL tools
model: sonnet               # optional — sonnet | opus | haiku | inherit
---

name and description are required. tools is optional — omitting it inherits every tool the main session has, so for a focused subagent you almost always want to set it explicitly. model is optional.

The description drives delegation

Claude reads description to decide when to hand work to this subagent automatically. Anthropic’s guidance: state clearly when the subagent should be used; include phrasing like “use proactively” or “must be used” when you want eager automatic delegation.

Design guidance

• Single responsibility. Anthropic recommends focused subagents with one clear job over broad general-purpose ones — focus improves reliability.
• Write a detailed system prompt. The body is the subagent’s entire briefing; be specific about process, constraints, and the shape of the output.
• Limit tool access to what’s needed. Anthropic notes this improves both security and focus and reduces the chance the subagent goes off task.
• Separate context window. Subagents preserve the main thread’s context — use them for work that would otherwise flood it (large searches, exhaustive reviews).
• Version-control project subagents in .claude/agents/ (here, in the artifact’s repo location).

How RBA tailors this

When to write an agent vs. a skill (RBA decision rule)

Anthropic explains how to write a subagent; RBA adds whether you should. Default to a skill — agents add friction (context switch, separate report) and should earn it.

Choose an agent when	Choose a skill when
The task can derail the main thread (large search, exhaustive review)	The pattern should run alongside the conversation
You want a different system prompt than the main session	The user wants Claude to follow a methodology in the open
The output is a single deliverable (report, audit, decision)	The user wants iterative back-and-forth
You want a strict tool allowlist different from the main session	The main session’s allowlist is fine

Frontmatter — RBA additions

---
name: <agent-name>                       # required — must match the filename (RBA: slug = name)
description: <what it does + when to invoke>  # required — Anthropic's rules apply
primitive: true                          # optional — set only when this is a cross-cutting foundation primitive
tools:                                    # RBA: always set explicitly; never inherit-all
  - Read
  - Grep
  - Glob
model: sonnet                            # optional
---

• Slug = name = filename (security-reviewer.md declares name: security-reviewer).
• primitive: true is a single optional flag for cross-cutting foundation primitives; plugin-bundled agents inherit it from the plugin’s rba-meta.json and must not redeclare it. See the plugin standards for the full facet model (platforms, disciplines, outcomes, lifecycle, tags).
• tools is never omitted. Anthropic allows inherit-all; RBA forbids it. A subagent must declare its allowlist explicitly so it is strictly more restricted than the main session.

Tool allowlist — RBA default-deny

Agent role	Allowed tools
Read-only investigator (security-reviewer, accessibility-auditor)	Read, Grep, Glob
Web researcher	+ WebSearch, WebFetch(domain:...)
Reviewer needing shell context	+ Bash(git diff *, git log *, git show *)

Never give an agent Write, Edit, or unrestricted Bash unless mutation is the agent’s whole purpose and the user has explicitly authorized it.

Output discipline (RBA convention)

The agent’s report is its only deliverable — treat the format as a contract: lead with the conclusion, use consistent section headers across runs, quantify where possible, cite file paths / line numbers, end with explicit recommendations.

Quality checklist

1. description makes it clear when to delegate here vs. a sibling (Anthropic).
2. The system prompt is detailed and single-responsibility (Anthropic).
3. tools is set explicitly and least-privilege — no inherit-all (RBA).
4. Frontmatter has name, description, tools; standalone agents may set optional facets or primitive: true (RBA).
5. Slug = name = filename (RBA).
6. The persona is domain-specific and opinionated.
7. The output format is an explicit, repeatable template.
8. The agent passes a smoke test on a representative input and its report is self-contained.

Anti-patterns

• Omitting tools so the subagent silently inherits everything (RBA-forbidden even though Anthropic permits it)
• An agent that duplicates a skill — if the work belongs in the main thread, write a skill
• Bash(*) or Edit access without a documented, authorized reason
• Vague description that produces inconsistent or no automatic delegation
• Vague output format that yields inconsistent reports across runs
• Generic “you are a helpful assistant” persona