# 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.** A skill exists ONLY for a repeatable procedure. Facts and conventions ALWAYS live in the always-loaded instruction files. IF an instruction section grows into a procedure THEN move it into a skill. IF a skill shrinks to a fact THEN move it back. S02. **No skill without a failing exhibit.** A skill is created ONLY IF a model demonstrably failed or repeated the task without it, and its provenance ALWAYS names that exhibit. A skill written from imagination is deleted on sight. S03. **Repetition is the trigger.** IF the same instruction, fix or correction occurs a second time THEN write the procedure into a skill in that turn. A third repetition of a captured pattern is a governance failure. S04. **A gate beats prose.** IF a rule can be enforced mechanically THEN the enforcement is code and the skill documents ONLY the judgment the code cannot make. NEVER restate what a validator already blocks. S05. **One concern per skill.** A skill covers ONLY one procedure. IF a second concern accumulates THEN extract it. IF two skills cover one concern THEN merge them and keep both provenance trails. ## editing S06. **Write the correction before the reply.** IF an owner instruction changes or contradicts a rule in any skill THEN edit the skill first, in the same turn, and ONLY THEN do the work. S07. **Edit the smallest clause.** ALWAYS change only the clause the failure implicates. NEVER restructure a working skill to taste. S08. **Both trees or neither.** Every skill ALWAYS exists in both sibling trees. IF an edit lands in one tree THEN it lands in the other in the same change. S09. **Claim before edit.** ALWAYS read fresh, claim, edit, release. NEVER edit a shared skill unclaimed. S10. **Never edit a skill to excuse an output.** A skill is edited ONLY to prevent the next failure. NEVER to reclassify a past one as correct. Weakening a clause so a bad output passes is reverted with the ledger as proof. ## judgment S11. **Fluency is not provenance.** A model-written rule binds other models ONLY IF it carries the failing exhibit it fixes or the owner's recorded acceptance. Confidence, structure and volume establish nothing. S12. **Test against a fresh agent.** ALWAYS judge a skill edit by behaviour: run the trigger scenario without the skill and with it, and link the pair from its provenance. IF the baseline does not fail THEN the skill teaches nothing. IF the with-skill run does not pass THEN the edit missed. S13. **The description is the trigger.** A description states ONLY when to load the skill. NEVER summarise the procedure in it, or the summary is executed and the body is skipped. S14. **Small enough to be read.** A skill body ALWAYS stays under 500 lines, and under 200 words when always-relevant. Heavy reference ALWAYS splits into files one level deep. S15. **Judged by counts.** A skill succeeds ONLY IF the failure it captures stops recurring in the governor counts, the ledger error classes and the owner-restatement counts. IF the class recurs THEN re-open the skill. ## provenance S16. **Every edit names actor and exhibit.** A skill edit ALWAYS records who edited, the exhibit that forced it, and the clause delta. An edit without provenance is reverted on discovery. S17. **The owner outranks the archive.** IF a skill and a live owner instruction conflict THEN the instruction wins and the skill is amended in the same turn. NEVER quote a skill, lock or prior rule back to the owner as a reason not to act. S18. **Imported skills keep their source.** An imported skill is ALWAYS installed verbatim with its license and origin recorded. Local amendments ALWAYS append and NEVER rewrite the imported text. ## representation S19. **A skill is an article object.** Every site-governing skill is ALWAYS one identity with typed representations, all derived from the object module. NEVER hand-maintain a representation twice. S20. **One link, one identity, one folder.** Any object a link names is ALWAYS downloadable as one folder holding all its representations with a manifest and hash lineage. Folders ALWAYS compose upward. S21. **Machine URLs are never human links.** Raw JSON and machine endpoints are ALWAYS shown to humans as copyable text. NEVER as clickable navigation. ## 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)