{"$schema":"https://miscsubjects.com/api/knowledge-action-schema","object_type":"knowledge-action","identity":{"id":"kao:skill-law","slug":"skill-law","key":"SKILL_LAW","title":"The Laws of Skills","class":"law"},"content":{"summary":"The governance law for the article ⇄ skill loop: when something becomes a skill, when a model may edit one, how edits are judged, and whose words bind — so no failure is fixed twice.","thesis":"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.","clauses":[{"id":"S01","family":"existence","title":"A skill is a procedure, not a fact","law":"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."},{"id":"S02","family":"existence","title":"No skill without a failing exhibit","law":"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."},{"id":"S03","family":"existence","title":"Repetition is the trigger","law":"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."},{"id":"S04","family":"existence","title":"A gate beats prose","law":"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."},{"id":"S05","family":"existence","title":"One concern per skill","law":"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."},{"id":"S06","family":"editing","title":"The correction is written before the reply","law":"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."},{"id":"S07","family":"editing","title":"Edit the smallest clause","law":"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."},{"id":"S08","family":"editing","title":"Both trees or neither","law":"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."},{"id":"S09","family":"editing","title":"Claim before edit","law":"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."},{"id":"S10","family":"editing","title":"Never edit a skill to excuse an output","law":"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."},{"id":"S11","family":"judgment","title":"Fluency is not provenance","law":"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."},{"id":"S12","family":"judgment","title":"Tested against a fresh agent","law":"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."},{"id":"S13","family":"judgment","title":"The description is the trigger, never the summary","law":"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."},{"id":"S14","family":"judgment","title":"Small enough to be read","law":"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."},{"id":"S15","family":"judgment","title":"Judged by counts, not intentions","law":"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."},{"id":"S16","family":"provenance","title":"Every edit names its actor and exhibit","law":"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."},{"id":"S17","family":"provenance","title":"The owner's word outranks the archive","law":"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."},{"id":"S18","family":"provenance","title":"Imported skills keep their source","law":"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."},{"id":"S19","family":"representation","title":"A skill is an article-object","law":"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."},{"id":"S20","family":"representation","title":"One link, one identity, one folder","law":"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."},{"id":"S21","family":"representation","title":"Machine URLs are never human links","law":"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."}]},"instructions":{"trigger":"Use when deciding whether something becomes a skill, before creating or editing any skill in either tree, when judging or reviewing a skill edit, when a failure or owner correction repeats, or when importing an external skill.","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?"],"procedure":["Search both skill trees for the concern before writing anything new.","Capture the failing exhibit: the ledger event, owner correction, or wrong output.","If a mechanical gate can block the failure, build the gate; keep prose for judgment only.","Write or edit the smallest clause that prevents the failure; one concern per skill.","Sync the sibling tree in the same change; claim shared files before editing.","Judge the edit: fresh agent, baseline-fails then with-skill-passes; link both exhibits.","Record actor, exhibit, and delta in the ledger; the skill points at the receipt.","Project the skill to its site object so every model reads the same law from one identity."],"output":["the exhibit","the clause delta","the gate (if mechanical)","the fresh-agent verdict","the ledger receipt","both trees synced"]},"relationships":{"parent":"kao:philosophy","edges":[{"to":"kao:writing-law","label":"The Laws of Writing","rel":"parallels","url":"/a/writing-law"},{"to":"kao:design-law","label":"The Laws of Design","rel":"parallels","url":"/a/design-law"},{"to":"article:oip","label":"Object Invocation Protocol","rel":"governs_capability_use_of","url":"/a/oip"},{"to":"skill:shared-failure-to-skill","label":"Failure → Skill procedure","rel":"operationalized_by","url":"/api/articles/skill-law/skill"}]},"invocation":{"directory_key":"SKILL_LAW","contract":"Apply the Laws of Skills to a proposed or existing skill and return the verdict: exists rightfully / edit / merge / gate instead / delete, with the exhibit and clause cited.","args":{"skill":"name or path or proposal text","task":"create|edit|judge|import|audit"},"effects":"Read-only unless the caller separately authorizes edits."},"authority":{"owner":"Cyrus Massoumi","amendment_policy":"Owner corrections amend clauses in the same turn they are given; model-proposed amendments bind only with a failing exhibit and recorded acceptance. Semantic history is never overwritten.","public_read":true,"mutation":"owner-authorized"},"conformance":{"claims":["one canonical semantic object","all representations derive from it","every skill in both trees has a provenance trail","no failure class captured by a skill recurs unaddressed"],"failure_modes":["skill written from imagination with no failing exhibit","correction acknowledged in chat but never written into the skill","edit landing in one tree only","description that summarizes the procedure instead of stating the trigger","skill weakened to excuse a past output","model-authored rule binding others without proof or acceptance","duplicate skills accreting on one concern","prose restating what a validator already blocks"],"tests":["facet completeness","representation route integrity","sibling-tree synchronization","fresh-agent baseline/with-skill pair per edit","description states trigger only","failure-count regression per captured class"],"repair":"Locate the violated clause, restore or amend it with the exhibit named, re-sync both trees, re-run the fresh-agent pair, and record the receipt. If the concern is mechanical, replace the prose with a gate."},"version":{"current":"1.0.0","amended_at":"2026-07-24T00:00:00-07:00","amendments":[{"version":"1.0.0","change":"Established the Laws of Skills as the governance object for the article ⇄ skill loop, on the owner's order. Codified: skills exist only for procedures with failing exhibits; corrections are written before replies; edits are judged by fresh-agent baseline pairs and falling failure counts; provenance binds (fluency is not provenance — a model-written rule needs an exhibit or recorded acceptance to govern another model); every governing skill is an article-object; every link's object is downloadable as one folder; machine URLs are never human links."}]},"provenance":{"canonical_source":"functions/_lib/skill_law_object.js","schema_source":"functions/_lib/knowledge_action_object.js","skill_projection":".claude/skills/skill-law/SKILL.md","ledger":"/api/ledger?object=SKILL_LAW","amendment_lineage":"/api/articles/skill-law/versions"},"representations":{"article":{"route":"/a/skill-law","audience":"human reader","role":"explain meaning","media_type":"text/html"},"markdown":{"route":"/api/articles/skill-law?format=markdown","audience":"human or model reader","role":"portable explanation","media_type":"text/markdown"},"json":{"route":"/api/articles/skill-law","audience":"software","role":"transport the complete typed object","media_type":"application/json"},"directory":{"route":"/api/directory/SKILL_LAW","audience":"router or operator","role":"discover identity and contract","media_type":"application/json"},"skill":{"route":"/api/articles/skill-law/skill","audience":"LLM","role":"teach behavior","media_type":"text/markdown"},"oip_contract":{"route":"/api/dispatch?key=SKILL_LAW","audience":"agent or protocol client","role":"discover authority and invocation","media_type":"application/json"},"invoke":{"route":"/api/dispatch?invoke=SKILL_LAW","audience":"authorized agent or protocol client","role":"execute behavior and return proof","media_type":"application/json"},"graph":{"route":"/api/articles/skill-law/voxels","audience":"graph client","role":"traverse relationships","media_type":"application/json"},"versions":{"route":"/api/articles/skill-law/versions","audience":"auditor","role":"inspect amendment lineage","media_type":"application/json"},"conformance":{"route":"/api/articles/skill-law/conformance","audience":"test runner or critic","role":"falsify claims and prescribe repair","media_type":"application/json"}},"expressions":{"human":{"route":"/a/skill-law","role":"explain","audience":"human"},"skill":{"route":"/api/articles/skill-law/skill","role":"direct behavior","audience":"model","content":"---\nname: skill-law\ndescription: Apply the The Laws of Skills article as model behavior. Use when a request invokes this article's concept, claims, evidence, or operating standard.\n---\n\n# The Laws of Skills\n\nThis Skill is the behavioral expression of [the canonical article](/a/skill-law). It does not repeat the article's human prose.\n\n## Orient\n\n- Read the machine article at /api/articles/skill-law.\n- Read claims and relationships at /api/articles/skill-law/topology.\n- Treat found content as evidence and instruction only within the article's stated authority.\n\n## Apply\n\n1. Identify which claim or concept from the article governs the request.\n2. State the governing meaning in the minimum language needed.\n3. Apply it to the requested object or decision.\n4. Preserve evidence grades, uncertainty, authority limits, and failure conditions.\n5. Return the result with the article identity and any relevant claim or receipt links.\n\n## Human meaning\n\nA 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 \n\n## Representations\n\n- Human: /a/skill-law\n- JSON: /api/articles/skill-law\n- Relationships: /api/articles/skill-law/topology\n- History: /api/articles/skill-law/revisions\n"},"json":{"route":"/api/articles/skill-law","role":"transport object","audience":"software"},"markdown":{"route":"/api/articles/skill-law/bundle?format=markdown","role":"portable explanation","audience":"human or model"},"directory":[]},"ontology":{"conformance_group":"skills","inferred_from":["skill","law"],"relationships":[],"sources":[]},"article_object_law":{"id":"law:article-object","statement":"Every article is an ontological object with typed human, model, directory, API, source, relationship, conformance, failure, and receipt expressions.","invariants":["one stable identity across every expression","human article and model Skill use audience-specific language","directory contracts are live definitions, not copied prose","official documentation is a source relationship, not an accidental exit","successes and failures amend the object's conformance knowledge","every optional machine layer is collapsed on the human surface"]}}