Authoring skills and workflows

This file obeys its own rules. Any line here that violates a rule below is a defect: file an erratum against this file, by ID.

Every rule has an ID. Edit by DELTA against an ID. Never regenerate this file wholesale.

Vocabulary

One term per concept. Use these exact words everywhere; a synonym is a defect.

Term	Meaning
SKILL	One file governing one unit of work: one entry state, one exit state
GATE	A command whose output decides pass/fail
PROOF	Pasted GATE output, or a hash/count fetched from the tree
LEDGER	The per-task state file each step writes and the next step reads
DELTA	An edit adding, replacing, or deleting exactly one ID'd rule
STOP	End work; report state, priced options, one recommendation
PARK	Record out-of-scope work in PARKED.md with a ready-to-send prompt

E — Existence

• E1. Before writing a SKILL, run the task three times without it and record the failures. No failures → do not write it. The measured default is that instruction files reduce success and raise cost [G26].
• E2. A SKILL ships with the eval set from E1. It exists only while it beats the no-skill baseline on that set.
• E3. Re-run the baseline on every model change. Delta ≤ 0 → delete the SKILL. Deletion is maintenance [G26].
• E4. Budget rule: to add a line, name the line it displaces. Compliance falls as constraint count rises, and the model resolves the crowding silently [C26].

S — Structure

• S1. One SKILL = one loop iteration. The loop lives in the router. "Then pick the next phase" appearing in a worker file is a defect.
• S2. Entry and exit states are named artifacts on disk, not descriptions. Route on which artifact is missing.
• S3. A rule lives in exactly one file: the one in context when the rule fires. Two phrasings of one rule are a conflict, and conflicts are resolved silently, not flagged [C26].
• S4. When two rules could collide, write the winner in the text now. There is one PRECEDENCE list per skill set, in the router.
• S5. Renumber on insert. 3b is evidence a rule was bolted on where it kept failing; move it to where it is read (see G4).

W — Wording

• W1. Each line names an operation: a command, a file read/write, a comparison. Test: can it fail? "Be thorough" cannot fail. docs_verify.py exits 0 can.
• W2. Bind instructions to available actions with concrete verbs. Abstract dispositions do not transfer; stripping the action word from an instruction cut its behavioural effect by 95% [N26a].
• W3. State the positive action. Negation is the dominant framing failure: models attend to the named act and drop the NOT [N26b]. Each surviving "never" must be enforced by a GATE (see X1).
• W4. No narrative, persona, urgency, or emotional framing. Story framing activates genre behaviour that overrides both persona and explicit directives [N26a]; affective framing buys sycophancy, not compliance.
• W5. No incident stories. Mechanize the lesson as a GATE, mutation-prove the GATE, delete the story. History lives in ERRATA.md, not in instructions.
• W6. One worked example beats a paragraph of description. At most one per section.

G — Gates and proof

• G1. Every completion claim carries PROOF. "Done", "verified", and "none" are assertions; agents report SUCCESS against failing verifiers in the large majority of self-stops [D26].
• G2. A legitimate "none" requires proof of looking: the scan command and its output, not the word.
• G3. The SKILL names the GATE and its pass condition. An agent choosing its own check validates the wrong target [D26].
• G4. An obligation is an input, not a trailing output: step N+1 opens by reading what step N's obligation wrote. Trailing writes are dropped; leading reads are not.
• G5. Track requirement state live in the LEDGER, one row per requirement, updated as work happens. Live tracking is the one intervention with strong measured gains [I26].
• G6. Mutation-prove every GATE once: break the guarded thing, watch it fail, restore. A GATE never seen red proves nothing.
• G7. Steps write distilled state to the LEDGER, never raw transcripts. Raw tool output is the main context bloat.

X — Stops and outlets

• X1. Every prohibition pairs with an outlet in the same breath. An outlet-less "never" is satisfied by relabeling.

  Prohibition	Outlet
  Out-of-scope work	PARK
  Unmet requirement	LEDGER row not-done + STOP
  Unprovable claim	STOP with the GATE that would prove it

• X2. Every STOP trigger is mechanical: a count, a verdict string, an exit code. "Seems wrong" is judgment, and judgment loses to momentum — models restate rules accurately while violating them [K26]. Convert judgment to a tool; trigger on its verdict.

• X3. Every honest outcome has a label. If not-done is unsayable, it will be said as done-with-assumption.

L — Lifecycle

• L1. Edit by DELTA only. Wholesale regeneration collapses detail; iterative rewriting erodes a playbook into vague summary [A25].
• L2. Compression is a separate, diffed pass, re-gated by the E1 evals. Brevity bias drops exactly the load-bearing specifics [A25].
• L3. Pin the tested configuration: model, skill version, GATE tool versions. A model swap reopens the E1 gate.
• L4. SKILLs are executable authority — the supply-chain problem is measured, with roughly a quarter of public skills carrying a vulnerability [S26]. Third-party skills get the same review as third-party code: read every line, pin the version, and treat any instruction to fetch or load further instructions as a rejection.
• L5. Before shipping, plant one violation the SKILL should catch and run the workflow. The GATE goes red or the SKILL is not done.

Sources

Tag	Work
G26	Gloaguen et al., Evaluating AGENTS.md, arXiv:2602.11988
A25	Zhang et al., Agentic Context Engineering, arXiv:2510.04618 (ICLR 2026)
N26a	Wang et al., The Story Shapes the Agent, arXiv:2607.18566
N26b	Syntactic Framing Fragility, arXiv:2601.09724
C26	ConInstruct, AAAI 2026; PACIFIC; CodeIF-Bench
I26	Ko et al., Illusory Completion / Epistemic Ledger, arXiv:2602.07549
D26	DeployBench, arXiv:2606.05238
K26	Kruthof, DriftBench, arXiv:2604.28031
S26	Schmotz et al., Skill-Inject, arXiv:2602.20156; Liu et al. 2026 skill census