Agent skill

Rules Distillation

by affaan-m in affaan-m/ECC

Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered.

MITAuto-check passedAgent Workflows

Install Rules Distillation

skills CLI
$ npx skills add affaan-m/ECC --skill rules-distill -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install affaan-m/ECC rules-distill --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/rules-distill .claude/skills/rules-distill && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
rules-distill
GitHub stars
277k
Used in
2 other repos
Token cost
~2.3k tokens
SKILL.md length
421 words
Files
3 (incl. scripts)
Skills in repo
683
Repo updated
First seen
Licence
MIT

At a glance

Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered.

  • Works in 3 steps: Inventory (Deterministic Collection) → Cross-read, Match & Verdict (LLM Judgment) → User Review & Execution
  • Running periodic maintenance on your rule files
  • SKILL.md covers When to Use, How It Works, Example and Design Principles
  • Runs Shell scripts from its folder; calls bash

What it does

Principles that keep showing up in several skills belong in a rule file, and this skill finds them. It works in phases where scripts collect the facts exhaustively and the agent then reads everything together and gives a verdict for each candidate.

Phase one runs scan-skills.sh and scan-rules.sh to inventory the skills and the existing rules and shows you the counts. Phase two groups skills into thematic clusters, has a subagent cross-read each cluster against the full rules text, and then merges candidates across batches, removing duplicates and rechecking that a principle appears in at least two skills when all batches are combined.

Each candidate gets a verdict: append to an existing section, revise inaccurate or insufficient content with a before and after, add a new section, create a new rule file, or mark it as already covered, and each is presented to you. It suits periodic rules maintenance, such as monthly or after installing new skills, or after a skill stocktake reveals patterns that should be rules.

When your agent uses it

  • Running periodic maintenance on your rule files
  • A skill stocktake revealed patterns that look like rules
  • Your rules feel incomplete compared with the skills you use

Example prompts

  • “Distill the principles shared across my installed skills into rules and show me the verdicts.”
  • “Check whether the rules folder already covers what the new testing skills say.”
  • “Run the rules distillation and propose a new rule file for anything that appears in several skills.”

Requirements

  • Bash, to run the bundled scan scripts
  • Installed skills and an existing rules folder

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Inventory (Deterministic Collection)
  2. Cross-read, Match & Verdict (LLM Judgment)
  3. User Review & Execution

What it can do on your machine

Read from SKILL.md and the folder at commit 2d515e4. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Rules Distillation loads about 2.3k tokens when it runs. Until then it costs about 57 tokens; SKILL.md has 421 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from affaan-m/ECC at commit 2d515e4, republished under its MIT licence (© affaan-m). 421 words, ~2,347 tokens.

Download SKILL.mdSave it as .claude/skills/rules-distill/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
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.
metadata.origin
ECC

Rules Distill

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.

Applies the "deterministic collection + LLM judgment" principle: scripts collect facts exhaustively, then an LLM cross-reads the full context and produces verdicts.

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

How It Works

The rules distillation process follows three phases:

Phase 1: Inventory (Deterministic Collection)
1a. Collect skill inventory
bash
bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh
1b. Collect rules index
bash
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
VerdictMeaningPresented to User
AppendAdd to existing sectionTarget + draft
ReviseFix inaccurate/insufficient contentTarget + reason + before/after
New SectionAdd new section to existing fileTarget + draft
New FileCreate new rule fileFilename + full draft
Already CoveredCovered in rules (possibly different wording)Reason (1 line)
Too SpecificShould stay in skillsLink to relevant skill
Show full SKILL.md (138 more words)Show less
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)
json
{
  "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.

© affaan-m, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in skills/rules-distill of affaan-m/ECC.

  • SKILL.md
  • scripts/scan-rules.sh
  • scripts/scan-skills.sh

Open the folder on GitHubat commit 2d515e4

Used in 2 other repositories

We found 7 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in affaan-m/ECC, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Rules Distillation next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Rules Distillation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Rules Distillation this skillaffaan-m/ECC277k2 repos~2.3kAutomated safety check: PassMIT
Task Observerrebelytics/one-skill-to-rule-them-all3.2k1 repos~11kAutomated safety check: PassCC-BY-4.0
Using Agent Skillsaddyosmani/agent-skills105k4 repos~2.4kAutomated safety check: PassMIT
Harness Agent Team Designerrevfactory/harness9.1k—~4.5kAutomated safety check: PassApache-2.0
Repo Task Proof LoopDenisSergeevitch/repo-task-proof-loop730—~3.8kAutomated safety check: PassApache-2.0
Claude Docs Consultantcentminmod/my-claude-code-setup2.7k—~959Automated safety check: PassMIT

Similar skills

  • Task Observer

    rebelytics/one-skill-to-rule-them-all

    Monitors task execution for skill improvement opportunities.

    3.2k GitHub starsUsed in 1 repo~11k tokens
    Agent WorkflowsAuto-check passed
  • Using Agent Skills

    addyosmani/agent-skills

    Meta-skill for choosing which workflow skill fits the task at hand, plus always-on habits: surface assumptions, stop on confusion, push back, keep it simple and stay in scope.

    105k GitHub starsUsed in 4 repos~2.4k tokens
    Agent WorkflowsAuto-check passed
  • Harness Agent Team Designer

    revfactory/harness

    Designs a project-specific agent harness: defines specialist agents, writes the skills they follow, picks an execution mode and model for each, and keeps the setup maintained.

    9.1k GitHub stars~4.5k tokensUpdated 13 days ago
    Agent WorkflowsAuto-check passed
  • Repo Task Proof Loop

    DenisSergeevitch/repo-task-proof-loop

    Repo-local workflow skill for large coding tasks. An agent skill from DenisSergeevitch/repo-task-proof-loop.

    730 GitHub stars~3.8k tokensUpdated 6 mo ago
    Agent WorkflowsAuto-check passed
  • Claude Docs Consultant

    centminmod/my-claude-code-setup

    Consult official Claude Code documentation from code.claude.com using selective fetching.

    2.7k GitHub stars~959 tokensUpdated 3 days ago
    Agent WorkflowsAuto-check passed
  • Audits the AI skills installed for a project for duplicate names, broad triggers and conflicting instructions, without changing any of them.

    726 GitHub stars~794 tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

More from affaan-m/ECC

All 682 skills in this repo
  • Skill Stocktake

    affaan-m/ECC

    Audits your installed Claude skills and commands for quality, with a quick mode for recently changed skills and a full mode that evaluates all of them through subagents.

    277k GitHub starsUsed in 5 repos~3.1k tokens
    Auto-check passed
  • Ingests, indexes, searches, edits and monitors video, audio and live streams through the VideoDB Python SDK, returning stream links, clips and timestamps.

    277k GitHub starsUsed in 3 repos~3.5k tokens
    Auto-check: notes
  • Docs Governance

    affaan-m/ECC

    Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references.

    277k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Builds DRAFT counterparty agreements from one markdown template and a small JSON spec per party, with clauses picked by the party's role.

    277k GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • Set an ECC-specific frontend design direction for production UI work.

    277k GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed
  • Measures whether agents actually follow a skill, rule or agent definition by generating scenarios at three strictness levels and scoring tool-call traces.

    277k GitHub starsUsed in 1 repo~623 tokens
    Auto-check passed

Categories

Questions about Rules Distillation

What does Rules Distillation do?

Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered. Principles that keep showing up in several skills belong in a rule file, and this skill finds them. It works in phases where scripts collect the facts exhaustively and the agent then reads everything together and gives a verdict for each candidate.

When should I use Rules Distillation?

Rules Distillation fits situations like: running periodic maintenance on your rule files; A skill stocktake revealed patterns that look like rules; your rules feel incomplete compared with the skills you use.

How do I install Rules Distillation in Claude Code?

Run `npx skills add affaan-m/ECC --skill rules-distill -a claude-code`. Or copy the skill folder (skills/rules-distill in affaan-m/ECC) into .claude/skills/rules-distill in your project. Claude Code loads it when a task matches its description.

How do I install Rules Distillation in Codex?

Run `npx skills add affaan-m/ECC --skill rules-distill -a codex`. Or copy the skill folder (skills/rules-distill in affaan-m/ECC) into .agents/skills/rules-distill in your project. Codex loads it when a task matches its description.

Can I use Rules Distillation in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add affaan-m/ECC --skill rules-distill -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/rules-distill, .gemini/skills/rules-distill, .github/skills/rules-distill and .opencode/skills/rules-distill in your project.

What does Rules Distillation need to run?

Going by SKILL.md and its folder, Rules Distillation needs a shell for the scripts in its folder and the command-line tools its instructions call (bash). Our summary lists: Bash, to run the bundled scan scripts; Installed skills and an existing rules folder.

Does Rules Distillation access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Rules Distillation safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Rules Distillation use?

Rules Distillation is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Rules Distillation use?

About 2.3k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Rules Distillation?

Skills that share tags, products or a category with Rules Distillation: Task Observer (rebelytics/one-skill-to-rule-them-all, 3.2k stars), Using Agent Skills (addyosmani/agent-skills, 105k stars), Harness Agent Team Designer (revfactory/harness, 9.1k stars) and Repo Task Proof Loop (DenisSergeevitch/repo-task-proof-loop, 730 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Rules Distillation?

affaan-m (a GitHub user) maintains it in affaan-m/ECC, which has 276,673 GitHub stars. The repository holds 683 skills in this directory. The repository was last updated on October 11, 2026.

Source: affaan-m/ECC on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.