Write Agent Skill

Design agents that are focused, safe, and reliable without over-constraining them.

Key principle: treat tokens and attention as a shared budget. Prefer small, high-signal prompts plus strong output contracts over long prose.

How this skill uses supporting files

This skill includes optional supporting material in references/ and templates/.

When a workflow step says Load: path/to/file.md, open that file before continuing.
If you feel uncertain about a decision point, jump to the Reference Index at the end to find the right deep-dive.
Templates are starting points to customize, not rigid formats.

For non-trivial agent design: Consider reading all files in this skill folder before starting. Partial context can lead to inconsistent agents or missed patterns. This is especially valuable when designing orchestrators, updating existing agents, or working in an unfamiliar domain.

Operating Principles (for the agent designer)

These principles guide you as you write agent prompts:

Treat attention as scarce. The model's attention is O(n²) with context length. Every token competes for attention with every other token. Front-load critical instructions; move reference material to references/ files loaded on demand.
Optimize for reliability, not elegance. If a step is fragile or easy to mess up, add guardrails: a checklist, a validation loop, a "do X, not Y" constraint. Don't rely on the model inferring correct behavior.
Default to one strong path, with escape hatches. Provide a recommended default workflow. If alternatives exist, name them explicitly, but avoid option overload.
Write for execution. Use clear imperatives: "Do X. Then do Y." Avoid vague admonitions ("be careful", "be thorough") without concrete steps or outputs.
Match certainty to expression. Use "must" / "never" for hard requirements. Use "should" / "prefer" for strong defaults with exceptions. Use "consider" / "may" for suggestions. The agent parses this calibration.
Make agent prompts standalone. Assume a first-time reader with zero context. Don't rely on the agent inferring from prior conversation or parent state. For subagents specifically: don't reference other agents by name — write each as if it's the only agent that exists. (Orchestrators are the exception; they coordinate subagents by design.) If a subagent needs orchestration context, the parent passes it via handoff, not in the permanent prompt.
Use positive and negative framing appropriately. For routine guidance, positive framing ("Do X") is often clearer than prohibition ("Don't do Y"). But negatives are a valid, complementary tool — especially for exclusions, failure modes, and boundary definitions. When using negatives, make them concrete (not vague), pair with contrastive examples where helpful, and position critical constraints at section boundaries. See references/prompt-structure.md for technique details.

What to Produce When This Skill Is Used

When asked to "create an agent" / "write a subagent" / "make a reviewer" / "make an orchestrator":

Agent Brief (concise) — include assumptions if needed.
A ready-to-paste agent file (.claude/agents/<name>.md).
- If it's a subagent: single-purpose executor/reviewer.
- If it's a workflow orchestrator: multi-phase coordinator that uses the Task tool to spawn subagents.
Optional companion artifacts (only if they materially help):
- A skill (reusable workflow/knowledge)
- An output contract skill (shared schema for orchestrator aggregation — e.g., all reviewers preload pr-review-output-contract)
- A CLAUDE.md / .claude/rules addition (always-on constraints)
- A hook (for conditional tool gating / quality gates)

Keep explanation short. Prioritize concrete artifacts (files, templates, checklists).

Workflow

Create workflow tasks (first action)

Before starting any work, create a task for each step using TaskCreate with addBlockedBy to enforce ordering. Derive descriptions and completion criteria from each step's own workflow text.

Write-agent: Route request and build agent brief
Write-agent: Decide mechanism and strictness
Write-agent: Author config and write system prompt
Write-agent: Design handoff and add guardrails

Mark each task in_progress when starting and completed when its step's exit criteria are met. On re-entry, check TaskList first and resume from the first non-completed task.

0) Identify the request type

Determine which you're doing:

Create a new agent from scratch → continue with Steps 1–8 below
Update/refactor an existing agent → Load: references/updating-existing-agents.md and follow that procedure

If updating/refactoring an existing agent:

Critical: Before proceeding with any update work, you must complete Step 0: Full context loading from that file. This means reading:

Every file in the write-agent/ folder (SKILL.md + all references/ + all templates/ + all scripts/)
Every file related to the target agent (the agent file + any supporting files)
Any orchestrators that spawn this agent (if applicable)

Do not skip this step. Partial context loading is the primary cause of routing drift, capability creep, and broken output contracts during updates.

1) Choose the agent pattern: subagent vs workflow orchestrator

Quick gate: If you're unsure whether an agent is the right mechanism at all (vs a skill or CLAUDE.md rule), jump to Step 3 first. Otherwise, pick the lightest agent pattern that fits:

Need	Choose	Practical effect
One job, one output (review, implement, diagnose, summarize)	Subagent	Simple scope, easier to validate; usually no Task tool
Multi-phase workflow (research → plan → implement → judge → iterate)	Workflow orchestrator	Needs Task tool; coordinates phases, dispatches subagents, aggregates results
Isolation for a single task, but no multi-phase orchestration	Subagent (or a `context: fork` skill — ⚠️ unreliable for plugins, see Step 3 notes)	Avoid writing orchestration logic unless needed

Hard constraint: Subagents cannot spawn other subagents. So a workflow orchestrator must run as the top-level session agent (e.g., claude --agent feature-development …), not as a Task-spawned subagent.

CLI invocation note: Agents can be invoked directly via claude --agent <name> (interactive) or claude --agent <name> -p "prompt" (non-interactive). For spawning Claude Code subprocesses from within a running session (e.g., iteration loops), use the env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p ... pattern — this bypasses the nesting guard. Always set --dangerously-skip-permissions on subprocesses. See references/claude-code-mechanics.md for the full invocation reference including multi-level nesting.

Templates:

Subagents: templates/subagent-template.md, templates/subagent-reviewer-template.md, templates/subagent-worker-template.md
Orchestrators: templates/workflow-orchestrator-template.md
Deep guidance: references/workflow-orchestrators.md

2) Build an Agent Brief (fast, minimal)

Fill these fields. Ask questions only if missing info is blocking; otherwise assume sensible defaults and label them.

Pattern: Subagent | Workflow orchestrator
Job-to-be-done: What should it reliably accomplish?
Delegation triggers: What should cause Claude to use it?
Inputs: What context/files will it need? What can it assume is available?
Outputs: What format, audience, and verbosity?
Quality bar: What makes an output "done" vs "needs revision"?
Constraints: Hard rules (must/never) vs soft guidance (should/could)
Tools & permissions: Least-privilege tool access; permission mode choice
Model choice: Cost/speed vs reasoning needs
Failure strategy: When to ask vs proceed with assumptions

If it's a workflow orchestrator, also capture: phases, subagent roster, artifact strategy, quality gates, and iteration policy.

Load: references/workflow-orchestrators.md for the full orchestrator checklist.

If useful, copy/paste the brief template from references/prompt-structure.md.

Default starting point: Pick the closest template under templates/ and fill every [TODO] before you return the agent file.

Clarification strategy (when gathering info for the brief)

Use this decision table to reduce both under-asking and over-asking:

Situation	Do
Missing info that affects routing (delegation triggers), tool power, side effects, or compatibility	Ask 1-3 targeted questions before drafting.
User says "whatever you think is best" / signals indifference	Provide a specific recommendation plus 1-2 alternatives, then confirm the non-trivial choice.
Details are low-stakes and reversible (example wording, minor section names)	Use sensible defaults; list assumptions briefly so the user can correct if needed.

Question design (when you need human input):

Offer 2-4 clearly labeled options (not 5+, which creates decision fatigue).
Put your recommended option first and label it "(Recommended)" with a 1-sentence rationale.
Include "Other" when your options might not cover reality.
Frame questions around what changes based on the answer, not abstract preferences.

If you proceed with assumptions, label them as Assumptions: so they're easy to spot and correct.

3) Decide: agent vs skill vs always-on rules

Choose the lightest mechanism that reliably achieves the goal.

If you need…	Prefer	Why
Always-on repo constraints (commands, conventions, non-negotiables)	CLAUDE.md / .claude/rules	Applied everywhere; no routing needed
Reusable instructions that should run in the main conversation context	Skill	Reuse without context isolation; easy to invoke interactively
A single specialized worker/reviewer with tool restrictions	Subagent	Isolated context + least-privilege tools
A multi-phase pipeline that coordinates other agents	Workflow orchestrator	Encodes phase order, dispatch, aggregation, iteration

Notes:

Subagents cannot spawn other subagents. If you need multi-step specialization, orchestration must live in the top-level agent/session.
If you want a reusable workflow that runs "out of band", prefer:
- a skill with context: fork, or
- a workflow orchestrator agent invoked as the session agent.
⚠️ context: fork is unreliable (Issue #16803 — OPEN). Skills frequently run inline instead of forking, especially plugin skills (95%+ failure rate reported). If you need reliable isolation, use the Agent tool + Skill load pattern instead: spawn a general-purpose subagent and start its prompt with "Before doing anything, load /skill-name". The subagent loads the skill via its Skill tool and executes in isolation.

4) Pick the right strictness level (the "Goldilocks zone")

Agent prompts should hit the right altitude — specific enough to guide, general enough to generalize:

Failure mode	Symptom	Example
Too rigid	Brittle enumeration; breaks on unexpected inputs	"If .ts do X. If .tsx do Y. If .js do Z..."
Too vague	Abstract principles without concrete signals	"Be helpful and thorough."
Just right	Heuristics that generalize + clear escalation	"Prioritize correctness over style. When uncertain, ask."

Map task characteristics to strictness:

High freedom: heuristics + output contract (reviews, audits, brainstorming)
Medium: step sequence + required checks (refactors, migrations)
Low: scripts/commands + strict validation loops (fragile ops)

5) Author the agent configuration (frontmatter)

Set (verify each is present before moving on):

name: stable, hyphen-case, descriptive
description: concrete triggers + examples; avoid over-broad routing
tools / disallowedTools: least privilege
permissionMode: default unless you have a reason
model: haiku/sonnet/opus/inherit (choose intentionally)
skills: preload needed skills explicitly (don't assume inheritance)

CRITICAL: routing uses <example> blocks. Include 2–4 <example> blocks with <commentary> that teaches why delegation should (or should not) happen.

Subagents (recommended defaults):

Do not include the Task tool (no nested spawning).
Preload domain skills they use to judge/implement (e.g., skills: [write-docs]).
Strong output contract so an orchestrator can aggregate reliably.

Workflow orchestrators (recommended defaults):

Include the Task tool (plus minimum tools for repo inspection).
Do not assume spawned subagents inherit your skills: (they do not).
See references/workflow-orchestrators.md for dispatch, aggregation, and iteration patterns.

Minimal pattern (copy/paste and customize):

---
name: my-agent
description: Use this agent when <trigger conditions>. Avoid using it when <exclusions>.

<example>
Context: <situation that SHOULD delegate>
user: "<user message>"
assistant: "<assistant response before delegating>"
<commentary>
Why this matches the trigger conditions.
</commentary>
assistant: "I'll use the my-agent agent to…"
</example>

<example>
Context: <near-miss that SHOULD NOT delegate>
user: "<user message>"
assistant: "<assistant response that stays in the main thread>"
<commentary>
Why this is a near-miss / exclusion.
</commentary>
assistant: "<continue without delegating>"
</example>

# Optional:
# tools: Read, Grep
# model: sonnet
# permissionMode: default
---

# My Agent
...

Load: references/claude-code-mechanics.md for subagent constraints, permission modes, and skills composition patterns.

6) Write the system prompt body

Use a structure that optimizes for correct execution:

Role & mission (2–4 sentences) — includes personality statement
Scope and non-goals (avoid accidental overreach)
Operating principles (directness vs suggestions)
Workflow checklist (copy/paste-able)
Tool-use policy (what to read/grep/run; how to keep noise down)
Output contract (exact headings; verbosity limits; evidence expectations)
Handoff protocol (what to pass to subagents; what to return)
Questions/escalation (when to ask; when to proceed)

Writing the Role & mission section:

The Role & mission sets the agent's identity and judgment frame. It should:

Declare what excellence looks like for this role (not just what it does)
Describe behaviors the best humans in this role would exhibit
Avoid escape hatches that could license poor judgment

Load: references/personality-and-intent.md for patterns on writing effective personality statements.

Quick guidance:

✅ "You catch the issues that matter most — correctness, security, data integrity"
✅ "You focus on high-impact areas over cosmetic nitpicks" (safe tradeoff: nitpicks are anti-pattern)
❌ "You ship working code over perfect code" (risky: "perfect code" isn't an anti-pattern)
❌ "You are pragmatic and fast" (vague; can excuse poor work)

Orchestrator additions: If writing a workflow orchestrator, add explicit sections for phase plan, dispatch rules, aggregation rules, iteration policy, and artifact passing. See references/workflow-orchestrators.md and references/prompt-structure.md.

Style constraint: Write in second person ("You are…", "Do…"). Avoid first-person commitments ("I will edit files…") unless the agent is allowed and expected to do so.

Including failure mode awareness:

Good agent prompts don't just say what to do — they explicitly name the failure modes most likely to occur given the agent's task. This gives the agent self-correction targets.

Load: references/failure-modes.md for the full catalog of common LLM failure modes.

Include failure modes either:

As a dedicated "Failure modes to avoid" section (explicit, scannable), OR
Woven into operating principles ("Do X. Avoid the tendency to Y.")

Pick the 3-5 most relevant for the agent's context — don't include all of them.

Quick selection guide:

Agent type	Commonly relevant
Reviewer	Flattening nuance, Source authority, Asserting when uncertain, Padding/burying lede
Implementer	Plowing through ambiguity, Downstream effects, Instruction rigidity, Assuming intent
Orchestrator	Plowing through ambiguity, Never escalating, Assuming intent, Over-indexing on recency

The interpretation test (run on every instruction):

Before finalizing the prompt, verify each instruction passes these four checks:

Could this be read two ways? — If yes, add a clarifying example or "do X, not Y" constraint.
Does this assume context the reader won't have? — Agent prompts should be standalone; make implicit assumptions explicit.
Would a different model or instance interpret this the same way? — If you're relying on a specific interpretation that isn't explicit, make it explicit.
Is the directive strength clear? — Distinguish "must" (non-negotiable) from "should" (strong default) from "consider" (suggestion). Don't use vague "be careful" language.

Don't draft loosely and fix later — tighten language as you write.

Load: references/prompt-structure.md for the full prompt section breakdown.

Prompting technique notes:

Few-shot examples: 2–3 well-chosen examples outperform more. Order matters: place the most representative example last (recency effect). One weak example degrades all examples.
Positive framing: See Operating Principle #7. When possible, reframe "Don't respond when uncertain" as "Respond only when confident."
Effective negatives: Negative instructions work well when supported correctly. Use contrastive examples (incorrect vs correct), make constraints concrete (not vague), and position critical constraints at section boundaries. Note: caps/bold emphasis does NOT help — use structural techniques instead. See references/prompt-structure.md for details.

7) Design bi-directional context handoff

Subagents start "fresh," so don't rely on them remembering the parent chat.

Parent/orchestrator → subagent: provide a handoff packet (goal, constraints, target files, what "good" looks like).
Subagent → parent/orchestrator: return a return packet (TL;DR, findings, evidence, next actions, open questions).

Orchestrator artifact rule of thumb:

If a phase output is small (< ~2–3 KB), pass it forward in the next handoff packet.
If a phase output is large (plans, research notes, many findings), write it to a file and pass the path forward. This prevents token bloat and enables resume/fork workflows.

Error retention: When a subagent action fails, keep the failed action and error in the handoff context. This enables implicit belief updating — the agent learns what doesn't work without explicit "don't do X" instructions. Summarize patterns if errors accumulate, but don't strip them entirely.

Load: references/handoff-protocol.md for packet templates and iteration patterns.

8) Add guardrails that pay for themselves

Prefer guardrails that are:

Observable (checklists, validations, concrete criteria)
Specific ("run X and report Y")
Low-cost (don't burn tokens on generic admonitions)

Avoid:

huge encyclopedic prompts,
many parallel options with no default,
vague "be careful" language without steps or outputs.

Quality bar

Before returning an agent file, confirm:

Frontmatter includes: name, description with 2–4 <example> blocks, and the intended tools/disallowedTools.
description is neither too broad nor too narrow; examples include at least one near-miss exclusion.
Role & mission describes what excellence looks like (not just what it does); no risky escape hatches.
Failure modes: 3-5 contextually relevant failure modes are addressed (dedicated section or woven into principles).
Instructions pass the interpretation test: no ambiguous phrasing; no assumed context; explicit "do X, not Y" where needed; directive strength is clear.
Prompt body includes: mission, scope/non-goals, workflow, tool policy, output contract, and escalation rules.
Handoff + return packet formats are explicit (or referenced).

If workflow orchestrator, also confirm:

Includes phase plan, dispatch rules, aggregation rules, and iteration policy.
Acknowledges no-nesting constraint (must run as top-level session agent).

Designer self-check (before delivering):

Did I write any instruction that could be read two ways in a different context?
Did I assume context the agent won't have?
Are there places where I used vague language ("be careful", "be thorough") instead of concrete steps?
Did I mix up directive strengths (using "should" where I meant "must", or vice versa)?

If any answer is "yes," fix before delivering. Most agent underperformance traces to designer errors, not model limitations.

Implementation Output Format

When emitting files, output them like this (paths + code blocks):

path/to/file.md
(contents in a fenced code block)

Do not embed additional markdown prose inside the file unless it's part of the file's content.

Reference Index

This index helps you quickly find the right deep-dive. In the main workflow, follow the Load: pointers.

Priority legend:

P0 = must for correctness/reliability
P1 = improves quality and consistency
P2 = optional depth

References

Path	Priority	Use when	Impact if skipped
`references/updating-existing-agents.md`	P0	"Update" or "refactor" requests for existing agents	Intent drift; broken routing; capability creep; downstream orchestrator failures
`references/claude-code-mechanics.md`	P0	Configuring frontmatter, understanding constraints, permissions, composition, CLI invocation patterns (`--agent`, `-p`, `--resume`), and recursive invocation limits	Broken routing, permission errors, failed spawning, blocked recursive calls
`references/prompt-structure.md`	P0	Structuring the system prompt body; writing Role & mission, tool policies, output contracts	Missed steps, inconsistent outputs, unclear escalation
`references/failure-modes.md`	P1	Selecting which failure modes to guard against for this agent type	Agents exhibit predictable LLM blind spots
`references/personality-and-intent.md`	P1	Writing effective Role & mission statements; avoiding escape hatches	Vague identity, risky tradeoff framing
`references/workflow-orchestrators.md`	P1	Designing multi-phase orchestrators; dispatch, aggregation, iteration	Orchestrator missing key coordination patterns
`references/handoff-protocol.md`	P1	Designing handoff packets; structuring return packets; multi-phase chaining	Subagents lack needed context or return unusable results
`references/evaluation-and-iteration.md`	P1	Tuning delegation behavior; debugging over/under-triggering	Agents stay miscalibrated
`references/procedural-patterns.md`	P2	Writing validation loops, iteration policies, or error handling	Agents may infinite-loop, skip validation, or fail ungracefully
`references/designer-failure-modes.md`	P2	Debugging agent underperformance; reviewing prompts before delivery	Blame model for designer errors

Templates

Path	Use when
`templates/subagent-template.md`	Starting a generic subagent
`templates/subagent-reviewer-template.md`	Read-only reviewer (disallows Write/Edit)
`templates/subagent-worker-template.md`	Implementation-focused worker
`templates/workflow-orchestrator-template.md`	Multi-phase orchestrator (uses Task tool)
`templates/skill-fork-template.md`	Skill that runs in a forked subagent context

Scripts

Path	Purpose
`scripts/validate-agent.sh`	Validate agent file structure; catches missing `name`/`description` and warns on missing `<example>` blocks

write-agent