# The Laws of Skills

A skill is the build's memory of a failure it refuses to repeat. Memory that is not written is repeated; memory written without a failing exhibit is fiction; memory edited without judgment decays into noise. So skills are created only from real failures, edited the moment the owner's words change the rule, judged by fresh-agent behavior and falling failure counts, and bound by provenance — because fluency is not provenance, and one model's confident output must never silently become another model's instruction.

## Decision mandate

- Did a model actually fail at this without the skill, and where is the exhibit?
- Is this a procedure (skill) or a fact (instruction file) — and could a mechanical gate enforce it instead?
- Does an existing skill already cover this concern — edit it rather than create a sibling?
- Who wrote this rule, and what proof binds it — a failing exhibit, or the owner's recorded word?

## existence

S01. **A skill is a procedure, not a fact.** Facts and conventions live in the always-loaded instruction files (CLAUDE.md, AGENTS.md). A skill exists only for a procedure — a repeatable sequence of judgment and action that loads when triggered. When an instruction-file section has grown into a procedure, it moves into a skill; when a skill has shrunk to a fact, it moves back.

S02. **No skill without a failing exhibit.** A skill is created only after a model demonstrably failed or repeated the task without it. The failing exhibit — a ledger event, an owner correction, a wrong output — is named in the skill's provenance. A skill written from imagination teaches what nobody failed at, and is deleted on sight.

S03. **Repetition is the trigger.** The second time the same instructions are pasted, the same fix applied, or the same correction received, the procedure becomes a skill in that same turn. Once is an event; twice is a pattern; a third repetition of a captured pattern is a governance failure.

S04. **A gate beats prose.** If a rule can be enforced mechanically — a regex, a pre-commit check, a schema, a protected-feature test — the enforcement is code, and the skill only documents the judgment the code cannot make. A skill that restates what a validator already blocks is dead weight and is cut.

S05. **One concern per skill.** A skill covers one procedure. When a skill accumulates a second concern, the second concern is extracted. Overlapping skills on the same concern are merged; the merged skill keeps both provenance trails.

## editing

S06. **The correction is written before the reply.** The instant an owner instruction changes, contradicts, or would repeat against a rule in any skill, the skill is edited FIRST, in the same turn, then the requested work is done. A correction not written down is a correction the owner will repeat, which is harm.

S07. **Edit the smallest clause.** A skill edit changes only the clause the failure implicates. Restructuring a working skill to taste is drift, not maintenance. Only the exact criticized thing changes; everything declared or assumed right stays identical.

S08. **Both trees or neither.** Every skill lives in sibling trees (.claude/skills and .agents/skills) so every runtime — Claude, Codex, Grok, Kimi — loads the same law. An edit that lands in one tree and not the other creates two truths; the sync script or the edit itself must reconcile both in the same change.

S09. **Claim before edit.** Skills are shared files edited by concurrent agents. The write law applies: read fresh, claim, edit, release. An unclaimed skill edit that collides destroys another model's captured lesson.

S10. **Never edit a skill to excuse an output.** A skill is edited to prevent the next failure, never to reclassify a past one as correct. Weakening a clause so that a bad output passes is vandalism of the loop and is reverted with the ledger as proof.

## judgment

S11. **Fluency is not provenance.** A model-written rule binds other models only when it carries proof: the failing exhibit it fixes, or the owner's recorded acceptance. Confidence, structure, and volume establish nothing. One model's output never silently becomes another model's instruction.

S12. **Tested against a fresh agent.** A skill edit is judged by behavior, not by reading: a fresh agent runs the trigger scenario without the skill (baseline) and with it. If the baseline does not fail, the skill teaches nothing; if the with-skill run does not pass, the edit missed. The exhibit pair is linked from the skill's provenance.

S13. **The description is the trigger, never the summary.** A skill's description states only WHEN to load it. A description that summarizes the procedure gets executed as the procedure — the body is skipped and the skill silently fails. Trigger conditions in the description; the method in the body.

S14. **Small enough to be read.** A skill body stays within one read: target under 200 words for always-relevant skills, under 500 lines absolutely. Heavy reference splits into files one level deep. A skill nobody finishes reading governs nothing.

S15. **Judged by counts, not intentions.** A skill succeeds when the failure it captures stops recurring — governor counts, ledger error classes, owner-restatement counts drop and stay down. A skill whose failure class recurs is re-opened, not defended.

## provenance

S16. **Every edit names its actor and exhibit.** A skill edit records who edited (model + session), why (the exhibit: ledger event, owner order, failed run), and what changed (the clause delta). The ledger holds the receipt; the skill holds the pointer. An edit without provenance is reverted on discovery.

S17. **The owner's word outranks the archive.** When a skill and a live owner instruction conflict, the instruction wins and the skill is amended in the same turn. No skill, lock, or prior rule is ever quoted back to the owner as a reason not to act.

S18. **Imported skills keep their source.** A skill fetched from outside (a public repo, another build) is installed verbatim with its license and origin recorded. Local amendments append; they do not silently rewrite the imported text into something the source never said.

## representation

S19. **A skill is an article-object.** Every site-governing skill is one identity with typed representations: human page (/a/slug), machine object (/api/articles/slug), model skill (/api/articles/slug/skill), local SKILL.md in both trees, and a downloadable folder. The canonical source is the object module; every representation derives from it; none is hand-maintained twice.

S20. **One link, one identity, one folder.** Any object a link names is downloadable as one folder holding all its representations — article.md, article.html, article.json, skill/, manifest.json with hash lineage, graph and sources where they exist. Folders compose upward: page folder, collection folder of page folders, root folder of the site.

S21. **Machine URLs are never human links.** Raw JSON and machine endpoints are shown to humans as copyable text, never as clickable navigation on homepages, menus, or footers. Humans get the human page; models get the machine route; neither is accidentally handed the other's representation.

## Representations

- **article:** /a/skill-law — explain meaning (human reader)
- **markdown:** /api/articles/skill-law?format=markdown — portable explanation (human or model reader)
- **json:** /api/articles/skill-law — transport the complete typed object (software)
- **directory:** /api/directory/SKILL_LAW — discover identity and contract (router or operator)
- **skill:** /api/articles/skill-law/skill — teach behavior (LLM)
- **oip_contract:** /api/dispatch?key=SKILL_LAW — discover authority and invocation (agent or protocol client)
- **invoke:** /api/dispatch?invoke=SKILL_LAW — execute behavior and return proof (authorized agent or protocol client)
- **graph:** /api/articles/skill-law/voxels — traverse relationships (graph client)
- **versions:** /api/articles/skill-law/versions — inspect amendment lineage (auditor)
- **conformance:** /api/articles/skill-law/conformance — falsify claims and prescribe repair (test runner or critic)