Prompt Writer

Prompt Writer

You are about to write or edit a prompt another Claude will execute. This skill is the playbook: rules, architecture, snippets, and worked examples for producing a high-signal prompt on the first try. Primary target is Claude Opus 5; the same patterns work on Sonnet 5 at lower cost and on Fable 5 above it.

Skim this body, jump to the reference that matches the task, fill in the template, validate against the checklist. The body carries the workflow; the references in ${CLAUDE_SKILL_DIR}/references/ carry the depth.

Ground before you write

Do not author a prompt from your own built-in knowledge alone. Parametric knowledge is frozen at the training cutoff; the world the prompt runs in is not. Two grounding passes come before the first line, every time.

• Read the actual target. When the prompt names an existing file, agent, skill, command, or symbol, open it first with Read, Grep, Glob, or ac:explore. Editing an existing prompt means reading its current body and the references it points at, not recalling what it likely says. A prompt built on a guessed file shape ships the guess.
• Verify against fresh sources. Model behavior, effort and thinking parameter shapes, API surfaces, SDK signatures, and library or framework features shift between versions, so built-in knowledge goes stale (a Laravel Horizon balancing option you "know" from the training cutoff may have changed in the latest release). Confirm anything version-sensitive against current canonical docs through ac:librarian or the ac MCP web tools (web-search, web-fetch, search-docs) before you state it as fact, and cite what you found.

When your built-in knowledge disagrees with the file or a fresh source, the file and the source win.

Decision flow

Route by what you are about to produce. Each branch points at a reference for the depth.

Writing a SKILL.md body (any Claude Code skill)?
├── YES → use this skill for the prompt body, route the skill SHAPE
│         (frontmatter, scope, invocation, bundling) through `skill-creator`.
└── NO  → continue
        ↓
Writing the body of a slash command (/name [args])?
├── YES → use this skill for the prompt body, route the command SHAPE
│         (arguments, allowed-tools, shell injection) through `command-creator`.
└── NO  → continue
        ↓
Writing a custom subagent definition (.claude/agents/<name>.md)?
├── YES → use this skill for the system-prompt body, route the agent SHAPE
│         (tools, model, permissions, isolation) through `agent-creator`.
│         Then read `${CLAUDE_SKILL_DIR}/references/subagent-prompts.md`.
└── NO  → continue
        ↓
Writing CLAUDE.md, CLAUDE.local.md, or .claude/rules/*.md?
├── YES → use this skill for content tone and structure, route the file SHAPE
│         (scope, paths:, @imports, loading order) through `claude-md-rules-creator`.
└── NO  → continue
        ↓
Briefing a fresh Agent tool call (no custom subagent_type)?
├── YES → `${CLAUDE_SKILL_DIR}/references/subagent-prompts.md`
└── NO  → continue
        ↓
Auditing or improving an existing prompt?
├── YES → `${CLAUDE_SKILL_DIR}/references/anti-patterns.md` FIRST,
│         then `${CLAUDE_SKILL_DIR}/references/architecture.md`.
└── NO  → use the Quick template below; validate against the Quick checklist.

Core principles

The ten rules that change outcomes the most. Detail lives in the references.

1. Static in system, dynamic in user. Persona, schema, examples, invariants go in the system prompt so prompt caching can amortize them. Per-request data (the document, the question, the file under review) goes in user messages.
2. Wrap every distinct block in XML tags. Claude is fine-tuned to parse XML. Tag boundaries are the only reliable way to separate instructions from data. Use descriptive, consistent names: <role>, <context>, <examples>, <input>, <output_format>.
3. Tell the model what to do, not what to avoid. "Provide concise responses" beats "do not be verbose." Negative instructions force the model to imagine the wrong behavior first.
4. State scope explicitly, in both directions. Where a rule must span, say so: "apply to every X, not just the first." Where the task must not widen, say that too: Opus 5 can expand scope and over-verify on its own, so name the boundary ("change only these files; report adjacent problems instead of fixing them").
5. Examples are the highest-leverage tool for gray areas. 3 to 5 diverse, labeled examples beat any abstract instruction. Wrap each in <example> inside <examples>. Cover edge cases.
6. Repeat the top constraint right before generation. Recency wins. End the prompt with the one or two rules the model must not break.
7. No "CRITICAL: you MUST" language. Modern Claude overtriggers on aggressive wording. Plain instructions work; if a rule needs weight, explain the why.
8. Structured Outputs over prefill. Prefilling the last assistant message returns a 400 error on Claude 4.6 and later. Use Structured Outputs, tool calls with enums, or wrap the output shape in XML tags inside the user turn.
9. Set scope before length. A short prompt with the right scope outperforms a long prompt with hedges. Hedges introduce ambiguity, the model fills it with priors.
10. The colleague test. Show the prompt to someone with no context. If they would be confused, the model will be too.

Standard architecture

Place components in this order. Skipping any is a choice, not a default.

For inputs above 20k tokens the order inside the user turn flips: long documents at the very top, instructions and the actual question at the bottom. This can move quality up to 30 percent on multi-document tasks. Full detail in ${CLAUDE_SKILL_DIR}/references/architecture.md.

Quick template

Fill this in. Strip components you do not need with intent.

<!-- SYSTEM PROMPT -->
<role>
You are [persona, one sentence: who, domain, tone].
</role>

<context>
[Static facts the model cannot derive: schemas, business rules, shape of the input. Cacheable.]
</context>

<examples>
  <example>
    <input>[representative input]</input>
    <expected_output>[exactly what the model should produce]</expected_output>
  </example>
  <!-- 2 to 4 more, diverse, covering edge cases -->
</examples>

<output_format>
[Shape: XML tags, JSON schema reference, plain prose, etc.]
</output_format>

<!-- USER MESSAGE -->
<input>
[The actual per-request data]
</input>

<instructions>
1. First, [process the structured part of the input].
2. Then, [interpret the ambiguous part using the structured baseline].
3. Finally, [produce the output in the shape specified above].
</instructions>

<reminders>
- [Top constraint, e.g., "cite the specific input region for every claim"]
- [Scope constraint, e.g., "apply to every section, not just the first"]
</reminders>

Model tuning knobs (Claude Opus 5)

Default target is claude-opus-5 (released 2026-07-24). Sonnet 5 (claude-sonnet-5) follows the same patterns at lower cost; Haiku 4.5 (claude-haiku-4-5-20251001) differs on effort and thinking. Full per-knob detail in ${CLAUDE_SKILL_DIR}/references/opus-5-tuning.md.

Two 4.8 defaults inverted. A prompt tuned for Opus 4.8 now overcorrects on Opus 5. Verbosity: 4.8 self-calibrated to task complexity, Opus 5 runs longer by default and effort does NOT reliably shorten it, so state an explicit length target. Subagent spawning: 4.8 spawned fewer unprompted, Opus 5 delegates more readily, so say when NOT to spawn and drop 4.8-era fan-out encouragement.

Effort. Five levels, default high. xhigh for coding and agentic work; medium only with cost or latency justification; low only for short scoped tasks; max for the hardest problems (diminishing returns past xhigh). Set max_tokens to ~64k at xhigh or max. Opus 5 converts extra effort into better results more reliably than any earlier Opus, so raising effort beats papering over shallow reasoning with prompt instructions. Effort is not a length lever on Opus 5. Haiku 4.5 does not support the parameter at all.

Thinking. On by default on Opus 5, Sonnet 5, and Fable 5. thinking: { type: "adaptive" } remains valid and equals the default, so the explicit enable 4.8 required is now redundant. Manual { type: "enabled", budget_tokens: N } returns a 400 error. { type: "disabled" } returns a 400 error at effort xhigh or max; disable only at high or below. On Haiku 4.5 the situation is inverted: manual extended thinking is the only accepted shape and adaptive is rejected. Add display: "summarized" when the UI needs to render thinking content.

Scope and over-verification. New on Opus 5: the model can widen a task's scope on its own and re-verify work it already verified. Name the boundary ("change only these files; report adjacent problems instead of fixing them"; "verify once, do not re-run passing checks").

Verbosity. Longer by default than prior Opus models, and effort will not shorten it. Ask positively with a target ("Lead with the answer in one or two sentences, then at most three supporting points"). State a produced artifact's length separately from conversational length.

Tool use. The 4.8 page documented a bias toward reasoning over tool calls; the Opus 5 page has no equivalent section, so treat the bias as undocumented rather than assumed. Describe when and how to reach for a tool explicitly, and avoid "CRITICAL: ALWAYS use this tool" wording either way.

Prefill is gone. Prefilling the last assistant message returns a 400 error on Claude 4.6 and later. Use Structured Outputs, tool calls with enums, or direct instruction wrapped in XML tags.

Unchanged from 4.8. Sampling parameters (non-default temperature / top_p / top_k return 400), tokenizer, 1M context, 128k max output, image coordinates 1:1 with actual pixels, and $5 / $25 per MTok pricing.

When the prompt runs inside Claude Code

Respect the harness defaults; do not restate them. Full detail in ${CLAUDE_SKILL_DIR}/references/claude-code-conventions.md.

• Terminal markdown rendering. User-visible text renders as GitHub-flavored markdown. Reference code as file_path:line_number (clickable).
• Permission denials are signal. A denied tool call means the user declined. Adjust the approach; do not retry verbatim.
• <system-reminder> tags are harness, not user. Treat as system signal; do not respond to them in user-visible output.
• Hooks intercept tool calls. A hook blocking an edit is feedback; do not retry the same edit.
• Parallel tool calls. Independent reads, searches, or fetches go in one assistant message with multiple tool-use blocks.
• Software engineering frame is the default. Generic instructions are interpreted in the working directory's context.
• Code style defaults inherited from the CC system prompt: no comments unless WHY is non-obvious; no backwards-compatibility shims; no error handling for impossible scenarios; no planning files unless asked; match adjacent code style.
• Communication during tool use: one sentence before the first call, one sentence per find/change-of-direction/blocker, no narration of internal deliberation, end-of-turn summary in one or two sentences.
• Reversibility gate: free for local edits and tests; confirm before destructive, hard-to-reverse, externally-visible, or third-party-upload actions.

Sibling skills (route the surrounding shape)

This skill stays focused on the prompt itself. The shape around the prompt routes through one of the following sibling skills.

When the user request implies any of the rows above, do both: invoke the matching creator for shape, then keep this skill loaded for the prompt body. When in doubt, default to this skill; the creators reference back to it for the body.

Quick template for common shapes

Subagent briefing (Agent tool call). Brief like a smart colleague who just walked in. Goal, what you already learned, surrounding context, length cap, response shape. Full detail in ${CLAUDE_SKILL_DIR}/references/subagent-prompts.md.

Audit `packages/*/src/**/*.ts` for unused exports.

Context: TypeScript monorepo. "Unused" means zero imports across the monorepo. Use ts-prune or write your own grep-based check.

I have already ruled out: ESLint's no-unused-vars (it does not cross packages).

Report: a list of `file_path:line_number` entries grouped by package. Under 500 words. If you cannot find unused exports with confidence, say so and explain what tooling you tried.

Custom subagent definition (.claude/agents/<name>.md). Bounded description, explicit tools, decisional steps, locked output contract.

---
name: code-reviewer
description: Reviews a diff for bugs, design problems, convention breaks and missing tests. Returns every issue it finds, low severity included. Use when a change is ready for a second read; an edit whose whole diff you have already read does not need it.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer.

## Decision rules
1. Read the diff and the surrounding code.
2. Check bugs, design, conventions, tests in that order.
3. Report every issue, including low-severity. Downstream filter handles ranking.

## Output contract
Markdown report with one section per finding:
- `file_path:line_number`
- Confidence (low / medium / high)
- Severity (nit / minor / major / critical)
- Suggested fix

Five more worked examples (document-extraction system prompt, long-document RAG, slash command body, meta-prompt) live in ${CLAUDE_SKILL_DIR}/references/worked-examples.md.

Snippet library (most useful starters)

Categorized copy-paste building blocks. Mix and match; each is a fragment, not a finished prompt. Full library in ${CLAUDE_SKILL_DIR}/references/snippets.md.

Hallucination control.

Never speculate about code you have not opened. If the user references a specific file, read it before answering. For every factual claim, cite the source: `file_path:line_number` for code, a document tag for retrieved data, or "general knowledge" for things not in the input.

Parallel tool use.

If you intend to call multiple tools and there are no dependencies between them, make all of the independent calls in parallel. When reading 3 files, run 3 tool calls in parallel. Sequential only when call N depends on call N-1. Never use placeholders or guess missing parameters.

Output format.

Place your final answer inside `<final_answer>` tags. Do not include any text outside the tags. Respond directly without preamble; do not start with "Here is...", "Based on...", "I'll...".

Verification.

Before you finish, verify your answer against:
- [criterion 1, specific and falsifiable]
- [criterion 2]
If verification fails, revise and verify again. Only return when all criteria pass.

Long-horizon agents.

Your context window will be compacted as it approaches its limit; you can continue working indefinitely from where you left off. Do not stop tasks early due to token budget. Save current progress to memory before the context refreshes.

Anti-patterns (audit existing prompts for these)

Surface-level set; the full audit checklist with the why behind each fix is in ${CLAUDE_SKILL_DIR}/references/anti-patterns.md.

Pre-flight checklist

Before shipping a prompt:

• Persona, domain, tone stated in the system prompt.
• Static content (schema, examples, invariants) in system; dynamic in user.
• Every distinct block wrapped in named XML tags.
• 3 to 5 diverse examples covering edge cases.
• Instructions ordered: process structured input first, ambiguous second.
• End-of-prompt reminders restate the top 1 to 3 constraints.
• Scope stated explicitly ("every X, not just the first").
• No "CRITICAL / MUST / ALWAYS" language.
• No prefill on the last assistant turn.
• Output format locked via Structured Outputs, tool call, or XML tag.
• If input above 20k tokens: documents at top, question at bottom.
• Effort level set via output_config={"effort": ...} and matches task complexity.
• Thinking parameter shape matches the model: default-on adaptive on Opus 5, Sonnet 5, and Fable 5 (manual enabled + budget_tokens returns a 400 error on all three; disabled returns 400 above effort high on Opus 5); manual enabled + budget_tokens only on Haiku 4.5, which rejects adaptive.
• No effort set for Haiku 4.5 (the parameter is unsupported on that model).
• Every fenced command in the body has been run, in the shell it will actually run in, and its output matches what the surrounding prose claims (see ${CLAUDE_SKILL_DIR}/references/claude-code-conventions.md).
• Length controlled by an explicit target, not by lowering effort.
• Scope boundary named, not just scope span.
• Output shape lock uses output_config.format (Structured Outputs), tool call with enum, or XML wrap; not the deprecated top-level output_format or last-assistant prefill.
• No effort-2025-11-24 beta header; client.messages.create (not client.beta).
• Colleague test passes.

References

Source material for these references is Anthropic's canonical documentation served as raw markdown by appending .md to the URL (the suffix returns LLM-friendly raw markdown instead of the JS-rendered HTML page). Two hosts: API and model docs at https://platform.claude.com/docs/en/<path>.md, Claude Code docs at https://code.claude.com/docs/en/<path>.md. The former docs.claude.com host now redirects to platform.claude.com and does not serve the Claude Code pages. Anchor URLs cited inline in each reference file. When canonical docs conflict with observed CLI behavior, trust the live binary.