Authoring SKILL.md: direct instruction, equipped for reliability

Status: open/draft

Summary

A SKILL.md is the instruction an agent executes, not documentation about the skill — and its reliability comes from how it is phrased and how it is built. Phrase each line as direct, positive instruction with surgical rationale; equip the skill with a triggering description, freedom matched to fragility, decomposed steps with a verification step, progressive disclosure, tested formatting, examples where output matters, and an eval. Every rule carries the evidence tier it rests on.

Scope

Every rule below applies to any SKILL.md. Two groups behave differently once sequencing moves out of prose and into a process registration (D-VSLI-distributed-work-runner-architecture):

Rules	After the engine cutover
1-4, 8-11 — phrasing, `description`, progressive disclosure, formatting and placement, examples, eval	Fully live. They govern any SKILL.md, a generated head included.
5-7 — freedom matched to fragility, step decomposition, verification steps	Inert for a generated head. They are authoring rules for sequencing prose, and a generated head sequences nothing.

This is a narrowing, not a retirement. After cutover, procedure truth lives in the process registration and the compiled DAG the engine executes — not in prose — so rules 5-7 have nothing left to constrain in a head that only narrates. They stay authoritative for every hand-authored SKILL.md that still sequences work, and their substance carries over to registration authoring: freedom-to-fragility becomes the choice of step variant, decomposition becomes step definitions, and the verification step becomes a declared gate.

Rule

A SKILL.md is the instruction an agent executes — not documentation about the skill. Both how each line is phrased and how the skill is built and equipped decide whether the agent executes it reliably. Each rule below carries its evidence tier (see the legend at the end of this section).

Phrasing each instruction

State behavior directly. Say what the skill does in positive, imperative form; don’t define it by contrast with another (“the sibling of X; where X does Y, this does not”). Positive framing beats negation: LLMs handle negation poorly, and the failure gets worse with scale — inverse scaling, so a “do NOT” is least reliable on the strongest models [A: Jang 2022; McKenzie 2023]. Pair any prohibition you must keep with the positive alternative.
Write no negative instruction the structure already enforces. If a constraint is guaranteed by allowed-tools (e.g. no AskUserQuestion → cannot prompt) or by the absence of a step (no stamp step → cannot stamp), don’t restate it as “NEVER…” / “does NOT…”. Enforce by structure or a deterministic script; prose negatives can be violated, structure cannot P-0001-prefer-deterministic-over-llm. Carve-out: a hard safety or irreversible-action boundary (e.g. “never force-push”, “do not run destructive migrations unprompted”) MAY still be stated as an explicit negative even when partly structural — redundancy is cheap insurance against an unrecoverable outcome.
Keep rationale surgical. A one-clause why is warranted only for a non-obvious rule the agent must generalize from — the reasoning becomes the rubric it applies to cases the steps didn’t anticipate [A: Lampinen 2022, large models]. Omit it for fragile literal steps (a bare imperative is correct there — extra “why” only invites the agent to second-guess a step it should follow verbatim) and for anything the model already knows. Design rationale — “why this mechanism and not that one” — belongs in a Decision record or the PR description, never in the steps.

Building and equipping the skill

Write the description to trigger. Third person; pack BOTH what the skill does AND when to invoke it (the key terms, file types, and contexts that should fire it). It is the single most important field for skill selection; make it slightly pushy if it under-triggers. Stay within ~1024 chars (1536 combined with name in Claude Code) [B].
Match degrees of freedom to fragility. Fragile or irreversible work — a “narrow bridge with cliffs” (migrations, releases, anything unrecoverable) — gets low freedom: an exact script or step list marked “do not modify.” Open, judgment-heavy work (code review, drafting) gets high freedom: general direction. Medium gets a parameterized script or pseudocode. Fragility sets the freedom — P-0001-prefer-deterministic-over-llm applied per-instruction — independent of how mature the workflow is on that principle’s maturation ladder [B].
Decompose; respect the curse of instructions. Joint compliance decays roughly as the per-instruction rate raised to the instruction count — most models drop below 50% past 3-4 hard constraints in one step [A: ManyIFEval 2509.21051; WildIFEval]. Keep few hard constraints per step, number sequential steps, and split any step carrying more than ~3-4.
Add an explicit verification step. A skill that produces something checks it — a numbered “verify / checklist” step (run the validator, confirm the marker, diff the output) rather than trusting the work landed [A: ManyIFEval self-check].
Disclose progressively. Keep SKILL.md lean; push detail into referenced files and scripts loaded on demand, and bundle deterministic, repeated, testable work as output-only scripts so code never enters context [A+B: Chroma “Context Rot” 2025; Anthropic context-engineering]. Don’t duplicate prose across skills — factor to one canonical doc and reference it (see solutions/ontological/skills/CLAUDE.md, P-0005-schema-over-prose).
Format consistently and place by salience. Use one tested structure — headers and numbered lists generally, XML/<example> tags for Claude where you use tags; format choice alone swings accuracy by large margins, so never trust one un-tested format [A: Sclar 2024]. Front-load the critical instructions and repeat them at the end of a long body; put long reference material ABOVE the task — ends beat the middle [A: Liu 2023 lost-in-the-middle]. Markdown shape (ATX headings, - bullets, fences, wrap) follows S-0007-markdown-formatting; this rule adds only the salience and consistency intent on top.
Show, don’t tell, where it matters. Add few-shot examples when the output schema matters, inputs are messy, or you’ve seen repeated failures; wrap each in <example> tags and include edge/error/empty cases. Order effects are real — don’t rely on a single example [A+B].
Eval like code. Build a small representative eval set; test across Haiku / Sonnet / Opus and 2-3 paraphrases to catch format/phrasing brittleness; turn repeated failures into few-shot examples; version skills as artifacts and pin model versions in production [A+B].

Tone and politeness have no reliable, generalizable performance effect — write clearly and neutrally; don’t spend effort optimizing register [mixed].

Evidence tiers (used throughout): [A] peer-reviewed or benchmarked result; [B] vendor-tested guidance (real, but not an independent [A] result — don’t relabel it); [A+B] an [A] result plus convergent vendor practice; [mixed]/[contested] a finding the literature disputes (reconciled in context, not settled).

Why

A SKILL.md loads into the agent’s context every time the skill runs; every line competes for attention and tokens, and context degrades at every length increment, not just near the limit [A+B: Chroma “Context Rot” 2025; Anthropic context-engineering]. Skills are the project’s highest-leverage, least-rigorous artifact (per D-TQHZ-skill), and their failure modes are now measured rather than folkloric. Phrasing and structure each have an evidence base:

Positive framing (1). Negation is a measured LLM weakness with inverse scaling — larger models do worse on negated prompts, several near chance [A: Jang 2022; Truong 2023; McKenzie 2023 Inverse-Scaling/NeQA]. A “do NOT” is the least reliable form precisely on the models we run.
Structure over prose (2). A constraint enforced by structure (a missing tool, a deterministic check) holds; a prose “do not” only hopes P-0001-prefer-deterministic-over-llm. The safety carve-out trades a little dilution for insurance against an unrecoverable action.
Rationale as rubric (3). In-context explanations help an agent generalize to unanticipated cases [A: Lampinen 2022, large models] — that’s the one thing a why-clause buys. The counter-pressure is real: more reasoning can hurt literal instruction-following [contested: 2505.14810], and conciseness guidance says don’t explain what the model already knows. The reconciliation is surgical placement: a why-clause where generalization is needed, a bare imperative where literal compliance is.
Structure and equipping (4-11). Agents miss instructions buried in a dense step (curse of instructions [A]), miss them in the middle of a long body (lost-in-the-middle [A]), and swing wildly on formatting the author never tested (format brittleness [A]). A skill is selected only if its description triggers [B], and degrades as its context grows whether or not it nears the limit (context rot [A+B]). Matching freedom to fragility is the same insight as P-0001-prefer-deterministic-over-llm applied per-instruction: where the cost of a wrong move is high, narrow the agent’s latitude.

Encoding these as house rules turns a class of silent, intermittent skill failures into things a reviewer can catch before merge.

How to apply

Authoring a skill. Draft the description first (rule 4). Classify each unit of work by fragility (rule 5). Write steps as a numbered sequence, each an imperative the agent performs (“Read the task file”, “Stamp the marker”, “Commit”), with ≤3-4 hard constraints, splitting dense ones (rule 6); end any output-producing flow with a verification step (rule 7). Keep the body lean — reference detail and bundle deterministic tails as scripts (rule 8).
Phrasing each line. Enforce structurally first: omit a tool from allowed-tools rather than writing “never call it”; let a script verify what must pass rather than instructing the agent to check by hand. Add a negative only when a concrete past failure shows it’s needed (cite the incident) or it guards a hard-safety/irreversible boundary (the carve-out); default to omission and pair any kept prohibition with the positive alternative. Keep a why-clause only where the agent must generalize the rule to cases the steps don’t enumerate; for a fragile literal step, write the bare imperative and stop. Relocate design rationale to a Decision/ADR or the PR body.
Reviewing a skill. For every line ask: “is this something the agent does, or a why-clause that helps it generalize?” If it only explains or justifies a mechanism, it’s documentation — cut or move it. Then check the structure: does the description say when to fire? Does any single step pile up more than ~4 hard constraints? Are critical instructions front-loaded (and repeated at the end if the body is long)? Is reference material above the task? Is there a verification step? Are messy-output skills carrying <example> blocks with edge cases?

Anti-examples

From the task-auto-define review (PR #231) — phrasing:

“This skill is the sibling of /sdlc:task-define. Where task-define asks…, this NEVER asks.” — Contrastive framing plus a negative for what allowed-tools already guarantees. Direct form: “Fill a task’s readiness gaps by synthesizing content from its prose and the codebase, then commit.”
“Note the task’s autonomy: value but do NOT gate on it.” — The skill doesn’t gate, so it needn’t mention autonomy at all.
“Rationale for this mechanism (and why NOT a frontmatter field): the schema is additionalProperties: false…” — Still excluded. This is design rationale (why this mechanism vs. an alternative the author considered), not generalization rationale: the agent never has to extrapolate “is additionalProperties: false?” to a new case, so the why-clause buys nothing here and belongs in the Decision/PR. Contrast a kept why-clause — e.g. “namespace the marker with the skill slug so a parent reading sub-agent output can’t mistake it for its own terminal verdict” — where the agent must apply the reason to any new marker it invents. Rule 3 admits the second shape and still rejects the first.

Structure and equipping:

Vague description. “Helps with tasks.” — states no trigger; the agent never selects it. Fix: third-person what + when, with the firing terms and contexts (rule 4).
High freedom on fragile work. “Update the database however makes sense.” — an irreversible action handed an open field. Fix: exact, do-not-modify script (rule 5).
One overloaded step. A single step that says clone, branch, edit five files, run three checks, push, and open a PR — six-plus hard constraints, so joint compliance collapses [A]. Fix: split into numbered steps, add a verification step (rules 6-7).
Buried critical instruction. The one “never push to main” line in the middle of a 200-line body. Fix: front-load it and repeat at the end (rule 9).
Tell-not-show on messy output. Prose-describing a strict output schema for noisy input instead of giving examples. Fix: <example> blocks with edge/error cases (rule 10).
Untested format / no eval. Shipping a skill validated on one prompt, one format, one model. Fix: representative eval set across Haiku/Sonnet/Opus and a few paraphrases (rule 11).

Notes

Drafted from review feedback on PR #231 (2026-06-02). The 2026-06 revision moved each rule from assertion to an evidence base (negation inverse-scaling, context-rot, rationale-as-rubric, curse-of-instructions, lost-in-the-middle, format brittleness) and folded the structural/equipping practices into this one standard. This standard is its own exemplar: it practices the discipline it states — direct, decomposed, positively framed, surgical rationale.
Status held at open/draft: the evidence strengthens the rules, but the original promotion bar — confirmation against more than one skill — is unchanged, so the status decision is deferred to that review.
Evidence tiers are load-bearing: [B] items (the description rules, degrees of freedom, progressive disclosure) are vendor-tested guidance, not proven [A] results — don’t relabel them. The one [contested] finding (more reasoning can hurt literal instruction-following) is reconciled in rule 3, not resolved.
This standard informs D-TQHZ-skill (the proposed required-SKILL.md-shape decision, still open/proposed): the description-field and degrees-of-freedom guidance here supersede the parts of that sketch they overlap. The decision’s required-sections and post-execution-assessment proposal remain open and are not settled here.
See the Hemingway authoring guidance in docs/CLAUDE.md. The mechanical enforcement has shipped: sdlc gate skill-prose runs a per-skill markdown-contract overlay — each covered skill’s rules live in SKILL_PROSE_REGISTRY in solutions/ontological/lib/services/gate/ops/_skill_prose_contract.ts — that pins each SKILL.md’s required sections, required phrases, and forbidden markers. It does not judge rule-2 redundant negatives or the rule-6 constraint cap by meaning, so flagging a “do NOT” / “NEVER” the structure already enforces stays human judgment.
The gate retires at the engine cutover. sdlc gate skill-prose exists to lint the English of a prose orchestrator — required sections, phrases, and markers standing in for a procedure contract. Once a process registration carries the steps, the registration validates the generated head instead, and the lint has nothing to guard (D-VSLI-distributed-work-runner-architecture, Consequences). The Scope block above is what survives: the phrasing and equipping rules stay live and hand-checked; the sequencing rules go inert with the gate.

← Back to Standards