Authoring effective instructions

This documentation was generated with the assistance of AI. Please report any inaccuracies.

CLAUDE.md, a SKILL.md, an agent definition, and a plugin’s bundled instructions are all, mechanically, the same thing: text an AI agent reads and is expected to act on faithfully. The quality of the results they produce is mostly a function of two things — how the instructions are phrased, and how much of the context window they (and everything they cause to happen) consume. This page is the shared guidance the other authoring guides (The CLAUDE.md file, Creating and updating skills and agents, Plugins) point back to, rather than repeating it four times. Together, a well-written CLAUDE.md plus a well-scoped set of skills and agents is what turns "an AI assistant" into a harness — a system that produces the same good behavior every time, instead of depending on how well any one session happens to be prompted.

This guidance applies to all four of CLAUDE.md, a SKILL.md, an agent’s system prompt, and a plugin’s bundled instructions — and just as much to a single, ad hoc prompt you type into a session yourself. A skill is really just a prompt saved for reuse across many runs; the same discipline that makes a saved prompt reliable the tenth time also makes a one-off prompt more likely to get the right answer the first time. Nothing below is specific to writing files — read "instruction" throughout as "anything you give Claude to act on," whichever of the five forms it takes.

Naming a skill or agent within a prompt

A one-off prompt can be just as explicit about which skill or agent should handle it as a SKILL.md step is about its own sub-steps — and doing so is itself an application of "direct, not vague" rather than a separate rule:

  • To invoke a specific skill, either type its slash command directly (/iru-plan 42) or name it in prose ("run the iru-plan skill for issue 42"). Either is unambiguous about which skill you mean. A purely descriptive request instead ("write me a plan for issue 42") leaves Claude to match your wording against every skill’s description on its own — usually fine, but a second source of run-to-run variation you remove by naming the skill yourself.

  • To involve a specific agent, name it and ask for the delegation explicitly ("use the Explore agent to find every caller of `X`", "spawn a sub-agent to run the full test suite") rather than leaving Claude to decide whether and how to isolate the sub-task. There is no slash-command equivalent for an agent, so naming it in the prompt is the only precise, repeatable way to request one.

See How each one is actually invoked for the full mechanics behind both of these — the frontmatter fields that change what’s even possible for a given skill (disable-model-invocation, user-invocable), and the other channels an agent can be reached through (@-mention, a session-wide default).

This matters most for a prompt meant to run the same way every time — one embedded in another skill’s instructions, or one you expect to reuse — where naming the skill or agent removes one more source of drift, the same motivation behind every other piece of guidance on this page.

Write direct, concise, step-structured instructions

An agent following a SKILL.md executes it closer to a runbook than to a suggestion — ambiguity that a human would resolve by intuition, the agent will resolve inconsistently across runs. This catalog’s existing skills (e.g. .claude/skills/iru-plan/SKILL.md, documented at Plan) follow a consistent shape worth reusing elsewhere:

  • Numbered steps, one decision per step. ## Step 1 — Locate the Antora documentation module, not a wall of prose covering discovery, validation, and generation together. A step an agent can point to by number is also a step you can debug ("it went wrong at Step 3") and a step another skill can invoke precisely (a Step number reference in a dependency section).

  • Imperative, not descriptive. "Find every SKILL.md under `.claude/skills`" reads as an instruction to execute; "This step is about finding skills" reads as a description of intent an agent then has to translate into action itself, and translations vary. Prefer the former.

  • State branches and stopping conditions explicitly. "Not found: ask the user whether to bootstrap one. Found: read it for the component name" is unambiguous about what happens in each case. A step that only describes the happy path leaves the agent to invent behavior for every other case, which is precisely the inconsistency a skill exists to remove.

  • Say what "done" looks like and what to report. A skill without an explicit final "Report" step tends to either report too much (dumping intermediate detail nobody asked for) or too little (silently stopping without confirming what actually happened).

  • Avoid hedged, discretionary language ("consider doing X if it seems appropriate") in the parts of an instruction that are meant to run the same way every time. Reserve genuine judgment calls for an explicit "ask the user" branch (see `iru-plan’s Step 3, Plan) rather than leaving them implicit in vague phrasing.

The same applies to CLAUDE.md (a rule stated as "run mvn test before considering a change done", not "tests should probably be run") and to an agent’s system prompt (a narrow, explicit description of what it’s for and what tools it needs, not an open-ended personality sketch).

Treat the context window as scarce

Everything loaded into a session — CLAUDE.md, the active skill’s instructions, prior tool output, a sub-agent’s full transcript — competes for the same finite context window, and a model’s attention degrades as that window fills with content irrelevant to the current step. Writing good instructions is only half the job; the other half is not loading more of them than the current step actually needs.

Concretely:

  • Keep CLAUDE.md short and current. It loads in every session whether or not that session needs it — see The CLAUDE.md file's "Keep it short" section. An import (@path) organizes a large file for human readers; it does not reduce what actually gets loaded, since imported content is still expanded in full at session start.

  • Isolate noisy sub-tasks in a sub-agent. A full test run, a broad codebase search, or an entire delegated implementation pass produces far more output than its result — spawning it via the Agent tool and asking it to report back only a short summary keeps that noise out of the calling skill’s own context. This catalog’s iru-code skill does exactly this for every quality check it runs per task (see Agents).

  • Collapse repetition in a skill’s own instructions. A step that repeats structurally ("for each task: implement, test, document, quality-check") should be written once as a loop, not unrolled per task — both because it’s shorter and because an agent re-reading the same instruction shape for the fifth time is reading, not thinking.

  • Prefer a reference over an inline copy. An xref: to another page, or an instruction to "read docs/testing-conventions.md before writing tests" pulls in detail only when it’s relevant, rather than inlining that whole document into every skill that might conceivably need it.

  • Ask for a report, not a transcript. When one skill invokes another, or a skill spawns an agent, specify what should come back ("a pass/fail plus the list of new issues", not "everything you saw") — the caller usually needs a conclusion, not the evidence trail that produced it.

  • Prune, don’t just append. A CLAUDE.md or SKILL.md that only ever grows accumulates instructions that stopped being true or stopped mattering; a periodic pass to delete stale content is as valuable as the writing that added it in the first place.

Give examples, not just rules

Claude reasons from a concrete example unusually well — often more reliably than from an abstract rule stated on its own. Where a rule is genuinely hard to state completely and precisely in prose (a report format, a commit-message style, an edge case that’s easier to show than describe), attaching a worked example alongside the rule tends to produce closer, more consistent behavior than the rule by itself, because an example doesn’t leave room for accidental misinterpretation the way a description can.

There are two ways to attach one, and both are legitimate:

  • Inline — paste the example directly into the instruction (the SKILL.md step, the CLAUDE.md rule, or the message itself), when it’s short enough not to be worth splitting out. For instance: "Follow this commit message shape: <type>(<scope>): <summary> — e.g. fix(auth): reject expired refresh tokens before issuing a new one."

  • By reference — point at a file already in the repository, or a URL, and instruct Claude to read it before proceeding, when the example is long, is one of several to pick from, or already exists as a real artifact (a past PR, a well-formed existing skill) rather than something worth retyping. This catalog already relies on this technique: Creating and updating skills and agents's advice to "ground a new skill in an existing example" is exactly this, applied to writing a SKILL.md itself, and several of this catalog’s own bootstrap skills (iru-setup-java-library, iru-setup-java-github-workflows) embed a full example file for the same reason rather than describing its shape in prose.

Which form to use is mostly a context-window tradeoff: inline a short example every time it’s needed; reference a long or only-occasionally-needed one so it loads only when actually relevant — the same reasoning that keeps a CLAUDE.md itself lean rather than inlining everything it might ever need.

This applies at every level this page covers — a one-off prompt ("format the output like this: …​"), a SKILL.md step ("write the summary in this shape: …​"), a CLAUDE.md rule ("commits follow the format shown in `docs/commit-style.md`"), and an agent’s system prompt (a sample of the kind of response it should produce). The worked example later on this page is itself an instance of the same idea: showing what a precise prompt looks like, not just describing the properties it should have.

Examples

The same contrast — vague versus precise, unstructured versus step-based — holds regardless of whether the text ends up in a one-off message, a SKILL.md step, a CLAUDE.md rule, or an agent’s system prompt. The worked example below deliberately picks a task with several interacting rules and no single "obvious" number, since that’s where the gap between a vague prompt and a precise one shows up most.

A complex worked example: calculating a tax liability

The figures and rules below are illustrative only, chosen to show what a precise prompt looks like — they are not current tax guidance. Verify against the actual current-year rules before using anything like this for a real filing.
Example 1. Vague prompt

Help me figure out my taxes for this year. I have some freelance income and stock stuff too.

This asks for a real conclusion but supplies almost nothing an agent could compute from: no tax year, no jurisdiction, no filing status, no actual numbers for the "freelance income" or "stock stuff," and no indication of what "figure out" should produce (a dollar amount? a list of forms? both?). Two runs of this same prompt can reasonably produce two different sets of assumptions and two different answers — which is exactly the inconsistency direct, structured instructions exist to remove.

Example 2. Precise, direct, structured prompt
Calculate my 2025 US federal income tax liability. Facts:
- Filing status: single
- W-2 wages: $95,000 (federal withholding already paid: $14,200)
- Schedule C freelance income: $32,000 gross, $4,500 deductible business expenses
- Schedule D stock sales: $3,000 short-term gain, $12,000 long-term gain
- Traditional IRA contribution: $6,500 (fully deductible; no other above-the-line items)
- No itemizable deductions — use the standard deduction

Steps:
1. Net Schedule C income = $32,000 - $4,500.
2. Self-employment tax = 15.3% of 92.35% of net Schedule C income; half of this amount is an
   above-the-line deduction.
3. Total income = wages + net Schedule C income + short-term gain + long-term gain.
4. AGI = total income - IRA deduction - deductible half of self-employment tax (step 2).
5. QBI deduction = 20% of net Schedule C income (no phase-out applies at this income level).
6. Taxable ordinary income = AGI - QBI deduction - 2025 single standard deduction - long-term gain (taxed
   separately in step 7, not at ordinary rates).
7. Apply the 2025 single ordinary-income brackets to taxable ordinary income (this includes the short-term
   gain, which is taxed at ordinary rates, not the long-term gain).
8. Apply the 2025 preferential long-term capital gains rates to the $12,000 long-term gain, stacked on top
   of ordinary income for bracket purposes.
9. Federal tax owed = step 7 + step 8 + self-employment tax (step 2) - withholding ($14,200).

Report each step's numeric result, then a single closing line: "You owe / are refunded $X." Explicitly flag
any assumption you had to make rather than silently choosing one.

What makes the second version work isn’t length, it’s what each part of it removes:

  • Every fact the calculation needs is given as a number, not a category ("some freelance income" becomes an exact gross figure and an exact expense figure).

  • The two different tax-rate schedules that apply here (ordinary rates for wages/short-term gain, preferential rates for long-term gain) are named explicitly, rather than left for the agent to notice or miss.

  • The one genuinely open question a real preparer would ask (standard vs. itemized) is resolved up front, instead of left as "whichever is better."

  • The output shape is specified ("each step’s numeric result, then one closing line"), so the response is checkable step by step instead of a single unverifiable number.

  • It asks for assumptions to be surfaced instead of silently made — the difference between an answer you can audit and one you have to trust blind.

Do’s and don’ts at a glance

Dimension Don’t — vague, general, or incorrect Do — precise, direct, structured

Facts and scope

"Help me figure out my taxes, I have some freelance income and stock stuff."

"Calculate my 2025 US federal tax liability for: single filer, $95,000 W-2 wages, $32,000 Schedule C income minus $4,500 expenses, $3,000 short-term and $12,000 long-term gains, a $6,500 IRA deduction."

Steps

"Figure out what I owe."

"1. Net Schedule C income…​ 2. Self-employment tax…​ 3. Total income…​ [numbered through to the final figure]."

Resolving ambiguity

"Use whichever deduction is better, I guess — you decide."

"No itemizable deductions — use the standard deduction. State this explicitly in the output."

Correctness of the premise itself

"Assume all my capital gains are taxed at my ordinary marginal rate, that’s how it works, right?" — stated as fact, but wrong: long-term gains have their own preferential brackets, and treating this as true produces a confidently wrong answer no matter how well-structured the rest of the prompt is.

"Apply the 2025 preferential long-term capital gains rates to the $12,000 long-term gain, separately from the ordinary-rate brackets applied to wages and the short-term gain."

Output shape

"Just tell me the number."

"Report each step’s numeric result, then one closing line: 'You owe / are refunded $X.' Flag any assumption made rather than silently choosing one."

Verifiability

Accepting a single final figure with no visible working, so an error partway through is invisible.

Asking for the intermediate result at each step, so a wrong figure can be traced to the exact step that produced it.

A don’t isn’t always merely vague — as the "correctness of the premise" row shows, a confidently wrong instruction produces a confidently wrong result regardless of how well-structured the rest of the prompt is. Precision in phrasing and correctness of the underlying facts are two separate requirements, and a well-structured prompt built on a false premise is still a bad prompt.

Why this matters more than it looks like it should

A harness built from directly-phrased, step-structured instructions that only load what each moment needs behaves the same way on the tenth run as the first. One built from vague, sprawling instructions that dump everything into context every time will look similar in a quick demo but drift, contradict itself, and degrade under real, larger tasks — precisely the problem this catalog’s own premise describes for undocumented, repeat-explained procedures.

See also