rules-distill

rules-distill — promote environment-specific facts to rules

Scan installed skills, find principles that belong in the always-loaded rules layer, and distill them into rules — appending to, revising, or creating rule files. The skill produces candidates and verdicts; it never edits rules without your approval.

Roots. <harness> below is the harness this audit covers: ~/.claude by default, or a repository's .claude/ when skill harness-stocktake runs in project mode (its Roots section maps the paths, names the evidence that is n/a there, and says which convention checks apply). The ledger <ledger> belongs to that harness: ${CLAUDE_SKILL_DIR}/results.json when this skill's directory is inside <harness> (the harness carries its own copy of the skill), else <harness>/stocktake/rules-distill.json (an installed plugin, or project mode). Either way it is committed with the harness's other changes on the apply branch.

When to Use

• Periodic rules maintenance (monthly, or after installing new skills)
• After a skill-stocktake reveals patterns that should be rules
• When rules feel incomplete relative to the skills in use

Phase 1 — Inventory (Glob, exhaustive)

Enumerate with Glob (no script):

• Skills: <harness>/skills/*/SKILL.md
• Rules: read every <harness>/rules/**/*.md in full — the corpus is small, so no grep pre-filter is needed

Glob targets only skill definition files, so dependency markdown under .venv / .pytest_cache is excluded structurally.

Present the counts (skills scanned, rule files, headings) before analysis.

Phase 2 — Cross-read & Verdict (inline, holistic)

Read every skill body and every rule into one context and analyze them together — extraction and matching are a single pass. Seeing all skills at once is what makes the recurrence count exact and the "not already in rules" test reliable.

A principle is a candidate only if ALL of these hold:

1. Environment-specific — a fact, a wiring, or a trap particular to this machine, harness, or set of accounts. A general engineering principle is not a candidate no matter how many skills repeat it.
2. Substrate does not already do it — if the current model handles it natively, a written rule does not add behaviour; it freezes an older default and competes with the newer one.
3. Not a procedure — steps and workflows belong in a skill. Residency is for facts and wiring, which have to be true before any particular task starts.
4. Actionable behavior change — expressible as "do X" / "don't do Y", not "X is important"
5. Clear violation risk — what goes wrong if ignored, in one sentence
6. Not already in rules — check the full rules text, including the same idea in different words