| name | writing-claude-5-prompts |
| description | Use when writing, rewriting, reviewing, shortening, or handing off prompts, system prompts, agent briefs, skills, CLAUDE.md files, or task specifications targeting Opus 5 or Fable 5 — including when a prompt was tuned for an older model, has grown repetitive or over-scaffolded, or is unclear about scope, autonomy, evidence, output length, or stopping. Not for prompts whose primary result is a visual artefact; writing-claude-design-prompts owns those. |
Writing Claude 5 Prompts
Principle
Write the smallest prompt that preserves the contract. These models infer intent and choose method well; specify the destination, the boundaries, the evidence, the output and the finish line, and prescribe the route only when the route itself is the requirement.
The failure mode with this generation is not vagueness. It is accumulated scaffolding — rules written for weaker models that now fight the model's own judgement, and duplicated instructions across system prompt, project file and skill that cost reasoning to reconcile.
The keep/cut test for any rule: does it correct a measured default behaviour of this model, or does it guard against a failure this model no longer has? Keep the first. Cut the second.
Method
1. Fix the target
Establish which model, which surface (API, Claude Code, skill, project file), and whether the prompt takes actions or only advises. If the target model isn't stated, ask — the two models pull in opposite directions on verbosity, verification and effort.
If the prompt's primary result is a visual artefact — a design, frontend, redesign, prototype, design system or image-to-code implementation — hand composition to writing-claude-design-prompts. That skill writes a creative commission rather than the goal contract in step 3, and its framing supersedes this one. Steps 2, 4 and 5 here still apply: the deletion pass, the model levers and the effort knob are model-level and hold whatever the prompt is for.
If the prompt touches offensive security or life sciences and the target is Fable 5, flag it in your response and recommend routing that work to Opus instead. Those domains hit Fable's safety classifiers and return stop_reason: "refusal" — even for benign work — and no prompt wording avoids that; the fix is configured fallback (to Opus 4.8), which is a harness change, not yours to write into the prompt.
2. Delete first
Before writing anything, strip legacy scaffolding. Anything on this list is dead weight or actively harmful:
| Strip | Why |
|---|
| "double-check", "re-verify", "add a verification step" | Opus 5 self-verifies; these compound into over-verification and burn tokens with no quality gain |
| "think step by step", "think harder", "be thorough" | Effort is a parameter now — see step 5 |
| "show your reasoning", "explain your thinking", "echo your plan" | Can trigger the reasoning_extraction refusal on Fable 5 and silently fall back to a weaker model. Read the structured thinking blocks instead |
| Assistant prefill on the final turn | Returns 400 from 4.6 onward |
thinking.budget_tokens | Returns 400 from 4.7 onward |
| "CRITICAL: You MUST use X" | Overtriggers. Plain "Use X when…" is enough |
| Few-shot examples that exist to teach tool usage | They narrow the exploration space. Move the guidance into the tool description and make the parameters expressive instead |
| Blanket worst-case guardrails ("never write comments", "never create files") | Wrong for a large fraction of requests. Replace with a contextual statement: match the surrounding code's comment density and idiom |
| The same rule restated in system prompt, CLAUDE.md and skill | Conflicting overlaps have to be reconciled before the model can act |
Examples still work well for output format, tone and structure — 3–5 of them, in <example> tags. It is examples-as-behavioural-training for tools and agentic flow that now costs more than it gives.
3. Write the contract
Include a section only where it changes behaviour:
- Outcome, and the reason for it. These models connect the task to relevant context when they know what the output is for.
I'm doing [larger task] for [audience]; they need [what it enables]. So: [request].
- Truth sources. Which file, spec, schema or command is authoritative when sources disagree.
- Scope. What is in, and — where it matters — what is explicitly out.
- Autonomy. Reversible work proceeds; name the irreversible actions that need a check-in. State this once.
- Output. Format, audience, and a length calibration. Both models write long by default.
- Done. What evidence proves completion, and the stop condition.
Express judgement calls as decision rules with observable triggers, not adjectives. Reserve absolutes for genuine invariants.
4. Counter the known defaults
Each model over-does a few things by default — Opus 5 around length, narration, scope and delegation; Fable 5 around planning, progress claims, unrequested actions and shorthand summaries. Open references/model-deltas.md, and for each behaviour that would cost something on this task, add its lever to the prompt — references/snippets.md has tested wording to adapt. Add nothing for behaviours the task can't surface; a brief instruction steers as well as an enumerated list used to.
5. Depth problems are knob problems
Effort is set in the client or the API request, not in prompt text. From inside a prompt you can do exactly two things with it:
- Strip wording that simulates it. "Think harder", "be thorough", "reason step by step" — already in the deletion table.
- Surface the knob instead of padding the prompt. If reasoning looks shallow, the recommendation to whoever runs the prompt is "raise effort", not more words. The reverse too: if Opus 5's answer is too long, that's a prompt fix (length calibration) — effort controls thinking volume, not visible response length.
Only when the deliverable includes the run configuration itself — an API request, a pipeline spec — do starting values matter; take them from the effort-and-parameters section of references/model-deltas.md.
6. Final check
- Every instruction changes behaviour, and appears exactly once.
- Success is objectively recognisable; the stop condition is explicit.
- Autonomy and approval boundaries are unambiguous wherever action is possible.
- Every prescribed step is justified by an invariant, not by habit.
- Nothing duplicates a tool description, a schema, or a harness rule.
- No verification, self-check, or show-your-reasoning instruction survived step 2 without a reason.
- The prompt preserves the user's requirements and invents none.
Return the finished prompt only, unless analysis, alternatives or a change log were asked for.
Related references
references/model-deltas.md — behaviour-to-instruction map for both models, plus effort and parameter starting pointsreferences/snippets.md — reusable instruction blocks, grouped by problemreferences/context-engineering.md — system prompts, CLAUDE.md, skills, tool descriptionsreferences/discovering-unknowns.md — for when the requirement isn't clear yetreferences/source-map.md — what came from where, and what was deliberately left out
House defaults
Personal conventions, not laws — drop them when a task argues otherwise.
- Prefer role separation on multi-step work: an orchestrator that schedules and verifies, a worker that executes one subtask.
- One small change per loop, with a generous verification budget.
- Name the truth source explicitly rather than relying on the model to pick.
- Include a
HANG ON A SECOND escape hatch so the worker can halt instead of guessing.
- Warn when the right approach requires amending the PRD or contract, rather than quietly working around it.
- British spelling in prose output.
