prompt-engineer

Help the user design a new prompt or fix a weak one, using structure and technique choices instead of guesswork.

The request (or an existing prompt to refine): $ARGUMENTS

1. Clarify before writing

A prompt can't be judged good or bad without knowing what it's for. If not already stated, ask:

• Goal - what should the model do or produce?
• Audience/caller - a human end user, another agent, an API caller? This changes tone and format.
• Model or product surface - Claude or another LLM, and which surface (system prompt, tool description, few-shot example)? Constraints differ - a tool description is read by the model deciding whether to call the tool, not by an end user.
• Success criteria - how would the user know the output is right? One concrete example of a good and a bad output is worth more than a paragraph of description.

Skip this step only if the user already supplied enough of the above, or explicitly wants a quick draft to iterate on rather than a full interview.

2. Gather context when the prompt targets something real

A prompt aimed at a specific codebase, API, tool, or product surface should be grounded in that target, not written from recall:

• Prompt for/about code in this project (agent instructions, CLAUDE.md content, a tool description) - read the relevant files first so names, conventions, and constraints in the prompt match reality.
• Prompt that depends on current external facts (a provider's API shapes, model-specific behaviors, a library's idioms) - verify with a web search or the docs rather than trusting recall; a confidently wrong detail baked into a prompt propagates to every run of it.

Skip this step when the prompt is self-contained - pure style, tone, or reasoning instructions with no external referent.

3. Pick the mode

• Drafting a new prompt - go to step 4.
• Fixing an existing prompt that underperforms - go to step 5 first, then step 4 for the rewrite.

4. Structure the prompt

A well-structured prompt separates these parts, even if the final text blends them:

• Role/context - who the model is acting as, and any background it needs.
• Task - the actual instruction, stated as an imperative, not a description.
• Constraints and format - length, tone, what to include or exclude, exact output structure.
• Examples - the highest-leverage lever. One good example clarifies more than several sentences of instruction.

Pick techniques based on the goal - state what to do rather than stacking all of them by default:

• Few-shot examples - when the desired output has a specific shape or style that's hard to describe in words.
• Chain-of-thought / step-by-step instructions - when the task requires reasoning through multiple steps rather than a single lookup.
• Structured output (XML tags, a schema, headers) - when the output will be parsed programmatically or must have a reliable shape.
• Negative examples - when a plausible-looking wrong answer is common; show it and say why it's wrong.
• Explain why, not just what - rules the model understands the reasoning behind generalize better than rigid MUSTs; reserve hard imperatives for genuinely non-negotiable constraints.

5. Diagnose a weak prompt

Check an underperforming prompt against these failure modes, roughly in order of impact:

1. Vague verbs - "handle", "deal with", "process" instead of a concrete action.
2. No success criteria - the model can't tell a good output from a bad one either.
3. Missing examples - especially for a specific output shape or style.
4. Ambiguous or conflicting constraints - two instructions that can't both be satisfied; the model will pick unpredictably.
5. No output format spec - if the caller needs a specific structure, say so explicitly.
6. Buried instruction - the actual task is lost in a wall of context; move it near the top or the end (both are read more reliably than the middle).
7. Assumes shared context the model doesn't have - jargon, acronyms, or "the usual way" without defining it.

Point to the specific line or phrase causing each issue rather than giving generic feedback.

6. Iterate

After drafting or fixing a prompt:

• Ask the user for one real example input it needs to handle, if they have one. Trace through the prompt against that example and flag anything that would produce the wrong output.
• Prefer a small number of well-chosen examples and constraints over an exhaustive list - a prompt that tries to cover every edge case up front is harder to read and often self-contradicts.

7. Return

Give the user the prompt itself, clearly delimited in a fenced code block, followed by a short rationale only for the non-obvious choices - not a running commentary on every line.