# Distill

> Decompose a complex system (codebase, architecture, paper, transcript, or document set) into essential primitives and a compressed mental model, without a line-by-line walkthrough. Prefer lateral-thinking for non-obvious hypotheses or cross-domain mechanism transfer.

- Skill: `abpai/distill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add abpai/distill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abpai/distill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: abpai (https://skillmd.com/u/abpai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/abpai/distill

---


# Distill

Compress a complex system into the smallest useful set of abstractions that
still reconstructs its behavior.

Read `references/input-strategies.md` when starting on a codebase, research paper,
transcript, or article — it has input-type-specific starting heuristics.

## Core Concepts

**Primitives**: the irreducible building blocks that can't be decomposed further
without losing essential behavior. A good primitive set is:
- **Complete** — you can reconstruct the full system's behavior from just these pieces
- **Orthogonal** — each primitive captures something the others don't
- **Minimal** — removing any one primitive loses something essential
- Sized independently — don't force primitives to the same level of abstraction when
  one is genuinely bigger than the others
- Use as many primitives as reconstruction requires; treat a large set as a
  signal to try another compression pass, not an automatic failure.

**Distillation vs. summarization**: summarization preserves information at lower
fidelity. Distillation re-expresses the essence in a new, cleaner form, which is
often *more useful* than the original because it strips away accidental complexity.
For example, "uses PostgreSQL" is implementation; "needs durable ordered storage"
is essence.

**Accidental vs. essential complexity** (per Fred Brooks): essential complexity is
inherent to the problem. Accidental complexity comes from the implementation.
Distillation separates them.

## Workflow

Two phases, Orient and Compress, iterate until the user is satisfied with the
decomposition.

### Phase 1: Orient

Before proposing a decomposition, identify what the user needs to do with it and
which layer matters. Ask one question at a time only when the answer changes the
primitive set.

Skip straight to Phase 2 when the user's intent is already obvious from context or
for one-shot asks. Ask again only if the intended layer or use of the distillation
is unclear enough to change the primitive set.

### Phase 2: Compress

Each turn follows this pattern:

**Step 1 — Propose primitives.** Present a candidate decomposition (format depends
on context; see Output Formats), always including:
1. The primitive set — named, with a one-sentence description of each
2. Proposed granularity — how many primitives, and why this number
3. What was discarded as accidental complexity
4. Confidence flags — where you're least sure about the decomposition

**Step 2 — Invite pushback.** Ask the user to challenge the decomposition rather
than presenting it as final — surface where it might be wrong, not just whether it's
acceptable.

**Step 3 — Refine.** Based on feedback, propose a revised decomposition, showing
what changed and why. Repeat until the user says it feels right. For one-shot asks,
stop after a candidate decomposition that is complete, orthogonal, minimal, and
annotated with confidence flags.

### Convergence Signals

You're done when:
- The user confirms the primitive set matches their intuition
- Each primitive feels irreducible — you can't merge or remove any
- The user can explain the system to someone using only these primitives
- (For code) you could sketch a minimal implementation from just the primitive set

## Output Formats

Choose based on what the user needs; ask when in doubt.

- **Conceptual Map** (the default; use it for any input unless a format below is
  requested or its trigger fires) — primitives, relationships, reconstruction,
  discarded accidental complexity, and confidence flags.

- **Minimal Implementation** (only when requested or explicitly useful) — a set of
  files (like Karpathy's 3 files) that capture the essential behavior: actually
  runnable, named to reflect the primitives, stripped of accidental complexity,
  commented to map each piece back to the original.
- **Behavioral Spec** (when the user wants a SKILL.md or similar) — captures what
  the system *does* without prescribing *how*; useful when the distillation will
  guide an agent or a rewrite.
- **Hybrid** — combine formats for complex systems, e.g. a conceptual map plus a
  minimal implementation, or a behavioral spec with a reference implementation.
- **HTML Map** (only when requested, or spatial comparison is the deliverable) — a
  self-contained HTML artifact with primitive cards, relationship arrows,
  confidence flags, and a discarded-as-accidental section. Good fit for codebase
  maps, architecture primitives, research-paper concept graphs, and multi-document
  synthesis. Keep names and reconstruction concise enough to read in one pass.