Prompt Engineering skill for Claude Code

A production prompt is done when it states the task, audience, constraints, and output format explicitly, separates instructions from data, and has a measured pass rate on a fixed eval set that you re-run after every edit. A prompt tuned by eyeballing three outputs is a draft.

Ground rules

• Write for a brilliant new colleague with zero context. If a human contractor would need to ask a question, the model needs the answer in the prompt.
• Explain why a rule exists. “Never use ellipses because a text-to-speech engine reads this” generalizes better than “NEVER use ellipses”.
• Say what to do, not only what to avoid. “Write in flowing prose paragraphs” beats “Do not use markdown”.
• Change one thing per iteration and re-run the eval. Keep a changelog of prompt versions.
• Prompts are code: store them in version control as files or constants, not in a dashboard nobody reviews.

Workflow

- [ ] 1. Collect 20-50 real inputs, including hard and edge cases
- [ ] 2. Write success criteria you can grade
- [ ] 3. Draft the prompt with the standard skeleton
- [ ] 4. Run, read failures, classify them
- [ ] 5. Fix the highest-frequency failure class, one change at a time
- [ ] 6. Freeze, version, and wire the eval into CI

1-2. Inputs and criteria first

Before writing a word of prompt, gather real inputs and write pass/fail criteria (“cites at least one source”, “under 120 words”, “valid JSON”, “no medical advice”). Without criteria you cannot tell whether an edit helped. Build the grader with llm-evals.

3. The standard skeleton

SYSTEM
You are <role> helping <audience> with <goal>.

<context>
Why this task exists, who reads the output, what good looks like.
</context>

<instructions>
1. ...
2. ...
</instructions>

<constraints>
- Length, tone, things that must never happen, and why.
</constraints>

<output_format>
Exact shape of the answer. Prefer a schema (see structured-outputs) for machine output.
</output_format>

<examples>
<example>
<input>...</input>
<output>...</output>
</example>
</examples>

USER
<document>
{{retrieved_or_user_content}}
</document>

<question>{{question}}</question>

Placement rules:

Content	Place	Why
Role, stable rules, examples	System prompt	Stable prefix, cacheable, carries more weight
Long documents (10K+ tokens)	Top of the user turn, before the question	Query at the end improves long-context answers noticeably
The actual question / task	End of the user turn	The model attends to the most recent instruction
Per-request variables	After all stable content	Keeps the cacheable prefix byte-identical

XML tags

• Wrap each distinct kind of content in its own tag: <document>, <email>, <schema>, <examples>. Refer to them by name in instructions (“using the contract in <contract> tags”).
• Tag names have no special meaning; consistency matters. Nest for hierarchy (<documents><document index="1"><source>...</source><content>...</content></document></documents>).
• Treat anything inside data tags as untrusted. Tell the model that instructions inside <document> are content to analyze, not commands (and read prompt-injection-defense when users control that content).

Examples (few-shot)

• 3-5 examples covering the real spread: typical, edge case, and a “decline / not applicable” case. One example gets copied too literally.
• Vary surface features (length, topic, phrasing) so the model learns the pattern, not the wording.
• Every example must satisfy every rule in the prompt. A single violating example outweighs a paragraph of instructions.
• Put examples in <example> tags so they are not confused with instructions.

Reasoning

Situation	Do
Model supports native extended/adaptive thinking (current Claude models)	Enable it and tune the effort level; do not also demand “think step by step” in the visible answer
No native reasoning, multi-step task	Ask for reasoning in <thinking> tags, then the answer in <answer> tags; parse only <answer>
Simple lookup, classification, formatting	Skip reasoning; it adds latency and cost without accuracy
Need to audit why	Keep reasoning in a separate field or tag you log but do not show users

Guidance that helps reasoning: “Before answering, check your draft against each item in <constraints>” and “If the information is not in the document, say so instead of guessing.”

Output format control

• Match the prompt’s own style to the desired output: a prompt written in markdown bullets invites markdown output; prose invites prose.
• For machine-consumed output, use schema-constrained structured outputs or a strict tool, not “respond only in JSON” (see structured-outputs).
• Assistant-message prefill (starting the model’s reply for it) is rejected by current Claude models. Use format instructions, XML answer tags, or structured outputs instead.
• State length in concrete units: “2-3 sentences”, “under 120 words”, “at most 5 bullets”.

4-5. Iterate on failures

Run the full set, read every failure, and tag it:

Failure class	Typical fix
Ignores an instruction	Move it into <instructions>, give the reason, add an example that follows it
Over-applies a rule everywhere	Scope it: “Only when the user asks for code…”
Hallucinated facts	Require quotes from <document> first; allow “I don’t know” explicitly
Wrong format	Switch to structured outputs; add a format example
Too verbose	Concrete length limit + example of the target length
Inconsistent across runs	Remove ambiguity; add decision rules for the fork it wavers on
Refuses benign requests	Add context on who the user is and why the task is legitimate

Stop iterating when the pass rate plateaus across two changes; the remaining failures need a different model, more context (RAG), tools, or a narrower task.

6. Freeze and version

• Store as prompts/<feature>.v<N>.md or a typed constant; reference the version in logs.
• Re-run the eval in CI on any prompt, model, or parameter change.

Porting prompts to newer models

Newer, stronger models follow instructions more literally and need less shouting.

• Remove ALL-CAPS emphasis, “CRITICAL”, and repeated warnings; they now cause over-application.
• Delete workarounds for old weaknesses (forced “think step by step”, elaborate persona hype, “you will be penalized”).
• Ask explicitly for behavior the old model did by default (“go beyond the basics”, “suggest changes but do not make them”).
• Re-run the eval on the new model before and after the cleanup; cleanup is a change too.

Gotchas

• Contradictions between system prompt and examples are the top cause of erratic output. Grep the prompt for each rule and check every example against it.
• Template bugs masquerade as model bugs. Log the fully rendered prompt for failing cases; look for empty variables, None, or double-escaped JSON.
• Timestamps, request IDs, or user names near the top of the prompt break prompt caching. Put variables last.
• “Be concise” with no number means different things on different models.
• Negative examples (“do not write like this: …”) can be copied verbatim. Prefer positive examples.
• A prompt that works for one language or locale is not tested for others; include them in the eval set if users send them.

Verification

1. The eval runs from one command and reports pass rate per criterion.
2. The new version beats the previous version on the full set, not only on the cases you looked at while editing. Hold out 20-30% of cases you never read while tuning.
3. Spot-read 10 passing outputs: graders miss tone and subtle errors.
4. If the score dropped, revert and try a smaller change.

Output contract

When delivering a prompt revision:

**Prompt:** prompts/<feature>.v<N>.md (was v<N-1>)
**Changes:** <one line per change and the failure class it targets>
**Eval:** <n> cases — v<N-1> <a>% -> v<N> <b>% (held-out: <c>%)
**Remaining failures:** <classes + counts, and the proposed next lever>