| name | write-prompt |
| description | Write and review any document an AI will read and act on — system prompts, SKILL.md/CLAUDE.md/rules files, PRDs, GitHub issues, agent specs. If an AI reads it and acts on it, it's a prompt. |
| argument-hint | [review|migrate] |
/write-prompt — Structured Prompt Engineering
Write high-quality system prompts for AI agents or Claude Code skills. Guides through building or reviewing prompts using validated research on what actually works.
When to Use /write-prompt
- Writing a system prompt for an API call (Messages API, Bedrock, etc.)
- Writing a Claude Code skill (SKILL.md file)
- Creating or revising a CLAUDE.md or rules/*.md file (Claude Code reads and acts on these)
- Creating or revising a PRD (the prd-* skills read and act on these)
- Creating a GitHub issue (CodeRabbit and AI agents read and follow these)
- Reviewing an existing prompt or skill for anti-patterns
- Adapting a prompt from one model generation to another (e.g., Claude 4.5 → 4.6)
General rule: If an AI will read the document and take action based on it, run /write-prompt on it.
Proactive Invocation
Claude Code should use this skill — not ad-hoc writing — whenever it creates or modifies a document that an AI will read and act on. This includes:
- Creating new skills: When building a SKILL.md file for a Claude Code skill
- Writing system prompts: When building prompts for API calls (Messages API, Bedrock, etc.)
- Editing CLAUDE.md or rules/*.md files: Claude Code reads and acts on these
- Creating or revising PRDs: The prd-* skills read and act on these
- Creating GitHub issues: CodeRabbit and AI agents read and follow these
- Reviewing existing prompts: When modifying or debugging an existing prompt or skill
- Model migration: When adapting prompts after a model upgrade
The difference matters: ad-hoc writing misses anti-patterns, skips the five missing information categories, and produces instructions that fail in predictable ways. This skill applies validated research on what actually works.
Invocation
/write-prompt — start the guided workflow/write-prompt review — review an existing prompt or skill the user provides/write-prompt migrate — adapt an existing prompt for a different model- Claude Code invokes this workflow when prompt creation or review is part of a larger task
Phase 1: Gather Context
Ask the user these questions before generating guidance. Present them together using AskUserQuestion.
- Prompt type: Are you writing a system prompt for an API call, or a Claude Code skill?
- Target model: What model will this run on? (Claude Opus 4.6, Claude Sonnet 4.6, Claude 4.5/Haiku 4.5, other/unknown)
- Task type: What kind of task? (Code transformation, analysis/reasoning, content generation, tool-using agent, interactive workflow)
- Starting point: Are you starting from scratch, or do you have an existing prompt to improve?
If the user provides an existing prompt, go to Phase 3 (Review). Otherwise, proceed to Phase 2.
Phase 2: Build the Prompt
Guide the user through building the prompt section by section. For each section, explain what it should contain, ask the user for their specific content, then help them refine it.
Section ordering for system prompts (API calls)
Build the prompt in this order:
- Role and constraints — Who the model is, what it must not do, scope boundaries
- Context / schema / reference material — Background the model needs to do the job
- Explicit rules — Enumerated instructions, numbered for clarity
- Examples — 3-5 diverse examples (see Examples guidance below)
- Input data — Where the user's input will go (use XML tags or clear delimiters)
- Output format specification — The most precise section; exact format, what to include/exclude, what constitutes failure
- Operational metadata — Model identity, version constraints, any runtime notes
Section ordering for Claude Code skills
Skills run inside Claude Code, which already has its own system prompt, personality, and tool access. Adjust accordingly:
- Purpose and invocation — What the skill does, how it's triggered, what arguments it accepts
- Workflow steps — Procedural, numbered phases. Emphasize the process to follow rather than stating the goal upfront. This is critical for skills — Claude Code follows procedures more reliably than it infers intent from goals.
- Rules and constraints — Enumerated. Use negative constraints ("Do NOT...") for known failure modes. Use format specifications for completeness requirements.
- Output format — What the skill produces and how it should be structured
- Quality checklist — A list the skill checks before presenting output to the user
Skills do NOT typically need:
- Role framing (Claude Code already has one) — unless the skill requires behavior that differs from Claude Code's defaults
- Examples for output format anchoring — instead, reference style files on disk for skills that produce formatted content
- Input data section — skills receive input interactively
Guiding each section
For each section, do the following:
- Explain what belongs here (1-2 sentences)
- Ask the user for their specific content
- Draft the section based on their input
- Flag any of the five missing information categories (see below) that aren't yet addressed
- Move to the next section
After all sections are drafted, present the complete prompt and run the anti-pattern check (Phase 3).
Phase 3: Review for Anti-Patterns and Missing Information
Five categories of missing information
Check the prompt for these five categories that cause incorrect output (from Nam et al., "Prompting LLMs for Code Editing: Struggles and Remedies", April 2025, FORGE '26).
If reviewing a Claude Code skill (not an API prompt): skip categories 3–4 (faulty scope/localization and missing codebase context — skills receive input interactively) and skip the code transformation failure modes section unless the skill generates code.
- Missing specifics — The prompt says what to do but omits concrete details. "Refactor this function" without specifying which pattern, target structure, or what to preserve.
- Missing operationalization plan — The prompt states a goal but doesn't break it into steps. "Add error handling" without specifying where, what to catch, what to do in each case.
- Faulty scope/localization — The prompt doesn't clearly identify which parts to modify and which to leave alone.
- Missing codebase context — The prompt doesn't include surrounding code, types, imports, or conventions the model needs.
- Missing output format — The prompt doesn't specify what the output should look like — full file, diff, just the changed function, with or without fences.
For each gap found, explain what's missing and ask the user how to fill it.
Anti-patterns to flag
Flag these if present. Explain why each is harmful and suggest a replacement. Severity: [High] = impacts correctness or causes hard failures; [Medium] = impacts efficiency or reliability; [Low] = style preference with marginal impact.
Emotional/motivational language (always flag):
- [High] Tipping promises ("$200 tip for correct answer")
- [High] Disability/accessibility claims used as motivation ("I'm blind and can't read truncated code")
- [High] Threat-based motivation ("If you truncate code, bad things will happen")
- [High] Emotional appeals ("This is very important to my career")
These produce worse benchmark scores than baseline prompts. Format design choices have far more impact than motivational language. (Source: Aider unified diff research, https://aider.chat/2023/12/21/unified-diffs.html)
Model-version-dependent anti-patterns (flag based on target model):
For Claude 4.6 models only:
- [High] Vague anti-laziness directives ("do not be lazy", "try harder") — these are motivational language that amplifies already-proactive behavior, causing runaway thinking or write-then-rewrite loops. Instead, use explicit depth instructions ("comprehensive", "include edge cases") or format specifications ("Output format: complete source file. Files containing placeholder comments will fail validation."). (Sources: Anthropic best practices, platform release notes)
- [High] Prefilled responses on the last assistant turn — Opus 4.6 does not support prefilling assistant messages, and prefilling is incompatible with extended thinking. Use structured outputs (
output_config.format), XML tags, or direct instructions instead. (Source: Feb 5, 2026 release notes)
- [Medium] Explicit think-tool instructions ("use the think tool to plan your approach") — these cause over-planning. The model thinks effectively without being told to. Use the
effort API parameter (output_config.effort: low/medium/high/max) to control thinking depth instead of budget_tokens, which is deprecated for 4.6 models.
- [Medium] Aggressive tool-use language ("You MUST use [tool]", "If in doubt, use [tool]") — replace with "Use [tool] when it would enhance your understanding of the problem." Claude 4.x models overtrigger on aggressive language.
For Claude 4.5 and earlier:
- [Medium] The word "think" in Claude Code contexts when extended thinking is off — Claude Code treats "think" as a request for deeper extended thinking. In the raw API, extended thinking is controlled via the
thinking parameter, not prompt wording. For Claude Code skills, replace with "consider", "evaluate", or "assess" unless you intend to trigger deeper thinking.
Structural anti-patterns (always flag):
- [High] Single "golden" example instead of 3-5 diverse examples — risks overfitting to that example's details
- [High] Vague output format — "Return the result" instead of specifying exact format, delimiters, what to include/exclude
- [Medium] Positive aspirations without negative constraints — "Write clean code" is less effective than "Do NOT refactor existing code. Do NOT hallucinate imports not in the allowlist."
- [Medium] Goal-first structure in skills — skills should lead with process steps, not goals. The user's global CLAUDE.md says: "When creating prompts for AI agents, emphasize the process to follow rather than stating the goal upfront."
Known code transformation failure modes
When the prompt involves code transformation, check for guards against these documented failure modes (from Khati et al., "Detecting and Correcting Hallucinations in LLM-Generated Code", FORGE '26):
- Mis-typed API calls (incorrect method signatures, wrong parameter types): ~55% of hallucinations
- Hallucinated imports (inventing packages that don't exist): ~24%
- Incomplete edits / truncation: common with large inputs
- Lost semantics (subtly changing behavior while modifying code)
- Lazy code / elision ("// ... rest of function" placeholders)
- Variable shadowing
For each applicable failure mode, suggest a specific negative constraint to add.
Examples Guidance
When the prompt needs examples, guide the user to create effective ones:
- 3-5 examples minimum — more examples = better performance, especially for complex tasks (Anthropic multishot prompting docs)
- Diverse — cover happy path, edge cases, and cases where the model should NOT act (skip/refuse)
- Carefully crafted — bad examples are worse than no examples. Claude takes them literally.
- Wrapped in XML tags — use
<example> tags nested within <examples> for structure
- No single golden example — one perfect example risks overfitting to its specific details
Chain-of-Thought Guidance
When to recommend CoT:
- Analysis, reasoning, multi-step problems, decisions with tradeoffs
- Complex math, multi-step analysis, writing complex documents
When to recommend skipping CoT:
- Well-constrained transformations with explicit rules
- Repetitive format-following tasks
- Tasks where the output format is fully specified
For Claude 4.6 specifically: do NOT add CoT instructions to the prompt. Use the effort API parameter instead. The model's adaptive thinking handles this automatically. Adding explicit thinking instructions causes runaway thinking or write-then-rewrite loops.
(Source: Anthropic chain-of-thought docs, https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-of-thought)
Output Format
When reviewing a prompt, present findings as:
## Prompt Review: {brief description}
### Missing Information
{List each of the 5 categories with status: addressed / missing / partially addressed}
### Anti-Patterns Found
#### High Severity
{Anti-patterns that impact correctness or cause hard failures — fix before using this prompt. Include model-specific items (e.g., "Claude 4.6 only") inline here.}
#### Medium Severity
{Anti-patterns that impact efficiency or reliability — fix for production use. Include model-specific items inline here.}
### Style Notes
{Low-severity findings: style preferences with marginal impact. Omit this section if none found.}
### Strengths
{What the prompt does well}
### Suggested Revision
{The revised prompt, or specific sections to change}
Sources
All guidance in this skill is sourced from:
