Canonical Knowledge-Action Object · 1.0.0
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.
The test for every skill
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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
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.
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.
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
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.
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.
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.
The loop
Every governing article on this site is also a model Skill: the Design Law and Writing Law already work this way. This law governs the loop itself — when a lesson becomes a skill, which model may change it, and what proof a change needs before it binds the next model that loads it.
One identity, many expressions
The article explains to a human. The Skill instructs a model. The folder ships every representation with one manifest and one hash lineage. Each expression uses the language its audience needs while preserving identity, meaning, version, relationships, and proof.
One identity. Many typed expressions. Each optimized for its audience and role.