prompt-engineering

name

Prompt Engineering

description

Improve prompts, system prompts, and agent instructions systematically - with test cases, failure diagnosis, and one-change-at-a-time iteration instead of vibe edits. Activate for "improve this prompt", "the model keeps doing X wrong", "write a system prompt", "make the agent stop doing Y", prompt templates, and instruction files for AI tools. Trigger signal: any prompt edit about to happen without a concrete example of the failing (or desired) behavior in hand.

Prompt Engineering

Purpose

A prompt is a program whose runtime is a model: it has specifiable behavior, test cases, regressions, and bugs. Most prompt "improvement" is vibe-editing — adding emphasis and adjectives without a single concrete failing example in hand, then declaring the result better without running it. This skill imposes the engineering loop: specify behavior → diagnose the actual failure → make one precise change → test against cases → keep versions.

When to use this skill

• Improving an existing prompt, especially "the model keeps doing X" complaints.
• Writing new system prompts, agent instructions, or reusable templates where behavior matters and the prompt will run many times.
• Reviewing a prompt that has accreted patches ("ALWAYS do A. NEVER do B. IMPORTANT: remember A...").

When NOT to use this skill

• One-off conversational asks — just ask well; the loop's overhead needs reuse to pay off.
• When the problem is the task, not the prompt: if the model lacks the information or capability, no wording fixes it — restructure the task (provide the context, split the steps, add tools) instead of engineering the incantation.

Operating procedure

1 — Specify behavior with test cases first. Before touching the prompt, write 3–5 concrete cases: input → desired output (or desired property of output). Include: the reported failing case, a normal case that currently works (your regression guard), and one edge case (empty/hostile/ambiguous input). No test cases = no way to know the edit helped.

2 — Diagnose from actual failures, not descriptions of them. Get the real failing outputs (live-state-truth: run the prompt if you can). Classify the failure:

Failure class	Signature	Fix direction
Ambiguity	Model does a reasonable other thing	Define the term; add the disambiguating example
Missing context	Model invents what it wasn't given	Provide the facts/data in the prompt, don't demand the model "be accurate"
Conflicting instructions	Behavior flips between runs; late instructions ignored	Find and resolve the conflict — don't add a third instruction to arbitrate two
Underspecified format	Content right, shape wrong/inconsistent	Show the format: a literal example output beats three sentences describing it
Buried instruction	Long prompt; the violated rule is in the middle	Restructure: critical constraints near the top, grouped, deduplicated
Capability gap	Fails all wordings of the same demand	Restructure the task (steps, tools, context) — see "When NOT"

3 — Edit with precision, not emphasis. The core discipline:

• Specific beats emphatic. "IMPORTANT!! be concise" loses to "answer in ≤3 sentences unless asked to elaborate." Reaching for caps, bold, or "CRITICAL" is the signal to restructure instead — emphasis is what you add when the instruction itself is vague.
• Show, don't only tell: one worked example for anything format-critical or judgment-critical. Examples are the highest-leverage tokens in most prompts.
• Positive over negative where possible: "cite a source for each claim" beats "don't make things up" — prohibitions leave the target behavior undefined.
• Every sentence earns its place: instructions the model already follows by default are noise that dilutes the ones it doesn't.
• State priority for genuine conflicts: if brevity and completeness will collide, say which wins, or the model decides per-run.

4 — One change at a time when debugging behavior (change-control for prompts): batch edits that "fix" the failure leave you not knowing which change did it — or which one broke the other case.

5 — Test against the cases from step 1 — the failing case (fixed?), the working case (still works?), the edge case. For high-volume prompts, multiple runs: single-run success on a stochastic system is anecdote, not verification.

6 — Version and annotate. Keep the prior version; note what each change fixed ("v3: added output example — fixed inconsistent JSON keys"). Prompt history without annotations becomes archaeology.

Quality bar

• Test cases existed before the edit; the edit is judged by them, not by whether it reads better.
• The diagnosis names a failure class from actual outputs, not a guess from the complaint.
• The revised prompt contains no emphasis-inflation (stacked caps/IMPORTANT/ALWAYS) standing in for specificity.
• Regression checked: the previously-working case still works.

Common failure modes

• Vibe-editing: rewriting for elegance with zero failing examples in hand; "improved" is asserted, never measured.
• Emphasis inflation: each failure adds another "VERY IMPORTANT" — the prompt becomes a shouting match with itself, and every instruction dilutes every other.
• Instruction pileup: patches accreting until they conflict; nobody deletes. Prompts need pruning passes like code needs refactoring.
• Overfitting to the complaint: fixing the one reported case with a hyper-specific rule that degrades general behavior — the regression case in step 1 catches this.
• Persona padding: "You are a world-class expert with 20 years..." as the entire improvement. Framing has its uses; it doesn't substitute for specified behavior.
• Testing in your head: predicting the model's response to the new prompt instead of running it. Predictions about stochastic systems are exactly the guesses live-state-truth bans.

Example

Complaint: "The summary prompt keeps producing bullet lists; we need prose paragraphs." Test cases: the failing doc; a short doc that already summarizes fine; an edge (doc that is itself a bullet list). Actual output collected: bullets appear when the source has bullets — diagnosis: underspecified format + ambient mimicry, not disobedience. One change: add a two-sentence literal example of the desired prose output and the line "write flowing prose paragraphs even when the source uses bullets." Test: failing case → prose ✓; regression case → still good ✓; bullet-list source → prose ✓. Versioned: "v2: literal prose example — fixed format mimicry."

Works with sibling skills

• change-control (one change, versions kept) and live-state-truth (run it, don't predict it) are load-bearing throughout.
• ruthless-editor polishes instruction wording — but here precision-per-word outranks brevity-per-word; cut only what tests confirm was inert.
• adversarial-verify stress-tests the finished prompt: "what input still breaks this?"
• intent-clarity decodes what behavior the prompt's owner actually wants — often different from the literal complaint.

Provenance and maintenance

Added 2026-07 in the expansion pass: prompt improvement is a recurring, high-value task the routing guide previously served with a composite of general skills; the test-case loop and failure taxonomy are specific enough to earn a dedicated owner. Practices are standard prompt-engineering craft, not claims about any particular model's internals. Re-verify by auditing recent prompt edits: if any shipped without a before/after test run, step 5 isn't enforced.