# Distill

> Distill a trusted, durable source — a classic book, paper, codebase, docs set, transcript, or interview — into a reusable, invokable agent skill. Use when the user wants to turn a book/PDF/paper/repo/docs/transcript into a skill (book-to-skill, 书籍转 skill, 把资料变成 skill), wants to ground agent answers in a verified source instead of model priors, or wants the QBS method (Question to Book to Skill). Trigger on distill, source-to-skill, QBS, 蒸馏, 把书变成 skill, 资料转 skill, 经典来源, 用书解决问题. Does not download copyrighted material or automate z-library—acquisition stays user-side. Does not write the distilled method from the model's own memory; the method must come from the source.

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

---


# distill — Source to Skill

## Overview

The most reliable knowledge about a recurring problem usually already exists — in a book, paper, codebase, docs set, transcript, or interview. That knowledge is inert text, while the model answers from lossy, recency-biased priors. `distill` compiles **one trusted source** into **one reusable, invokable skill**, once, then reuses it forever.

It is the general form of the QBS method: **Question → Book → Skill** becomes **Need → Source → Skill** (see `references/recipes/qbs.md`).

## Stable Surface

```bash
distill <doctor|status|path|list|show|new|install|install-skill|uninstall-skill|selftest|help> [args]
```

Registry: `$DISTILL_HOME` (default `~/.distill`), one dir per skill: `<slug>/meta.json` + `<slug>/skill/`.

## Workflow

### 1. Need — name the capability, not the tool

- Restate the recurring job the skill must own in one sentence: trigger, input, and what "solved" looks like.
- One need = one skill = one source. Split multi-part needs.
- Do not scaffold until the source is chosen.

### 2. Source — pick a trusted, persistent source

- Choose the highest-trust source that survives time and names its own failure modes (see `references/source-selection.md`).
- Prefer a **primary, durable** source (original edition, canonical doc, actual code) over a summary of a summary.
- Acquisition is **user-side**: tell the user where to get it legally; never download or link infringing copies. `locator` records what was used.

### 3. Skill — distill the method

- Scaffold:
  ```bash
  distill new <slug> --need "..." --source "..." --source-type book \
    --author "..." --year 1994 --why "..." --locator /path/or/url
  ```
- Fill `skill/SKILL.md` by extracting the source's **method**, not a chapter summary. The skill must answer the step-1 need.
- Push detail into `skill/references/` (progressive disclosure); keep `SKILL.md` lean.
- Cite the source inside the generated skill.

### 4. Use — install and invoke

- `distill install <slug> --all` links the generated skill into agent skill dirs.
- Invoke the generated skill to answer the original need; cite the source.
- Improve by editing `<slug>/skill/` in place; never fork a `-v2`.

## Boundaries

- **Never** downloads, mirrors, or links copyrighted material; acquisition is user-side only.
- **Never** fabricates the method from the model's own memory; it must be traceable to the source.
- **Does not** write a generic summary. A chapter-by-chapter recap is a failure; an executable method is the goal.
- Registry state (`meta.json`) is written only by this CLI; do not hand-edit it to fake readiness.
- For multi-source distillation, create one skill per source and compose them at use time.

## Verification

- `distill new ...` prints the entry dir and a `skill/SKILL.md` skeleton.
- `distill list` shows the slug; `distill status` reports `ready: true`.
- `distill show <slug> --files` lists the generated skill tree.
- `distill install <slug> --all` links the skill into agent skill dirs.

## Failure Handling

| Symptom | Response |
|---------|----------|
| Need is vague or multiple needs | Split it; one skill per need. |
| No trustworthy source found | Stay on step 2; do not distill from priors. |
| User has no copy of the source | Recommend legal acquisition; never download. |
| Source is a summary/Derivative | Prefer the primary source it summarizes. |
| Generated skill = chapter recap | Redo it as a method + failure modes. |
| `distill install` refuses | Target exists; re-run with `--force` after confirming. |

## Resources

| File | When to read |
|------|----------------|
| `references/method.md` | Running a full distill loop end to end |
| `references/source-selection.md` | Choosing or judging a source |
| `references/recipes/qbs.md` | The book dialect, incl. the 30-year rule |
| `scripts/distill.py` | Registry / scaffold / install CLI (`distill selftest`) |