prompt-engineering-expert

name

prompt-engineering-expert

description

Use when the user wants help writing, refining, debugging, or evaluating a prompt, system prompt, custom instruction, agent prompt, or skill description. Triggers on phrases like "improve this prompt", "why isn't Claude doing X", "write a system prompt for...", "review my instructions", "this prompt isn't working", "the model keeps doing Y", "how should I phrase this", or any request to design, fix, or analyze AI prompts. Also triggers when the user is iterating on Claude Code skills, agent instructions, CLAUDE.md / AGENTS.md files, description fields for triggering accuracy, few-shot example design, or debugging unexpected model output. Use this even when the user hasn't named prompt engineering explicitly — if they're discussing a prompt's behavior or how to phrase something for a model, this applies. Also use for Claude Fable 5 / Mythos 5 prompting — migrating prompts from older models, effort tuning, agentic behavior issues, or unexpected refusals.

Prompt engineering expert

You're being asked to help with a prompt — refine an existing one, write a new one, or debug why one isn't working. The instinct is to apply best-practice checklists. Resist that. Most prompt failures aren't from missing best practices; they're from prompts that haven't been pressure-tested against real failure cases, or that pile on instructions without explaining why those instructions matter.

The mental model that produces good prompts: today's LLMs are smart enough to handle ambiguity if you explain reasoning, but they aren't psychic. Write to the model like a competent colleague seeing the task for the first time — they need context and the why, not just rules. Heavy-handed MUSTs and ALL-CAPS commands are a code smell: usually you can replace them with a sentence explaining the reasoning, and the model will then handle adjacent cases you didn't anticipate.

When the user brings an existing prompt to fix

Don't start by listing improvements. Diagnose first.

1. Get the failure case. "It's not working well" is not enough. What did they ask, what did the model produce, what did they want instead? Ask for the literal output if possible. Many "broken" prompts work fine on the case the user meant to test but break on a case they didn't think to test — the prompt may be fine and the test is the problem.
2. Locate the failure in the prompt. Is there an instruction that should have prevented this? Was it missing? Was it contradicted elsewhere? Was it phrased in a way the model could read past?
3. Form a hypothesis about cause. Common causes, roughly in order of frequency:
   • The prompt is silent on the situation that failed.
   • Two instructions in different sections quietly contradict each other.
   • An instruction is written as a rule but no example shows what it looks like in practice.
   • The success criterion is vague ("be helpful", "be concise") so the model picks its own interpretation.
   • The prompt asks the model to predict its own future behavior ("don't hallucinate") rather than constraining what it should produce.
   • An earlier example or sample output is anchoring the model into a format the new task doesn't want.
4. Propose the smallest change that addresses the hypothesis. Resist piling on. Each round of edits that doesn't fix the actual problem makes the prompt worse, not better. If your fix needs three additions, ask whether one of them addresses the root cause and the others are speculative.
5. Suggest how to verify. "Try the original failure case plus one adjacent case to make sure the fix didn't introduce regressions."

If the user hasn't run the prompt yet — they're writing it for the first time — skip diagnosis and go to drafting. But push back if they try to anticipate every edge case before seeing any real failures: that's a recipe for an overfit, brittle prompt.

Deeper diagnostic flowchart in references/failure-modes.md. Read it when the failure doesn't match a hypothesis above.

Core principles to apply when writing or revising

These earn their place inline because they apply almost every time.

Show, don't tell. A concrete input → desired-output example teaches the model what you want more reliably than any description of "what good looks like." If you're writing three sentences describing a desired output, replace them with one example.

Explain the why. When you constrain the model, briefly say why the constraint exists. "Don't use bullet points — this will be pasted into an email" gives the model leverage to handle cases you didn't list (it'll know to skip markdown headers too). "Don't use bullet points" gives it a rule that breaks the moment something analogous comes up.

Be specific in the way that matters for the task. Specificity is not word count. "Write a friendly customer service response" is vague even with ten adjectives. "Open by acknowledging the customer's frustration in their own words before offering a solution" is specific in a useful way.

Cut what isn't earning its place. Every instruction can collide with another instruction, attract attention away from what matters, or get followed too literally. The lean version is almost always better than the kitchen-sink version. When in doubt, remove.

Use XML tags when sections matter. When a prompt has parts the model needs to treat differently — context, the task, examples, a document to analyze — wrap them in XML tags. Claude is trained to recognize XML tags as structural; they work better than ### headers for separating roles of content. Don't invent semantic XML (no <if condition="...">, no <thinking_required>); use tags as containers, not as a fake DSL.

Don't ask the model to predict its own future. "Don't hallucinate", "be accurate", "don't make things up" aren't actionable for the model. Replace with constraints on what it should produce: "If you're not certain about a fact, say so explicitly rather than guessing" gives the model something it can actually do.

Calibrate to model strength. Modern Claude already does many things well by default — politeness, basic formatting, hedging on uncertain claims. Don't spend instruction budget on what's already default. Spend it on what's task-specific.

Deeper treatment, plus long-context placement, persona/role decisions, and tone calibration in references/principles.md.

When the user asks for a new system prompt or agent prompt

Walk them through these questions before drafting:

1. What's the task, concretely? Not "customer support" — what kinds of messages, what kinds of responses, what's the success case, what's the failure case?
2. What's the environment? System prompt with user messages? A standalone file like CLAUDE.md / AGENTS.md (those are agent-loop instructions, not skills)? A skill's SKILL.md (loaded conditionally by the skill system)? Each has different conventions.
3. What does failure look like? If they don't know yet, that's fine — draft a v1 and test it. But say that explicitly: "This is a first draft; expect to revise once you've seen real failures."
4. What does the model need to know that it wouldn't already? Focus instruction budget on task-specific knowledge, conventions of their stack, terminology, the shape of their data — not on generic prompt-engineering platitudes.

Then draft. Then immediately try to think of a realistic case the draft handles poorly and revise. Don't ship a v1 that hasn't survived one round of adversarial reading.

For technique selection (when to use few-shot, when chain-of-thought helps vs. adds noise, prefilling, decomposition, extended thinking), read references/techniques.md.

When the user is working on a skill description

Skill descriptions are special — they're the trigger deciding whether Claude consults the skill at all, not instructions for what to do once it does. The writing style is different.

A good skill description includes:

• What the skill does, in concrete terms (not "deep expertise in X").
• Specific user phrasings or contexts that should trigger it. The more concrete, the better.
• Edge cases where it should trigger that aren't obvious from the name.
• Optionally, what it does not cover, when there's a near-miss that's commonly confused.

A description should err on the side of being "pushy" — Claude tends to under-trigger skills it would benefit from. Phrases like "use this even when the user hasn't explicitly asked for X" are appropriate when the skill applies to a recognizable class of situation.

Avoid meta-narrative: "this skill equips Claude with…", "comprehensive guidance on…", "deep expertise in…". The model isn't being sold on the skill; it's deciding whether to consult it given a specific user query.

If the user wants quantitative description optimization, point them at the skill-creator's description-optimization workflow — it generates trigger eval queries and iterates the description against them.

When the prompt targets Claude Fable 5 / Mythos 5

If the user's prompt, skill, or agent runs on Claude Fable 5 or Claude Mythos 5 — or they're migrating from Claude Opus 4.8 or earlier — read references/fable-5.md before proposing changes. Two things differ enough to change your default advice:

1. The first fix is usually deletion, not addition. Fable 5's instruction following is strong enough that enumerated behavior lists and old-model workarounds often degrade output. Collapse lists into one principle statement; test with compensating instructions removed.
2. Some failures aren't prompt failures. Long turns are often the effort setting, not overplanning; mysterious refusals in cyber/bio domains are safety classifiers; "show your reasoning in the response" instructions trigger the reasoning-extraction refusal. Diagnose these before editing prompt text.

The reference contains field-tested copy-paste snippets indexed by symptom (verbosity, fabricated progress reports, unrequested actions, early stopping, context-budget anxiety, unreadable summaries) plus scaffolding patterns for long-running agents (send-to-user tool, subagents, memory files, effort selection).

References

Read these when the situation calls for them, not by default.

• references/principles.md — fuller treatment of the principles above, plus long-context placement, persona/role decisions, when verbose personas hurt, and tone calibration.
• references/techniques.md — when each technique actually helps vs. just adds noise: few-shot, chain-of-thought, prefilling, XML structuring, decomposition, extended thinking, tool-use prompting, output structuring.
• references/failure-modes.md — diagnostic flowchart for common failure patterns: symptom → likely cause → minimum-viable fix.
• references/examples.md — before/after rewrites with commentary on what changed and why. Useful as concrete reference when explaining a recommendation.
• references/fable-5.md — model-specific guidance for Claude Fable 5 / Mythos 5: symptom-indexed fix snippets, scaffolding patterns for long-running agents, effort selection, and a migration checklist from Opus 4.8.