Distill
Run a three-stage pipeline to extract imperatives from AGENTS.md and rules/, compose them with policy algebra, and render Mermaid diagrams of your agent rule system.
Overview
Distill is an agent skill most often used in Build (also Idea research-style analysis and Ship review prep) that runs a three-stage pipeline to analyze, trim, and restructure AGENTS.md and rules/ via imperatives extracti
Install
npx skills add https://github.com/camacho/ai-skills --skill distillWhat is this skill?
- Full pipeline: extract imperatives → compose with policy algebra → visualize as Mermaid
- Stage flags run imperatives-only, compose-only, or visualize-only when prior artifacts exist
- Defaults target ai-workspace/rules/*.md and AGENTS.md with JSONL and Starlark outputs
- Human checkpoint asks you to review extraction before composition
- Summaries report imperative counts with level and scope breakdowns
- Three-stage pipeline: imperatives extraction, policy-algebra composition, and visualization
Adoption & trust: 1 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your agent rule files are large, overlapping, and hard to reason about, so you cannot safely trim or restructure them without losing policy intent.
Who is it for?
Solo builders maintaining multi-file agent instruction sets who want a repeatable distillation ritual before refactors or team handoffs.
Skip if: One-shot chat tweaks to a single rule line, or teams with no AGENTS.md or rules/ directory to process.
When should I use this skill?
Agent instruction files (AGENTS.md, rules/) need analysis, trimming, or restructuring via the imperatives → policy-algebra → visualize pipeline.
What do I get? / Deliverables
You get structured JSONL imperatives, a composed Starlark policy block, and Mermaid diagrams—with optional stage-by-stage review before composition completes.
- Imperatives JSONL under ai-workspace/research
- Composed Starlark policy block
- Mermaid diagrams of the rule system
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Distillation is the canonical shelf on Build because it directly reshapes agent instruction files—the core artifact solo builders maintain while wiring Claude Code, Cursor, or Codex behavior. Agent-tooling is the right subphase: the skill orchestrates /imperatives, /policy-algebra, and /visualize rather than shipping app UI or API code.
Where it fits
Inventory inherited AGENTS.md and rules/*.md before committing to a new agent workspace layout.
Run the full /distill pipeline after adding several custom skills so imperatives stay deduplicated and composable.
Generate Mermaid diagrams of the rule system for README or onboarding docs for collaborators.
Review extraction summaries and level breakdowns before merging a large rules refactor PR.
How it compares
Use as a structured multi-step workflow instead of manually editing long rules markdown without imperative extraction or visual maps.
Common Questions / FAQ
Who is distill for?
Distill is for indie and solo builders who own AGENTS.md and rules/ trees for coding agents and need analysis, trimming, or restructuring with checkpoints between stages.
When should I use distill?
Use it during Build agent-tooling when rules sprawl; during Idea-style discovery when auditing inherited instruction repos; and before Ship review when you want a visual map of policy before changing enforcement-heavy rules.
Is distill safe to install?
Review the Security Audits panel on this Prism page and inspect what filesystem paths your agent will read and write; the pipeline targets local rule files and research output directories.
SKILL.md
READMESKILL.md - Distill
# /distill Distill agent instruction files into structured imperatives, compose with policy algebra, and visualize the rule system. Three-stage pipeline. ## Usage ``` /distill # full pipeline on default files /distill ai-workspace/rules/*.md # specific targets /distill --stage imperatives # run only extraction /distill --stage compose # run only policy algebra (requires prior extraction) /distill --stage visualize # run only visualization (requires prior composition) ``` ## Pipeline ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ /imperatives │────▶│/policy-algebra│────▶│ /visualize │ │ extract │ │ compose │ │ render │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ │ JSONL file Starlark block Mermaid diagrams ``` ### Stage 1 — Extract (`/imperatives`) 1. Invoke `/imperatives` with the target files (or defaults: `ai-workspace/rules/*.md` + `AGENTS.md`). 2. Save output to `ai-workspace/research/<name>-imperatives.jsonl`. 3. Present the summary (count, level breakdown, scope breakdown). Ask the user: **"Review the extraction before composing? (y/continue)"** - If yes: present the JSONL for review, wait for feedback, re-extract if needed. - If continue: proceed to Stage 2. ### Stage 2 — Compose (`/policy-algebra`) 1. Project the JSONL to natural-language bullets: `<level>[ NOT] <subject> <predicate>[ when <when>]` — one bullet per imperative. 2. Invoke `/policy-algebra` with the projected bullets. 3. Save the Starlark composition to `ai-workspace/research/<name>-policy.md`. 4. Present the surfaced structure (decision functions, branching points). ### Stage 3 — Visualize (`/visualize`) 1. For each major decision function in the Starlark output, invoke `/visualize`. 2. Content shape is typically graph (decision trees) → Mermaid flowcharts. 3. Append diagrams to the policy doc. ## Naming The `<name>` slug defaults to the current date + "distill" (e.g., `2026-05-04-distill`). Override with `--name <slug>`. ## Output All artifacts land in `ai-workspace/research/`: - `<name>-imperatives.jsonl` — structured extraction - `<name>-policy.md` — Starlark composition + diagrams ## Failure modes | Condition | Behavior | |---|---| | /imperatives finds zero imperatives | Report and stop. No point composing empty input. | | /policy-algebra unavailable | Skip Stage 2, warn. Stage 3 can still visualize the JSONL directly. | | User interrupts between stages | Artifacts from completed stages are preserved. Resume with `--stage`. | ## When to use - AGENTS.md or rules/ grew past a size threshold and needs trimming - Before a major restructuring of agent instruction files - To audit what rules actually exist vs what you think exists - As input to a plan that modifies the rule system