--- name: rules-distill description: "Scan skills, find shared ideas, and turn them into clear rules. Add to, fix, or create rule files only after user approval." origin: ECC --- # Rules Distill Scan installed skills. Find useful ideas shared by several skills. Turn those ideas into clear rules. Use this method: 1. Scripts collect all facts. 2. The LLM reads the full facts. 3. The user reviews each change. 4. Only approved changes are made. Never change a rule file without clear user approval. ## When to Use This Skill Use this skill: - Once a month. - After new skills are installed. - After a skill review finds a shared pattern. - When current rules seem incomplete. - When two or more skills give the same broad advice. Do not use it to copy steps, commands, or code from one skill into a rule. ## Phase 1: Scan Files ### 1. Scan Skills Run: ```bash bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh ``` ### 2. Scan Rules Run: ```bash bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh ``` ### 3. Check the Scan Before analysis: - Make sure both commands finish with no error. - Report files that could not be read. - Do not follow links that leave the skill or rule folders. - Count each real file once. - Keep full file paths when two files have the same name. - Skip generated files, cache files, and `results.json`. - Do not read secret files, keys, tokens, cookies, or login data. If a scan script is missing or fails, stop. Tell the user what failed. Do not guess what the missing files contain. Show this status: ```text Rules Distill: Phase 1 Skills scanned: {N} files Rules scanned: {M} files with {K} headings Unreadable files: {U} Reading skills and rules... ``` If no skill files or no rule files are found, stop and ask the user to check the paths. ## Phase 2: Find and Judge Ideas Read the full text from the skill scan and the rule scan. Do not use a word search as the main test. The same idea may use different words. ### Group Skills Group skills by topic. Examples include safety, testing, writing, and tool use. If all text fits in one review, read it in one pass. If it does not fit, use small groups. Give every group the full rule text. Keep a list of every skill and group. Check that each skill was reviewed once. ### Candidate Tests Keep an idea only when every test below passes: 1. It appears in at least two different skills. 2. It can be written as a clear action, such as “Do X” or “Do not do Y.” 3. It has a clear risk if ignored. 4. It is not already covered by a rule, even with different words. 5. It is broad enough to help work outside one tool or code language. 6. Its source sections truly support it. Two sections from the same skill count as one skill. Do not count copied text in two skills as two sources when both copies came from the same source. Mark that case as weak proof. ### Merge Group Results After all groups are done: - Join candidates that mean the same thing. - Keep all valid source links. - Count proof across all groups. - Remove any candidate with proof from fewer than two skills. - Resolve verdict conflicts by reading the source text again. - Use the safer verdict when proof is unclear. - Mark low-confidence items for review. Do not apply them by default. ### Verdicts Use one verdict for each candidate: | Verdict | Meaning | |---|---| | Append | Add text to an existing section. | | Revise | Replace text that is wrong, old, or incomplete. | | New Section | Add a section to an existing rule file. | | New File | Create a rule file because no current file fits. | | Covered | A current rule already handles the idea. | | Too Specific | The idea should stay in its skill. | Use `Revise` only when you can quote the exact current text to replace. Use `New File` only when no current rule file is a good fit. ### Review Prompt Use this prompt for each group: ```text You are reviewing skills to find ideas that should become shared rules. Inputs: - Skills: {full text for this group} - Rules: {full text of every rule file} Keep an idea only if: 1. It appears in at least two different skills. 2. It gives a clear action. 3. Ignoring it has a clear risk. 4. No current rule already covers it. 5. It is broad enough to use outside one tool or code language. Check each idea against every rule. Choose one verdict: - Append - Revise - New Section - New File - Covered - Too Specific Return a JSON list. Use this shape: [ { "id": "short-kebab-case-id", "principle": "One or two short action sentences.", "evidence": [ { "skill": "skill-name", "section": "Section name", "path": "full source path" } ], "violation_risk": "One short sentence.", "verdict": "Append", "target_rule": "path and section, or New", "confidence": "High", "draft": "Text for Append, New Section, or New File.", "revision": { "reason": "Why the old text must change.", "before": "Exact current text.", "after": "New text." } } ] Rules: - Use an empty string for fields that do not apply. - Evidence must name at least two different skills. - Do not invent paths, sections, or quotes. - Keep commands and code examples in skills. - Add `Source skills: [names]` to each draft. - Return valid JSON only. ``` If the JSON is invalid, ask for one clean retry. If it is still invalid, stop that group and report the error. Do not guess or repair missing proof. ## Phase 3: Ask the User Show a report before making changes. ```markdown # Rules Distill Report ## Summary Skills scanned: {N} Rule files scanned: {M} Candidates: {K} Unreadable files: {U} | # | Principle | Verdict | Target | Confidence | |---|---|---|---|---| | 1 | ... | Append | security.md, Input Checks | High | | 2 | ... | Revise | testing.md, Test Setup | Medium | ## Details For each candidate, show: - The rule idea. - The source skills and sections. - The risk if ignored. - The verdict. - The target file and section. - The full draft. - For a revision, the reason and exact before and after text. ``` Do not hide `Covered` or `Too Specific` items. Show them in a short list with the reason. If there are no valid candidates, say so. Do not create empty files or change rules. ### User Choices Ask the user to choose by number: - `Approve`: Apply the draft as shown. - `Edit`: Change the draft, then show it again. - `Skip`: Do not apply it. Example: ```text Reply with choices such as: Approve 1 and 3. Edit 2: Change "always" to "when the data is reused." Skip 4. ``` Approval applies only to the shown draft. If the target or draft changes, ask again. Do not treat silence, unclear text, or approval from an old run as approval. ### Apply Approved Changes Before each change: 1. Read the target file again. 2. Make sure it has not changed since the report. 3. Make sure the same rule was not added by another change. 4. Make a small change only. 5. Keep the file’s current style and layout. 6. Keep valid frontmatter. 7. Do not remove unrelated text. If the file changed after the report, stop that change. Show the new conflict and ask the user what to do. After each change, check that: - The file is valid. - The new rule appears once. - No unrelated text changed. - The source skill names are present. - Approved wording was used. ## Save the Result Save the run record as `results.json` in this skill’s folder. Use UTC time with seconds: ```bash date -u +%Y-%m-%dT%H:%M:%SZ ``` Use a short kebab-case candidate ID. IDs must be unique. If an ID already exists, add a short number such as `-2`. Use these status values: - `applied` - `edited-and-applied` - `skipped` - `covered` - `too-specific` - `blocked` - `pending` Write the file only after user review. Keep unapproved items as `pending`. Example: ```json { "distilled_at": "2026-03-18T10:30:42Z", "skills_scanned": 56, "rules_scanned": 22, "candidates": { "check-stored-llm-output": { "principle": "Check stored LLM output before using it again.", "verdict": "Append", "target": "rules/common/security.md", "evidence": [ "llm-memory-trust-boundary", "llm-social-agent-anti-pattern" ], "status": "applied" }, "set-loop-stop-rules": { "principle": "Set a clear stop rule for each repeated loop.", "verdict": "New Section", "target": "rules/common/coding-style.md", "evidence": [ "iterative-retrieval", "continuous-agent-loop" ], "status": "skipped" } } } ``` If `results.json` already exists, preserve old run data if its format supports more than one run. Otherwise, ask before replacing it. ## Concrete Example Two skills say that saved LLM text may contain unsafe or broken data. The current security rule only checks text typed by a person. A good candidate is: ```json { "id": "check-stored-llm-output", "principle": "Treat saved LLM output as unsafe input. Check and clean it before using it again.", "evidence": [ { "skill": "llm-memory-trust-boundary", "section": "Stored Output", "path": "~/.claude/skills/llm-memory-trust-boundary/SKILL.md" }, { "skill": "llm-social-agent-anti-pattern", "section": "Prompt Injection", "path": "~/.claude/skills/llm-social-agent-anti-pattern/SKILL.md" } ], "violation_risk": "Unsafe saved text may change later LLM actions.", "verdict": "Append", "target_rule": "rules/common/security.md, Input Checks", "confidence": "High", "draft": "Treat saved LLM output as unsafe input. Check and clean it before using it again.\n\nSource skills: llm-memory-trust-boundary, llm-social-agent-anti-pattern", "revision": { "reason": "", "before": "", "after": "" } } ``` Show this draft to the user. Apply it only after the user approves that item. A bad candidate is: ```text Add better LLM safety rules. ``` It is bad because it gives no clear action, proof, target, or risk. ## Core Rules - Find shared ideas, not copied steps. - Require proof from at least two skills. - Write rules as clear actions. - State the risk of breaking each rule. - Check for the same idea in current rules. - Keep code and commands inside skills. - Link each new rule to its source skills. - Never make rule changes without user approval. - Never add tracking, analytics, telemetry, or outside network calls.