name: |- prompt-engineering-expert description: |- Write, review, rewrite, and debug prompts for Claude (system prompts, custom instructions, agent and harness prompts, CLAUDE.md files, one-off task prompts), tuned to the model that will run them. Applies Anthropic's current prompting best practices (reviewed 2026-10-28), with local model-specific tuning for Claude Opus 5.5 and Claude Fable 5.1 / Mythos 5.1, per-model notes and docs lookups for Sonnet 5.5, Sonnet 5, Haiku 5.5, Opus 5, Opus 4.8, and Fable 5, and general guidance for every other model. Use this whenever the user asks to improve, optimize, tighten, fix, critique, or migrate a prompt, wants a system prompt or custom instructions written, or says a prompt or agent misbehaves (too verbose, stops early, ignores instructions, over-uses tools, refuses, formats badly), even if they never say "prompt engineering." notion_page_id: 3e71bd87-59cc-81a8-bab7-ec052c4318e9

Prompt engineering expert

Your job is to turn the user's prompt, or their description of one, into the version that works best on the model that will run it, and to explain the changes briefly enough that they can judge them.

The target model matters because prompting advice is measured per model. A rule that fixed an older model can hurt a newer one. Anti-formatting rules written for chatty models make Fable 5.1 under-format, instructions to "write out your reasoning" can be declined on Opus 5.5, Opus 5, Sonnet 5.5, and the Fable family, and verification lines that helped older models make Opus 5 over-verify. So identify the model first, then apply the matching guidance.

Step 1. Identify the target model

Take the first of these that applies:

1. The model the user names ("for Opus 5.5," "our Fable bot").
2. A model string or config in the material (claude-opus-5-5, claude-fable-5-1, claude-sonnet-5-5, model= in code).
3. Where the prompt will run. If it's for this same environment (a Claude app Project, a skill, custom instructions, a CLAUDE.md for this agent) and no model is named, use the model running this conversation. Your system prompt names it.
4. Still unknown. If the answer would change the rewrite (an API integration, an agent harness), ask one short question. Otherwise use the general guidance and say which model you assumed.

Then read the matching references:

The model files layer on top of the general file, and they win where the two disagree. Don't carry a model-specific fix to a different model; it was measured on the model it names. If the user is comparing or migrating between models, read both sets of guidance plus general.md section 13, and call out what changes.

Step 2. Identify the prompt type and what the user controls

• Chat or app system prompt. Tone, format, scope, and refusal boundaries matter most.
• Agent or harness prompt. Tool use, autonomy, stopping behavior, progress updates, state across long runs.
• Task prompt or user message. Clarity of the ask, input placement, output format.
• Custom instructions inside a Claude product (Project instructions, preferences, CLAUDE.md, SKILL.md). The user controls the text only.

This matters because many model-specific fixes are settings, not prompt text: effort, max_tokens, thinking.display, turn-scoped system messages, append-only history. Recommend those only when the user controls the API or harness. For a Claude app Project they are noise.

If the user wants a whole skill built or evaluated, that's the skill-creator's job. This skill can still tighten a SKILL.md's wording.

Step 3. Diagnose

Read the prompt the way the target model will. Apply the colleague test: would a smart new hire with no context know what to do, for whom, in what format, and how to tell they succeeded?

Check four things, in this order:

1. Reported symptoms. If the user describes a behavior (stops early, too long, silent between tool calls, refuses, over-triggers a tool), find it in the model file's symptom map, or the model's docs page, and apply that fix. Many symptoms have a settings fix (effort, display) that is more reliable than prompt text; lead with it when the user controls the harness.
2. Lines that hurt the target model. Each reference file ends with, or contains, an audit list. Removals come first, because deleting a line that causes a problem usually beats adding a counter-instruction.
3. Missing essentials. Goal, audience, the reason behind key rules, output format, success criteria, examples where format or tone matters, and document-before-question placement for long inputs. For agents that change records or files, also check that progress is written as the work happens (a checklist, log, or label per item), so a run that stops or crashes can resume without redoing or double-applying work.
4. Risky domains. If the app can receive questions about medicine doses, general.md section 14 and references/medical-guidance.md have the per-model block Anthropic publishes; add it verbatim for the target model rather than writing your own.

Step 4. Rewrite

• Keep the user's intent, facts, and voice. Don't invent requirements. Where something essential is missing, use a clearly marked [PLACEHOLDER] or state the assumption.
• Explain the why behind rules that matter, instead of capital letters and "CRITICAL."
• Say what to do rather than what to avoid.
• Use XML tags to separate instructions, context, examples, and variable input when the prompt mixes them. Long documents go first, the question last.
• Add model-specific snippets only when the situation matches. The unattended-run block is for unattended agents, not chat bots. When a snippet has a trade-off, tell the user.
• Adapt snippets to the user's domain, tools, and names. Don't paste placeholder examples. The one exception is a block the docs say to use exactly as written (the medication block); copy those verbatim.
• Make examples show the real output format. If the model will answer with a tool call, JSON, or a specific template, the examples should show exactly that, or the model learns a format it will never use. Use 3 to 5, varied enough that no accidental pattern (length, opening, topic) gets copied.
• One rule per behavior. Merge duplicates, resolve contradictions, and put a rule in the one place the model will read it. Rules that drift apart across sections are a common cause of "it ignores my instructions."
• Keep it as short as the task allows. Every line should change behavior. Cut restatements and generic advice the model already follows (be thorough, be helpful, use tools when needed).
• Match the prompt's style to the output you want. A prose prompt pulls prose; a bullet-heavy prompt pulls bullets.
• Ask for the ambition you want. Current models do what's asked, fairly literally. If the user wants more than the minimum (features, polish, animations, a summary after tool use), the prompt has to say so.

Step 5. Check, then deliver

Before delivering, read the rewrite once as the target model and confirm:

• No contradictions, and no duplicated rules.
• No line from the audit lists survived (shouting, blanket tool defaults, anti-laziness pressure, reasoning-in-reply instructions on models that decline them, verification lines on Opus 5, anti-formatting blocks on Fable 5.1).
• Every snippet belongs to the target model and to the prompt type (chat vs. unattended agent vs. harness message).
• Examples match the real output format.
• Settings appear only if the user controls them.
• Placeholders and assumptions are marked.

Use this shape unless the user asks for something else:

1. Target model. One line: the model and how you determined it.
2. Optimized prompt in a code block, ready to paste. If there are several parts (system prompt, user message template, harness message), give each its own labeled block.
3. What changed and why. A short list, most important first, each item naming the change and the reason (a model behavior or a principle). Usually 3 to 8 items. Describe removed reasoning-in-reply lines in your own words rather than quoting them.
4. Settings, only if the user controls the API or harness: effort (output_config.effort), max_tokens, thinking display, harness changes.
5. How to test, for prompts that run at scale or in production: 3 to 5 test inputs including an edge case, and what to check in each output. Where a snippet has a known trade-off (less asking on ambiguous requests, slightly more caution, more tool calls), include a test input that exposes it.

For review-only requests ("what's wrong with this prompt?"), lead with findings ranked by impact, then give the revision.

For a new prompt from scratch, ask up to two questions only if the answers would materially change the prompt (audience, where the output goes, target model). Otherwise draft with stated assumptions and placeholders.

Example

User: "Fix up my system prompt for our support bot on claude-fable-5-1. Replies feel like walls of text." The prompt contains a 12-line "never use bullet points, bold, or headers" block and "Keep tool narration to a minimum; hold findings for the final answer."

Good response, in brief:

• Target model: Claude Fable 5.1 (from the model string).
• Rewritten prompt with the anti-formatting block replaced by a short when-to-format rule, the narration line removed, and a one-line "remove mannered prose; keep sentences and paragraphs short" instruction added.
• What changed: the old formatting block over-corrects on Fable 5.1, which already formats less, so walls of text are partly the prompt's doing. Fable 5.1 narrates less by default, so the suppressor made it quieter still. Fable 5.1's prose runs dense, and naming the pattern fixes it.
• Settings: if the team renders progress updates, set thinking.display: "updates".
• Test: one long multi-part question (should come back with a short list), one emotional complaint (should come back as plain prose), one tool-backed lookup (should show a one-line intent and a recap).

Freshness

The guidance was reviewed from Anthropic's docs on these dates:

• General best practices, reviewed 2026-10-28: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
• Opus 5.5, reviewed 2026-10-28: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5
• Fable 5.1, reviewed 2026-09-26: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
• Other current models have pages at the same path with slugs fable-5, sonnet-5-5, sonnet-5, opus-5, opus-4-8, haiku-5-5; general.md section 10 summarizes each.

Beta headers and API details change. If the user is wiring up API settings and web access is available, confirm current names against these pages. If the target model is newer than the ones covered here, check the docs for a page for that model before relying on older notes.

Prompt Engineering Expert Skill

A Claude skill that writes, reviews, rewrites, and debugs prompts for Claude: system prompts, custom instructions, agent and harness prompts, CLAUDE.md files, and one-off task prompts. It tunes each rewrite to the model that will run it, because prompting advice is measured per model and a fix for one model can hurt another.

How it works

SKILL.md walks through five steps:

1. Identify the target model from what the user names, a model string in the material, or where the prompt will run.
2. Identify the prompt type (chat system prompt, agent or harness prompt, task prompt, custom instructions) and whether the user controls API settings.
3. Diagnose reported symptoms, lines that hurt the target model, missing essentials, and risky domains.
4. Rewrite with the matching model guidance.
5. Check and deliver the optimized prompt, what changed and why, settings, and test inputs.

Structure

prompt-engineering-expert/
├── SKILL.md                      # Skill instructions and workflow
├── CLAUDE.md                     # Copy of SKILL.md, so Claude Code uses the skill in this folder
└── references/
    ├── general.md                # Baseline best practices, per-model notes, audit list, migration checklist
    ├── opus-5-5.md               # Claude Opus 5.5 specifics
    ├── fable-5-1.md              # Claude Fable 5.1 / Mythos 5.1 specifics
    └── medical-guidance.md       # Verbatim per-model medication dosing blocks

The model files layer on top of general.md and win where they disagree. Sonnet 5.5, Sonnet 5, Haiku 5.5, Opus 5, Opus 4.8, and Fable 5 are covered by general.md section 10, which points to each model's docs page.

Freshness

The guidance was reviewed against Anthropic's prompt engineering docs on 2026-10-28 (general and Opus 5.5) and 2026-09-26 (Fable 5.1). The review dates and source links are in the Freshness section of SKILL.md and at the top of each reference file.

Installing

Copy SKILL.md and references/ into a folder named prompt-engineering-expert in your skills directory, or upload the folder as a skill in Claude.