Skip to main content
Agent skill

Rules Distill

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.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Rules Distill when an AI agent needs a reusable SKILL.md workflow for this job: 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.

When not to use it

Skip Rules Distill when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/rules-distill
# Save SKILL.md to ~/.claude/skills/rules-distill/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/rules-distill/SKILL.md. For a shared project, commit the folder at .claude/skills/rules-distill/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Rules Distill skill for this task: Periodic rules maintenance (monthly or after installing new skills). Confirm any required inputs or files before making changes.

What supports this recommendation?

81/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
87/100
Practical detail
92/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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

| 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`)

```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.

Intended uses

  • 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

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.