/prompt-engineering

name: prompt-engineering
description: 'Create, update, review, or discuss an LLM prompt — a system prompt, a skill, or an agent. Use when writing or improving a prompt, discussing a skill or agent, diagnosing prompt failures, or when the user says a prompt needs work.'
argument-hint: '<request>'
user-invocable: true

A prompt states a goal and gets out of the way. Everything else in it is load — spent on every run, taken from the attention the model would otherwise put on the work — so each line has to buy more than it costs. What follows decides four things: what the run is given, whether a line exists, where it sits, and how it is worded.

What the run has in front of it

A run's result is bounded by what it has in front of it: the prompt and everything fed into it — the inputs filled into a template, the files it reads, retrieved material, tool output, the conversation so far, what a handed-off agent receives. The model is usually capable enough, so bad output usually traces to that input. When a run underperforms, read what it actually had — the trace or the filled-in input, not the template alone — before you change any wording, and look for four faults:

• **Missing** — a piece the task needs is not there, so the run guesses.
• **Conflicting** — two pieces disagree, so the run picks one.
• **Wrong or stale** — a piece is untrue or out of date, so the run repeats it.
• **Noise** — what matters is there, buried under material that does not bear on the task.

Fix the input first: supply the piece or a pointer that reaches it, choose one source where two disagree, correct or drop what is wrong, cut what buries the signal. That usually moves the result more than any other change. Wording edits and after-the-fact corrections — a review pass, a self-check, a rule added after a failure — come after it. A correction that makes up for faulty input leaves the fault in place, and the next run meets it again.

Complete means complete for the task: the fix usually trades noise for the missing piece rather than adding volume. Look to the instructions when the input is already complete, consistent and clean; when the model lacks a capability no input can supply, change the architecture instead.

Where a line came from

Ask this before asking whether the line helps. A line can be true, relevant, and still worth cutting, so usefulness does not settle it. Provenance does, and you can answer it from memory:

• **The user ruled it** — a decision, preference, or constraint they stated. Nothing derives it. Keep.
• **The world holds it, out of the run's reach** — an unwritten convention, a failure you observed, a fact outside what the run will read. Keep, and prefer a pointer to the source over a copy that can go stale.
• **It counteracts a default you have watched the model take** — keep, when the default is observed rather than feared.
• **You worked it out from material the run will also read** — cut. A conclusion available in the corpus is one the run reaches itself, so writing it down buys nothing and spends load on every invocation.

That last class is the one that feels most earned, because you did the work to reach it, and it is where over-specification comes from. Two tells: a line you could justify from the same sources the run gets, and a sentence that merely argues for the instruction above it without adding information admitted by the tests above.

**A choice the request left open belongs to whoever made the request.** Some of what you would add is not padding but a decision — what ranks one candidate over another, an exception to a rule they gave you, a deliverable beyond what they asked for. It reads as thoroughness and it commits them to something they never chose, under their name, in a file they will quote back later. Ask where the answer would change the work; leave it out where it would not.

**A finished prompt looks thinner than you expect it to, and that is the result rather than a warning sign.** Two rulings and a goal make a short document; the pull at that point is to fill it out — a section on how to rank, a definition of the term in its own name, a third source of evidence nobody asked for — and everything reached for that way comes from the class above. When it reads as too slight, check the goal is stated and the rulings are in it, then ship it.

The counterfactual question — *would the model do this without the line?* — asks for a prediction about the model's own behaviour, which is not reliably answerable from the inside. Ask it second, of what provenance already admitted: it can still cut a line provenance allowed, never keep one provenance rejected.

When two people disagree about whether a line is doing work, the argument is about the model's default, so settle it by running the document with the line removed and comparing. That is a tiebreak available when it is worth the trouble, not a step every line has to pass.

Author upward

Start from the goal sentence. Add only what the questions above admit, one line at a time.

Writing broadly and pruning afterwards costs more and lands longer: every line you would cut is one you already argued for, and the draft's own weight reads as evidence that it was needed.

Two budgets

Everything you add spends one of two things:

• **Context load** — always-loaded material, paid every turn whether or not it fires. A skill's description, a rule in an `AGENTS.md`, anything resident.
• **Cognitive load** — what a person has to hold: which documents exist, and when to reach for each. Not a cost to drive to zero — it is what buys human judgement. Spend it where judgement matters.

Material behind a pointer escapes context load for the price of the pointer's own line. Material with no pointer rides entirely on a person remembering it.

Where a line sits

Three rungs, ordered by how immediately the run needs the material: **steps** it performs in order, **reference** it consults on demand, and **disclosed reference** i