- 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/
.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
- 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)
- 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
- (interactive) or
- claude --agent
-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
- --max-turns
- and
- --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.
- (Be aware some environments have reliability issues with
- context: fork
- .)
- 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
blocks. Include 2–4 blocks with 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 : "
" assistant : " " <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 : "
" assistant : " " <commentary Why this is a near
miss / exclusion. </commentary
assistant : "
" </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