create-repo-rule
create-repo-rule is the repo-rule authoring workflow packet of the sk-doc family. It
turns a user's request — a behaviour they want, or a failure they keep hitting — into a
file in the target repository's rules directory (.skilled/repo-rules/ where a .skilled
source root exists, repo-rules/ otherwise), wired into its REPO RULES.md router.
Most requests should not become a rule. The four decision tests in
references/decision-tests.md refuse more than they admit, and running them first is the
cheap order. Authoring a rule that then fails a test is the expensive one.
A repo rule supplements the harness. It sits below AGENTS.md and below a live
operator instruction, it can be changed when it stops matching the work, and it can be
removed when it stops earning its load. This mode owns all three.
1. WHEN TO USE
Activation Triggers
- Someone asks for a repo rule, a project rule, or a convention that should bind before an action.
- Someone describes a recurring failure and asks how to stop it happening again.
- An existing rule needs changing because it no longer matches how the work is done.
- A rule needs retiring because nothing it prevents still happens.
- A repository needs a rule router because it has none.
Keyword triggers: create repo rule, /create:repo-rule, repo rule, project rule, REPO RULES.md, repo-rules, add a rule, retire a rule, revise a rule, trigger table, rule router.
When NOT to Use
- It teaches how to do something. A skill is capability, a rule is constraint. Route to the skill-authoring mode.
- It must bind on every turn. Content that holds when no trigger fires belongs in the always-loaded document, not behind a trigger. This is decision test 1 and the most common refusal.
- It is routing. Which skill, which command, which agent, which flags. The always-loaded document and the skills it routes to own that.
- It is one line, not a cluster. A single row is a section inside an existing rule.
- A sibling mode already produces it. README, changelog, command, catalog, playbook and diagram all have owners.
2. SMART ROUTING
sk-doc routes repo-rule authoring here: the request names a repo rule, a project rule, REPO RULES.md or /create:repo-rule.
The hub's mode signal selects this packet.
Four operations route here: create, revise, retire and router.
The operation decides which resources load, and the decision tests decide whether anything should be authored at all.
references/decision-tests.md loads first on every path, including retire, because whether a rule should exist and whether it should still exist are the same four questions.
references/README.md routes the rest.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Create
Run the four decision tests. Always-loaded, scope boundary, four-part refusal, restraint.
On refusal, name the test that failed and where the content goes instead — the tests' section 6 maps every refusal to a destination. Stop here. This is the common outcome.
Check the destination exists. No REPO RULES.md in the target repository means no rule can load; emit the router from assets/repo-rules-router-template.md first.
Fill assets/repo-rule-template.md. Ten fixed elements, open numbered body, aim under 160 lines.
Run references/creation-standards.md against the draft. Structure is checkable and is not the bar; a rule can pass every assertion and be worth nobody's context.
Wire it: a trigger row and an index row in the router, and a pointer from the AGENTS.md section it governs.
Verify by running the checker, not by eye: node .skilled/skills/sk-doc/sk-create-repo-rule/scripts/check-repo-rules.cjs.
It exits non-zero on any failure, and it asserts:
- count parity across the rule files and both router tables.
- row coverage with link resolution.
- trigger-phrase uniqueness, the line ceiling, frontmatter keys, divider parity and rule links.
- fires-when sections.
- that every index summary matches its rule's own description.
- that every Fires-when bullet has a counterpart in its router row.
- that every committed rule card still matches the card its rule renders.
A hand check of the same properties is how every one of them drifted before the checker existed. What it cannot judge is whether the rule is worth loading at all, which is references/creation-standards.md and still needs a reader.
Revise
Run the decision tests again first — a rule that no longer passes them should be retired,
not patched. Then edit, and if the change alters when the rule fires, change the trigger
row in the same edit or the router lies silently. Bump version. Full ordering and the
version convention: references/agents-md-integration.md §5.
To learn whether a revision changed behaviour, measure instead of guessing:
python3 .skilled/skills/sk-doc/sk-create-repo-rule/scripts/measure-rule-compliance.py.
It reads local Claude Code and Codex transcripts and reports, per runtime, delivery
receipts by channel and compaction window, the Gate 5 and reply-rule miss rates, and each
reply prohibition split by the rule's git blob version, every rate with its denominator and
a Wilson 95% interval. It prints aggregates only, never transcript text.
Retire
Pointer first, then index row, then trigger row, then the file — create inverted, so no
intermediate state leaves a row pointing at nothing. Record why it went. Do not archive;
git holds the history. Full ordering: references/agents-md-integration.md §6.
4. RULES
✅ ALWAYS
- Run the decision tests before authoring, on every path including retire.
- Emit the router first when the target repository has none.
- Quote
title and description in frontmatter; both routinely contain a colon.
- Keep dividers equal to numbered sections.
- Make clear, in every numbered section, what goes wrong without it — in the section's substance if not in a dedicated line.
- Name the failed test and the destination on every refusal.
⛔ NEVER
- Write a rule that must bind when no trigger fires. That is an
AGENTS.md row.
- Put routing, skill selection, or dispatch mechanics into a rule.
- Edit
AGENTS.md beyond adding or removing a pointer. The always-loaded document carries hard blockers; anything else is an operator decision.
- Add a rule because the set looks thin. The set is subject to its own
overengineering.md.
- Restate another rule instead of linking to it — though the default is no link at all.
- Report a refusal as a failure. It is the designed outcome for most requests.
⚠️ ESCALATE IF
- The request needs an
AGENTS.md change beyond a pointer, or a widening of the router's scope statement.
- Two existing rules disagree, and the new rule would have to pick a side.
- The proposal fails a test but the operator wants it anyway — that is their call to make explicitly, not one to infer.
5. SUCCESS CRITERIA
- A generated rule passes the same structural checks the shipped corpus passes.
- A refused request leaves the user knowing which test it failed and where the content belongs.
- A retired rule leaves no dangling router row or pointer.
- The rule set does not grow because rules were easy to write.
6. REFERENCES
Routed by references/README.md. Load
references/decision-tests.md first on every path; everything else is conditional.
references/decision-tests.md: the four tests deciding whether a rule may exist and where refused content goes.
references/rule-anatomy.md: the ten fixed elements, what varies and the length bands.
references/creation-standards.md: the five reader tests deciding whether a well-formed rule earns its load.
references/agents-md-integration.md: the three wiring points, the scope check and the create, revise and retire orderings.
assets/repo-rule-template.md: the blank a new rule is filled from.
assets/repo-rules-router-template.md: the router for a repository that has none.
1---2name: sk-create-repo-rule3description: Author, revise or retire a repo rule from a user's request, with the decision tests that refuse most of them.4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 1.1.8.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-create-repo-rule8---910# create-repo-rule1112`create-repo-rule` is the repo-rule authoring workflow packet of the `sk-doc` family. It13turns a user's request — a behaviour they want, or a failure they keep hitting — into a14file in the target repository's rules directory (`.skilled/repo-rules/` where a `.skilled`15source root exists, `repo-rules/` otherwise), wired into its `REPO RULES.md` router.1617**Most requests should not become a rule.** The four decision tests in18`references/decision-tests.md` refuse more than they admit, and running them first is the19cheap order. Authoring a rule that then fails a test is the expensive one.2021A repo rule **supplements the harness**. It sits below `AGENTS.md` and below a live22operator instruction, it can be changed when it stops matching the work, and it can be23removed when it stops earning its load. This mode owns all three.2425---2627## 1. WHEN TO USE2829### Activation Triggers3031- Someone asks for a repo rule, a project rule, or a convention that should bind before an action.32- Someone describes a recurring failure and asks how to stop it happening again.33- An existing rule needs changing because it no longer matches how the work is done.34- A rule needs retiring because nothing it prevents still happens.35- A repository needs a rule router because it has none.3637Keyword triggers: `create repo rule`, `/create:repo-rule`, `repo rule`, `project rule`, `REPO RULES.md`, `repo-rules`, `add a rule`, `retire a rule`, `revise a rule`, `trigger table`, `rule router`.3839### When NOT to Use4041- **It teaches how to do something.** A skill is capability, a rule is constraint. Route to the skill-authoring mode.42- **It must bind on every turn.** Content that holds when no trigger fires belongs in the always-loaded document, not behind a trigger. This is decision test 1 and the most common refusal.43- **It is routing.** Which skill, which command, which agent, which flags. The always-loaded document and the skills it routes to own that.44- **It is one line, not a cluster.** A single row is a section inside an existing rule.45- **A sibling mode already produces it.** README, changelog, command, catalog, playbook and diagram all have owners.4647---4849## 2. SMART ROUTING5051`sk-doc` routes repo-rule authoring here: the request names a repo rule, a project rule, `REPO RULES.md` or `/create:repo-rule`.52The hub's mode signal selects this packet.53Four operations route here: create, revise, retire and router.54The operation decides which resources load, and the decision tests decide whether anything should be authored at all.5556`references/decision-tests.md` loads first on every path, including retire, because whether a rule should exist and whether it should still exist are the same four questions.57`references/README.md` routes the rest.5859Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.6061---6263## 3. HOW IT WORKS6465### Create66671. **Run the four decision tests.** Always-loaded, scope boundary, four-part refusal, restraint.682. **On refusal**, name the test that failed and where the content goes instead — the tests' section 6 maps every refusal to a destination. Stop here. This is the common outcome.693. **Check the destination exists.** No `REPO RULES.md` in the target repository means no rule can load; emit the router from `assets/repo-rules-router-template.md` first.704. **Fill `assets/repo-rule-template.md`.** Ten fixed elements, open numbered body, aim under 160 lines.715. **Run `references/creation-standards.md` against the draft.** Structure is checkable and is not the bar; a rule can pass every assertion and be worth nobody's context.726. **Wire it**: a trigger row and an index row in the router, and a pointer from the `AGENTS.md` section it governs.737. **Verify by running the checker**, not by eye: `node .skilled/skills/sk-doc/sk-create-repo-rule/scripts/check-repo-rules.cjs`.74 It exits non-zero on any failure, and it asserts:75 - count parity across the rule files and both router tables.76 - row coverage with link resolution.77 - trigger-phrase uniqueness, the line ceiling, frontmatter keys, divider parity and rule links.78 - fires-when sections.79 - that every index summary matches its rule's own description.80 - that every Fires-when bullet has a counterpart in its router row.81 - that every committed rule card still matches the card its rule renders.8283 A hand check of the same properties is how every one of them drifted before the checker existed. What it cannot judge is whether the rule is worth loading at all, which is `references/creation-standards.md` and still needs a reader.8485### Revise8687Run the decision tests again first — a rule that no longer passes them should be retired,88not patched. Then edit, and if the change alters *when* the rule fires, change the trigger89row in the same edit or the router lies silently. Bump `version`. Full ordering and the90`version` convention: `references/agents-md-integration.md` §5.9192To learn whether a revision changed behaviour, measure instead of guessing:93`python3 .skilled/skills/sk-doc/sk-create-repo-rule/scripts/measure-rule-compliance.py`.94It reads local Claude Code and Codex transcripts and reports, per runtime, delivery95receipts by channel and compaction window, the Gate 5 and reply-rule miss rates, and each96reply prohibition split by the rule's git blob version, every rate with its denominator and97a Wilson 95% interval. It prints aggregates only, never transcript text.9899### Retire100101Pointer first, then index row, then trigger row, then the file — create inverted, so no102intermediate state leaves a row pointing at nothing. Record why it went. Do not archive;103git holds the history. Full ordering: `references/agents-md-integration.md` §6.104105---106107## 4. RULES108109### ✅ ALWAYS1101111. Run the decision tests before authoring, on every path including retire.1122. Emit the router first when the target repository has none.1133. Quote `title` and `description` in frontmatter; both routinely contain a colon.1144. Keep dividers equal to numbered sections.1155. Make clear, in every numbered section, what goes wrong without it — in the section's substance if not in a dedicated line.1166. Name the failed test and the destination on every refusal.117118### ⛔ NEVER1191201. Write a rule that must bind when no trigger fires. That is an `AGENTS.md` row.1212. Put routing, skill selection, or dispatch mechanics into a rule.1223. Edit `AGENTS.md` beyond adding or removing a pointer. The always-loaded document carries hard blockers; anything else is an operator decision.1234. Add a rule because the set looks thin. The set is subject to its own `overengineering.md`.1245. Restate another rule instead of linking to it — though the default is no link at all.1256. Report a refusal as a failure. It is the designed outcome for most requests.126127### ⚠️ ESCALATE IF1281291. The request needs an `AGENTS.md` change beyond a pointer, or a widening of the router's scope statement.1302. Two existing rules disagree, and the new rule would have to pick a side.1313. The proposal fails a test but the operator wants it anyway — that is their call to make explicitly, not one to infer.132133---134135## 5. SUCCESS CRITERIA136137- A generated rule passes the same structural checks the shipped corpus passes.138- A refused request leaves the user knowing which test it failed and where the content belongs.139- A retired rule leaves no dangling router row or pointer.140- The rule set does not grow because rules were easy to write.141142---143144## 6. REFERENCES145146Routed by [`references/README.md`](references/README.md). Load147`references/decision-tests.md` first on every path; everything else is conditional.148149- [`references/decision-tests.md`](references/decision-tests.md): the four tests deciding whether a rule may exist and where refused content goes.150- [`references/rule-anatomy.md`](references/rule-anatomy.md): the ten fixed elements, what varies and the length bands.151- [`references/creation-standards.md`](references/creation-standards.md): the five reader tests deciding whether a well-formed rule earns its load.152- [`references/agents-md-integration.md`](references/agents-md-integration.md): the three wiring points, the scope check and the create, revise and retire orderings.153- [`assets/repo-rule-template.md`](assets/repo-rule-template.md): the blank a new rule is filled from.154- [`assets/repo-rules-router-template.md`](assets/repo-rules-router-template.md): the router for a repository that has none.