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

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:

  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

Resources