| name | writing-agents |
| description | Use when creating new agents, editing existing agent system prompts, optimizing agent token efficiency, or maintaining agent quality. Applies when agent is too long, not performing well, overtriggering, or when reviewing agent files in .claude/agents/. Does not apply to skills, hooks, commands, or slash commands. |
Writing Agents
Overview
Patterns and workflows for writing effective, token-efficient agent system prompts.
Quick Reference
| Task | Reference |
|---|
| Frontmatter fields | references/agent-frontmatter.md |
| Description examples | references/project-patterns.md Section 7 |
| Model selection | references/project-patterns.md Section 2 |
| Size targets | references/project-patterns.md Section 3 |
| Memory patterns | references/project-patterns.md Section 4 |
| Output format patterns | references/project-patterns.md Section 5 |
| Handoff patterns | references/project-patterns.md Section 6 |
| Emphasis calibration | references/anthropic-best-practices.md Section 3 |
| Parallel execution | references/anthropic-best-practices.md Section 6 |
| Common mistakes | references/common-mistakes.md |
Description Field
Syntax: Single line with \n for newlines. Wrap in '...' if contains # after whitespace.
Write in third person — the description is injected into the system prompt by the routing system.
Content pattern: Brief capability statement (1 clause), then triggering conditions. Do NOT expand the capability statement into a workflow summary — Claude follows the description shortcut instead of reading the full system prompt body. Keep "what" to a single clause, put process details in the body.
Include:
- "Use when..." / "When to use" conditions
- "When NOT to use" anti-conditions
- 1-2
<example> blocks with <commentary> explaining why it triggers
See references/project-patterns.md Section 7 for working examples.
System Prompt Structure
Canonical section order for this project:
- Persona/Role — Expert identity with domain expertise, 1-2 sentences
- Core Responsibilities — Numbered, 3-5 items
- Mandatory Gates — Issue requirements, input validation
- Classification/Detection — Change-type analysis, input categorization
- Workflow Steps — The main process
- Output Format — Structured template (verdict header, evidence, next steps)
- Handoff Protocol — How results return to caller
- Critical Rules — Numbered constraints
- Self-Improvement — If using memory (see
references/project-patterns.md Section 4)
Not every agent needs all sections. Small focused agents may only need Persona, Workflow, Rules, and Output Format.
Output format: Agents feeding orchestrators use rigid parseable formats. Standalone agents use human-readable reports. See references/project-patterns.md Section 5.
Handoff patterns: Choose from: GitHub issue comment, structured return to caller, terminal states (SUCCESS/ROLLBACK/PARTIAL), or fix-and-retry loop. See references/project-patterns.md Section 6.
Creation Workflow
Use sub-agents for each phase, same as optimization. Fresh context prevents drift.
Phase 1: Create (sub-agent)
Dispatch a creation sub-agent. Provide it with: the agent requirements, this skill, existing agents (for pattern reference), and all inherited context files (CLAUDE.md, .claude/rules/*). The sub-agent follows these steps:
- Discover patterns — Read 2-3 existing agents in
.claude/agents/ for local conventions
- Define persona — Expert identity with domain expertise, 1-2 sentences
- Write frontmatter — Description complying with the Description Field section of this skill (under 1024 chars, no workflow summary, 1-2 examples with
<commentary>, "When to use" and "When NOT to use" sections). Choose model and tools (least privilege — see references/anthropic-best-practices.md Section 9)
- Structure system prompt — Follow section order from System Prompt Structure above. Include output format template and handoff protocol
- Calibrate freedom — High freedom for judgment calls, low freedom for exact commands (see
references/anthropic-best-practices.md Section 2)
- Scope-limit Opus — For agents that make modifications, add "Only make changes directly requested." Prefer direct Grep/Read over spawning subagents for simple lookups (see
references/anthropic-best-practices.md Section 4)
- Safety gates — Identify destructive or externally-visible operations. Add confirmation gates for irreversible actions. For hard-stop gates, use strong language (e.g., "stop immediately with BLOCKED"). Add "stop on error" for sequential workflows
- Calibrate emphasis — Same rules as Optimization Phase 1 step 4. Safety gates keep strong language; operational preferences use normal language
- Avoid inherited duplication — Read CLAUDE.md and
.claude/rules/*. Do not duplicate content. Use single-line references (e.g., "Follow inherited secret handling rules")
- Size check — Target under 300 lines / 2,000 words. Run
wc -l and wc -w to verify
Phase 2: Validate (two parallel sub-agents)
Same as Optimization Phase 2, but the effectiveness review checks completeness rather than comparing to an original:
- Structural review: Same checks as optimization — frontmatter fields, description under 1024 chars, no workflow summary, examples have
<commentary>, max 2 examples, emphasis calibrated, output format and handoff protocol present. Return PASS/FAIL with specific issues and exact fixes.
- Completeness review: All System Prompt Structure sections present (at minimum: Persona, Workflow, Rules, Output Format). No inherited context duplicated. No Opus-known explanations. Domain-specific commands have non-obvious flags where needed. Return COMPLETE/INCOMPLETE with specific gaps.
Phase 3: Fix loop
If either validator returns FAIL/INCOMPLETE: dispatch a fix sub-agent with the specific issues and exact fixes. Then re-run Phase 2. Repeat until both validators return PASS + COMPLETE.
Optimization Workflow
Use sub-agents for each phase. Fresh context prevents sunk cost bias and keeps each step focused.
Phase 1: Optimize (sub-agent)
Dispatch an optimization sub-agent. Provide it with: the agent file path, this skill, and all inherited context files (CLAUDE.md, .claude/rules/*). The sub-agent follows these steps:
- Measure — Count lines (
wc -l) and words (wc -w). Identify largest sections
- Fix description field — Must comply with the Description Field section of this skill:
- Under 1024 chars (measure and verify). If over: trim to 1-2 examples, remove workflow summaries, shorten dialogue
- No workflow summary (lines like "Handoff flow: X → Y → Z"). Only capability + triggering conditions
- Every
<example> must contain <commentary> explaining why it triggers. Add if missing
- Max 2
<example> blocks
- Must have "When to use" and "When NOT to use" sections
- Remove inherited context — Read CLAUDE.md and every
.claude/rules/ file. Search the agent for duplicated content. Common: secret handling, git staging, research priority, domain substitution. Replace with single-line references (e.g., "Follow inherited secret handling rules")
- Calibrate emphasis — Soften CRITICAL/MUST/NEVER/FORBIDDEN/MANDATORY (see
references/anthropic-best-practices.md Section 3). Remove explanations Opus knows (Section 12). Safety gates (hard stops preventing data loss, secret exposure, skipping required inputs) keep strong language. Operational preferences (tool choice, workflow ordering, style) use normal language — no bold, no
CRITICAL, no blockquote emphasis
- Cut aggressively — Remove Opus-known content, inherited context, verbose examples. Agents are single files; do not extract. Keep: domain-specific commands with non-obvious flags, exact commit/git commands in self-improvement, behavioral anchors preventing shallow execution
- Verify frontmatter — All original fields must survive (
name, description, model, memory, tools). Missing tools silently grants all tools
Phase 2: Validate (two parallel sub-agents)
Dispatch two fresh sub-agents (no shared context with the optimizer). Both read: the optimized file, the original (via git show <pre-optimization-ref>:<path>), inherited context files, and this skill. Run in parallel:
- Structural review: Frontmatter fields survived. Description under 1024 chars, no workflow summary, examples have
<commentary>, max 2 examples. System prompt sections present. Emphasis calibrated (strong only on safety gates). Output format and handoff protocol present. Return PASS/FAIL with specific issues and exact fixes.
- Effectiveness review: Compare for lost domain-specific knowledge not in inherited context and that Opus wouldn't know. All workflow steps still represented. Domain commands with non-obvious flags preserved. Classify cuts as SAFE/RISKY/LOST. Return EFFECTIVE/DEGRADED/BROKEN.
Phase 3: Fix loop
If either validator returns FAIL/DEGRADED: dispatch a fix sub-agent with the specific issues and exact fixes. Then re-run Phase 2. Repeat until both validators return PASS + EFFECTIVE.
Common Mistakes
| Mistake | Fix |
|---|
| Workflow summary in description | Brief capability + triggering conditions only. Put workflow in body |
| CRITICAL/MANDATORY/NEVER overuse | Normal language. Claude 4.5/4.6 overtriggers on aggressive emphasis |
| 500+ line system prompt | Cut aggressively — remove what Opus knows. Target < 300 lines |
| No output format specified | Add structured output template |
| No examples in description | Add 1-2 <example> blocks with context/user/assistant/commentary |
| See full list | references/common-mistakes.md |
