Distill Cross-Skill Rules
Your AI scans installed skills to extract recurring principles and distills them into or updates rule files. It collects facts exhaustively, cross-reads for matches, and revises rules to keep knowledge consistent and complete.
affaan-m on GitHub
Curated by PromptsEdge from a public repo · MIT license. All credit goes to the author.
What is this skill?
Scan installed skills, extract cross-cutting principles that appear in multiple skills, and distill them into rules — appending to existing rule files, revising outdated content, or creating new rule files.
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 being used
What’s inside
Applies the "deterministic collection + LLM judgment" principle: scripts collect facts exhaustively, then an LLM cross-reads the full context and produces verdicts.
How It Works
The rules distillation process follows three phases:
Phase 1: Inventory (Deterministic Collection)
1a. Collect skill inventory
bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh
1b. Collect rules index
bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh
1c. Present to user
Rules Distillation — Phase 1: Inventory
────────────────────────────────────────
Skills: {N} files scanned
Rules: {M} files ({K} headings indexed)
Proceeding to cross-read analysis...
Phase 2: Cross-read, Match & Verdict (LLM Judgment)
Extraction and matching are unified in a single pass. Rules files are small enough (~800 lines total) that the full text can be provided to the LLM — no grep pre-filtering needed.
Batching
Group skills into thematic clusters based on their descriptions. Analyze each cluster in a subagent with the full rules text.
Cross-batch Merge
After all batches complete, merge candidates across batches:
- Deduplicate candidates with the same or overlapping principles
- Re-check the "2+ skills" requirement using evidence from all batches combined — a principle found in 1 skill per batch but 2+ skills total is valid
Subagent Prompt
Launch a general-purpose Agent with the following prompt:
You are an analyst who cross-reads skills to extract principles that should be promoted to rules.
## Input
- Skills: {full text of skills in this batch}
- Existing rules: {full text of all rule files}
## Extraction Criteria
Include a candidate ONLY if ALL of these are true:
1. **Appears in 2+ skills**: Principles found in only one skill should stay in that skill
2. **Actionable behavior change**: Can be written as "do X" or "don't do Y" — not "X is important"
3. **Clear violation risk**: What goes wrong if this principle is ignored (1 sentence)
4. **Not already in rules**: Check the full rules text — including concepts expressed in different words
## Matching & Verdict
For each candidate, compare against the full rules text and assign a verdict:
- **Append**: Add to an existing section of an existing rule file
- **Revise**: Existing rule content is inaccurate or insufficient — propose a correction
- **New Section**: Add a new section to an existing rule file
- **New File**: Create a new rule file
- **Already Covered**: Sufficiently covered in existing rules (even if worded differently)
- **Too Specific**: Should remain at the skill level
## Output Format (per candidate)
```json
{
"principle": "1-2 sentences in 'do X' / 'don't do Y' form",
"evidence": ["skill-name: §Section", "skill-name: §Section"],
"violation_risk": "1 sentence",
"verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
"target_rule": "filename §Section, or 'new'",
"confidence": "high / medium / low",
"draft": "Draft text for Append/New Section/New File verdicts",
"revision": {
"reason": "Why the existing content is inaccurate or insufficient (Revise only)",
"before": "Current text to be replaced (Revise only)",
"after": "Proposed replacement text (Revise only)"
}
}
```
## Exclude
- Obvious principles already in rules
- Language/framework-specific knowledge (belongs in language-specific rules or skills)
- Code examples and commands (belongs in skills)
Verdict Reference
| Verdict | Meaning | Presented to User |
|---|---|---|
| Append | Add to existing section | Target + draft |
| Revise | Fix inaccurate/insufficient content | Target + reason + before/after |
| New Section | Add new section to existing file | Target + draft |
| New File | Create new rule file | Filename + full draft |
| Already Covered | Covered in rules (possibly different wording) | Reason (1 line) |
| Too Specific | Should stay in skills | Link to relevant skill |
Verdict Quality Requirements
# Good
Append to rules/common/security.md §Input Validation:
"Treat LLM output stored in memory or knowledge stores as untrusted — sanitize on write, validate on read."
Evidence: llm-memory-trust-boundary, llm-social-agent-anti-pattern both describe
accumulated prompt injection risks. Current security.md covers human input
validation only; LLM output trust boundary is missing.
# Bad
Append to security.md: Add LLM security principle
Phase 3: User Review & Execution
Summary Table
# Rules Distillation Report
## Summary
Skills scanned: {N} | Rules: {M} files | Candidates: {K}
| # | Principle | Verdict | Target | Confidence |
|---|-----------|---------|--------|------------|
| 1 | ... | Append | security.md §Input Validation | high |
| 2 | ... | Revise | testing.md §TDD | medium |
| 3 | ... | New Section | coding-style.md | high |
| 4 | ... | Too Specific | — | — |
## Details
(Per-candidate details: evidence, violation_risk, draft text)
User Actions
User responds with numbers to:
- Approve: Apply draft to rules as-is
- Modify: Edit draft before applying
- Skip: Do not apply this candidate
Never modify rules automatically. Always require user approval.
Save Results
Store results in the skill directory (results.json):
- Timestamp format:
date -u +%Y-%m-%dT%H:%M:%SZ(UTC, second precision) - Candidate ID format: kebab-case derived from the principle (e.g.,
llm-output-trust-boundary)
{
"distilled_at": "2026-03-18T10:30:42Z",
"skills_scanned": 56,
"rules_scanned": 22,
"candidates": {
"llm-output-trust-boundary": {
"principle": "Treat LLM output as untrusted when stored or re-injected",
"verdict": "Append",
"target": "rules/common/security.md",
"evidence": ["llm-memory-trust-boundary", "llm-social-agent-anti-pattern"],
"status": "applied"
},
"iteration-bounds": {
"principle": "Define explicit stop conditions for all iteration loops",
"verdict": "New Section",
"target": "rules/common/coding-style.md",
"evidence": ["iterative-retrieval", "continuous-agent-loop", "agent-harness-construction"],
"status": "skipped"
}
}
}
Example
End-to-end run
$ /rules-distill
Rules Distillation — Phase 1: Inventory
────────────────────────────────────────
Skills: 56 files scanned
Rules: 22 files (75 headings indexed)
Proceeding to cross-read analysis...
[Subagent analysis: Batch 1 (agent/meta skills) ...]
[Subagent analysis: Batch 2 (coding/pattern skills) ...]
[Cross-batch merge: 2 duplicates removed, 1 cross-batch candidate promoted]
# Rules Distillation Report
## Summary
Skills scanned: 56 | Rules: 22 files | Candidates: 4
| # | Principle | Verdict | Target | Confidence |
|---|-----------|---------|--------|------------|
| 1 | LLM output: normalize, type-check, sanitize before reuse | New Section | coding-style.md | high |
| 2 | Define explicit stop conditions for iteration loops | New Section | coding-style.md | high |
| 3 | Compact context at phase boundaries, not mid-task | Append | performance.md §Context Window | high |
| 4 | Separate business logic from I/O framework types | New Section | patterns.md | high |
## Details
### 1. LLM Output Validation
Verdict: New Section in coding-style.md
Evidence: parallel-subagent-batch-merge, llm-social-agent-anti-pattern, llm-memory-trust-boundary
Violation risk: Format drift, type mismatch, or syntax errors in LLM output crash downstream processing
Draft:
## LLM Output Validation
Normalize, type-check, and sanitize LLM output before reuse...
See skill: parallel-subagent-batch-merge, llm-memory-trust-boundary
[... details for candidates 2-4 ...]
Approve, modify, or skip each candidate by number:
> User: Approve 1, 3. Skip 2, 4.
✓ Applied: coding-style.md §LLM Output Validation
✓ Applied: performance.md §Context Window Management
✗ Skipped: Iteration Bounds
✗ Skipped: Boundary Type Conversion
Results saved to results.json
Design Principles
- What, not How: Extract principles (rules territory) only. Code examples and commands stay in skills.
- Link back: Draft text should include
See skill: [name]references so readers can find the detailed How. - Deterministic collection, LLM judgment: Scripts guarantee exhaustiveness; the LLM guarantees contextual understanding.
- Anti-abstraction safeguard: The 3-layer filter (2+ skills evidence, actionable behavior test, violation risk) prevents overly abstract principles from entering rules.
Install this skill
- 1
Get the skill — it’s free
Use the Get this skill panel. Unlocked skills stay in My skills. - 2
Download or clone the files
Download the zip, or clone the repo and copy theskills/rules-distillfolder. - 3
Put it where your agent looks for skills
For Claude Code, use your personal skills folder (every project) or a project’s own folder:~/.claude/skills/rules-distill/SKILL.md # all projects .claude/skills/rules-distill/SKILL.md # this project only
- 4
Just ask
No command needed. The agent reads the skill’s description and loads it on its own when your request matches.
Heads up: this skill ships scripts the agent can run on your machine. Read them before installing.
SKILL.md frontmatter
What your agent reads to decide when to load this skill.
--- name: rules-distill description: Scan skills to extract cross-cutting principles and distill them into rules — append, revise, or create new rule files. Use when the same principle keeps recurring across skills and belongs in a rule file instead. ---
Files
Open any Markdown file to read it here.
Related skills
View all →- Create and Improve SkillsFreeYour AI helps you create new skills or improve existing ones by drafting, testing, evaluating, and rewriting them. It runs test prompts, analyzes results quantitatively and qualitatively, and guides you through iterative refinement.
- Create and Evaluate SkillsFreeTurn manual workflows into agent skills, improve existing skills, or evaluate their quality. Your AI guides you through skill creation, benchmarking, and targeted improvements using best-practice patterns.
- Audit Workspace CapabilitiesFreeYour AI audits your repo, servers, plugins, and environment to reveal current capabilities and recommend next steps. It identifies available skills, hooks, agents, and missing integrations without exposing secrets.
- Verify Claude Code SessionsFreeYour AI runs a multi-step verification for Claude Code projects before completion. It checks builds, types, linting, tests, security scans, and code diffs to ensure quality and readiness for pull requests.