Turn a book already in your Calibre library into an actionable agent skill by extracting its structure — not producing summaries. The calibre-mcp server supplies the chapter map and in-book search; the host agent (this LLM) does all synthesis.

Philosophy

Books contain crystallized expertise: frameworks, principles, and techniques that took years to develop. This skill extracts that knowledge into a format a compatible agent can leverage repeatedly.

Extract structure, not summaries. A skill isn't a book report. It's a toolkit of:

Named frameworks (mental models with clear application)
Actionable principles (rules that guide decisions)
Techniques (step-by-step methods)
Anti-patterns (what to avoid and why)
Voice calibration (how the author thinks and communicates)

Preserve the author's precision. "The 5 Whys" isn't interchangeable with "ask why multiple times." Capture the exact formulation.

Layer depth appropriately. Simple books → simple skills. Complex books with 10+ frameworks → skills with reference files and on-demand chapters.

Why calibre-mcp instead of a local extractor: the book is already in the library, so there's nothing to upload or clean up. In-book keyword + semantic search (RU/UK-aware, cross-lingual) lets you probe topics precisely instead of grepping a flat file, and the byproducts can flow back into the catalog (Step 9.5).

Modes of Operation

Route based on what the user asks:

1. Full Conversion (Default)

Trigger: A book reference (id / title / query) with no special instructions. Action: Run Steps 0–9. Output: Complete skill with SKILL.md, chapters/, glossary, patterns, cheatsheet.

2. Analyze Only

Trigger: "analyze", "just extract", "I want to review before generating". Action: Run Steps 0–3, produce an extraction report, then stop.

3. Generate from Prior Analysis

Trigger: User has existing analysis notes / previously ran analyze-only. Action: Skip Steps 0–3, run Steps 4–9 from the provided analysis.

4. Update / Fold-in — whole source (Existing Skill)

Trigger: An existing skill (folder or slug) plus a new book reference, no single topic named. Action: Steps 0–2, then the Update / Fold-in Workflow — merge the entire new book.

5. Targeted Fold-in — topic-scoped (Existing Skill) — calibre-only

Trigger: An existing skill plus a book reference plus an explicit topic/question (e.g. "supplement kafka-ops with what book 187 says about rebalancing"). Action: Locate the topic with in-book search, read only the matching chapters, merge that slice. See the Targeted Fold-in Workflow (§Mode 5). This is what a flat-file pipeline cannot do — it needs ranked, cross-lingual retrieval.

Synthesizing ONE topic across MULTIPLE books (≥3) into a new concept-keyed skill? That's a different artifact — use the sibling skill calibre-distill-topic, not a Mode here.

Skill Locations

This distiller can generate skills for multiple agent systems. For the generated skill, pick a destination the user's host agent can discover (see Step 5). Probe in order:

Claude Code personal: ~/.claude/skills/
GitHub Copilot CLI personal: ~/.copilot/skills/ → ~/.agents/skills/
Amp global: ~/.config/agents/skills/
Project-local: .claude/skills/ → .github/skills/ → .agents/skills/

When more than one valid root exists, ask the user once and remember the answer for the session — do not silently default.

This skill itself lives in the calibre-mcp repo (skills/calibre-distill/). Install it by copying or symlinking to ~/.claude/skills/calibre-distill/. Note: the calibre-mcp MCPB bundle cannot ship skills — install the skill separately from the MCP server.

Step 0 — Out-of-scope check

If no book reference is provided, stop:

"calibre-distill needs a book — give me an id, title, or search query, plus an optional skill slug. Example: calibre-distill 187 kafka-ops or calibre-distill "AI Engineering"."

Requires the calibre-mcp server connected. If its tools aren't available, say so and stop. Parse the input into the book reference and an optional SKILL_NAME slug (lowercase hyphens). If the reference / slug matches an existing skill in a skills root, or the user asks to update, flag this run as Mode 4/5 (Fold-in).

Step 1 — Resolve the book

Resolve the reference to a single Calibre book with calibre_search:

Numeric id → confirm via calibre_get_book (title/authors).
Title / query → calibre_search; if it returns more than one plausible match, list the top hits (id, title, author) and ask which one — never guess.
No match → stop with the query echoed back.

Record BOOK_ID, title, authors, and available formats. Prefer EPUB, else PDF (scanned PDFs yield no text — Calibre has no OCR; if calibre_get_content reports an image PDF, tell the user this book can't be distilled).

Also record the ISBN-13 — the stable, cross-machine key the artifact binds to (the L4 back-link / bibliography). If library metadata has none and writes are enabled, backfill it once with calibre_extract_isbn(id=BOOK_ID, apply=true) — an offline scan of the book's own front matter / back cover for a checksum-valid ISBN. If it finds nothing, or writes are off, leave ISBN as "—" and rely on the title:"…" AND authors:"…" fallback key. (E2)

Step 1.5 — Identify content type

Ask the user, pre-suggesting from library metadata (tags / format):

"Is this book technical (code, tables, formulas — e.g. programming, papers) or text-heavy (mostly prose — management, narrative non-fiction)? Based on its tags/format I'd guess <technical|text> — confirm or correct."

Pre-suggest technical when tags include programming/engineering-ish terms or the format is a code-dense PDF; else text. Store as BOOK_TYPE ∈ {technical, text}. (This mirrors the reverse-direction win in Step 9.5: metadata helps the distill before the distill helps the metadata.)

Step 2 — Get the chapter map

Call calibre_get_content with structure=true:

calibre_get_content(id=<BOOK_ID>, structure=true)

Returns structuredContent:

chapters: [{ n, heading, startChar, endChar, approxTokens, cursor }] — each cursor seeks straight to that chapter's start in a follow-up calibre_get_content call.
hasToc, detector (pdf-outline | numeric | structural | none), totalChars, format, backend. pdf-outline = the PDF's own bookmarks; its n is a running number, not the printed chapter number.

If detector = none / chapters = [], the book has no machine-detectable headings — walk it with plain calibre_get_content cursor pages (no structure) and infer sections from the text, or treat the whole book as one section for a thin doc.

No files are created and nothing is cached on your side — the server holds the extracted text in its own sha256 LRU cache, so re-runs and later chapter reads are fast.

Step 2.5 — Pre-flight cost estimate

From the chapter map present an estimate before generating anything:

📖 Book: <Title> — <Author>   (id <BOOK_ID>, <format> via <backend>)
📄 Chapters: <N> (<detector>) | ToC: <yes/no> | Total: ~<totalChars/4/1000>K tokens

💰 Estimated token cost (Full Conversion / Update):
   Input  (chapter reads + prompts): ~<N>K tokens
   Output (skill files):             ~<N>K tokens
   Total:                            ~<N>K tokens
   ⏱  ~<N> minutes

📁 To generate: SKILL.md + <N> chapter files + glossary + patterns + cheatsheet

➡  Proceed? (or "analyze only" to preview first)

How to estimate:

Token total ≈ totalChars / 4. Per-chapter tokens ≈ approxTokens from the map.
Input ≈ Σ chapter tokens × 1.3 (prompt overhead per pass).
Output ≈ chapters × per-chapter budget (Step 7 matrix) + 4,000 (SKILL.md) + 4,500 (glossary + patterns + cheatsheet).
Prices (as of 2026): Claude Sonnet input=$3/MTok output=$15/MTok — Haiku input=$0.80/MTok output=$4/MTok. Quote Sonnet and Haiku lines.

Wait for confirmation. "analyze only" → Mode 2.

Step 2.6 — Targeted in-book access (don't dump the whole book)

Never load the whole book into context — you have precise probes. Treat the book as a queryable corpus:

Read one chapter: calibre_get_content(id=<BOOK_ID>, cursor=<chapter.cursor>, maxChars=<budget>) — pages from the chapter start; follow nextCursor if a chapter spans more than one page (stop at the next chapter's startChar).
Find a concept / where a topic lives: calibre_semantic_search(scope=book, bookId=<BOOK_ID>, query="<concept>") → ranked passages with char offsets; map each hit's offset to a chapter via the Step 2 map. Cross-lingual and RU/UK-aware.
Exact term / verify a framework is really in the book: calibre_search(scope=book, id=<BOOK_ID>, query="<exact phrase>") (FTS) — use the hit count as the "is this actually mentioned?" check before you claim it in SKILL.md.

Use these for Step 3 (structure), Step 7 (per-chapter reads), and Step 8 (glossary/patterns extraction). Reading only the slices you need keeps generation cost proportional to output, not to book size. Semantic search needs the book indexed (calibre_build_index bookId=…); if it's not indexed, either build the index or fall back to FTS (calibre_search) — say which you used.

Step 3 — Analyze book structure

Using the chapter map (Step 2) plus a read of the first chapter / front matter, identify:

Book title and author(s) (already known from Step 1 — reconcile).
Chapter structure — the map gives you this directly; skim the ToC region if hasToc.
Core themes and subject domain.

If Mode 2 (Analyze Only): produce the extraction report now and stop:

## Extraction Report — <Title>

### Author's Core Frameworks
- **<Framework Name>**: <what it is and when to apply>

### Key Principles
- <Principle>: <actionable rule>

### Techniques & Methods
- <Technique>: <step-by-step or how-to>

### Anti-patterns
- <What to avoid>: <why>

### Suggested Skill Name
`{author-lastname}-{core-concept}` — e.g. `huyen-ai-engineering`

### Chapters Detected
| # | Title | Main Frameworks |

Step 4 — Ask purpose (Full Conversion only)

"What should this skill help you do? (Pick one or more)

Apply the author's frameworks while working

Think with the author's mental models

Reference specific chapters and concepts

All of the above"

Derive DEPTH (no extra prompt):

Answer is only option 3 → DEPTH=reference — lean, fast-lookup chapters.
Answer includes 1, 2, or 4 → DEPTH=study — deeper chapters with worked detail.

DEPTH + BOOK_TYPE set the per-chapter budget in Step 7. (Modes 2/3 default DEPTH=study.)

Step 5 — Determine skill name and destination

If SKILL_NAME was given, use it. Otherwise propose two and let the user choose:

By author-concept: {author-lastname}-{core-concept} (e.g. huyen-ai-engineering)
By title: lowercase-hyphen title (e.g. designing-data-intensive-apps)

Default to author-concept when the book has a strong methodological identity.

Choose the destination skill root (SKILLS_HOME) by the host the user is running in (see Skill Locations). If exactly one candidate root exists, use it; if none, ask which to create; if the user asked for project-local, prefer that. Check whether $SKILLS_HOME/<skill_name>/ already exists → if so, offer Update/Fold-in (Mode 4/5), Overwrite, or Rename.

Step 6 — Create skill directory structure

mkdir -p "$SKILLS_HOME/<skill_name>/chapters"

Step 7 — Generate chapter summaries

TOKEN BUDGET RULE — CRITICAL (adaptive):

	`DEPTH=reference`	`DEPTH=study`
`BOOK_TYPE=text`	800–1,200 tokens	1,000–1,800 tokens
`BOOK_TYPE=technical`	1,200–1,800 tokens	2,000–3,000 tokens

Per-file targets, not hard caps. Density beats length (Quality Rule #3) — never pad.
Chapter files load on-demand, so a bigger chapter only costs tokens when read.
Between two cells, use the lower budget; depth comes from precision, not volume.

DEPTH=study is earned with content, not a bigger number. To reach the study budget honestly a chapter must add concrete material:

Reconstruct one worked example on a FRESH scenario under a ## Worked Example section — the single biggest lever and the main thing a learner returns for.
Expand the "How" of each framework into explicit steps or criteria.
Add a short "Why it works / failure mode" note to the top 1–2 frameworks.

If a chapter genuinely has no worked example, let it land below the study floor and note it is thin — don't pad. A reference chapter deliberately omits worked examples.

For EACH chapter in the Step 2 map: read it via its cursor (Step 2.6), then create $SKILLS_HOME/<skill_name>/chapters/ch<NN>-<slug>.md. The # Chapter N: title should be a concise paraphrase of the chapter's subject, not the book's verbatim heading (the verbatim heading may appear only in the L4 footer metadata).

Adapt emphasis by BOOK_TYPE: technical → prioritize Code Examples, Reference Tables, Commands & APIs; API/config identifiers and syntax rules are facts and stay exact, but the author's own example code / tables get re-authored, not copied (see the sections below). text → prioritize Frameworks, Mental Models, Key Takeaways; skip empty technical sections.

# Chapter N: <paraphrased subject — not the book's verbatim heading>

## Core Idea
<1–2 sentences: the single most important thing this chapter teaches>

## Frameworks Introduced
- **<Framework Name>**: <exact formulation — preserve the author's naming>
  - When to use: <specific situation>
  - How: <steps or criteria>

## Key Concepts
- **<Term>**: <precise definition in 1 sentence>
(5–10 most important terms)

## Mental Models
<2–4 thinking tools. Write as "Use X when Y" or "Think of X as Y">

## Anti-patterns
- **<What to avoid>**: <why it fails>

## Code Examples *(technical books only — omit if BOOK_TYPE=text)*
<!-- Re-author a minimal example that demonstrates the same technique — fresh variable
     names, a fresh scenario. API/config identifiers and syntax rules are facts and stay
     exact; the author's example code does NOT get copied verbatim. -->
```<language>
<a re-authored minimal example demonstrating this chapter's technique>

What it demonstrates:

Reference Tables (technical books only — omit if BOOK_TYPE=text)

Worked Example (DEPTH=study only — omit for DEPTH=reference)

Key Takeaways

(3–7 takeaways a practitioner must remember)

Connects To

Ch N:
:


---

## Step 8 — Generate supporting files

### glossary.md
`$SKILLS_HOME/<skill_name>/glossary.md` — every significant term, alphabetized. Format:
`**Term** — definition (Ch N)`. Max 1,500 tokens. Use `calibre_search scope=book` to
confirm a term's usage/chapter before listing it.

### patterns.md
`$SKILLS_HOME/<skill_name>/patterns.md` — all concrete techniques/patterns/algorithms.
Format: `## Pattern Name` / `**When to use**` / `**How**` / `**Trade-offs**`. Max 2,000 tokens.

### cheatsheet.md
`$SKILLS_HOME/<skill_name>/cheatsheet.md` — **the most differentiated layer; a reasoning
aid, not a keyword list.** It captures the author's *judgment*. Prioritize, in order:
1. **Decision rules** — "When X, do Y, because Z."
2. **Decision trees / flowcharts** (nested bullets or a small table) for >2-branch choices.
3. **Trade-off matrices** — options scored on the author's dimensions.
4. **Thresholds & defaults** — the specific numbers / rules of thumb the author commits to.
5. **Tells & smells** — fast heuristics for recognizing a situation.

Avoid bare term→definition rows (glossary) and prose paragraphs (chapters). Every line
helps the reader *decide* something. Compact tables + decision rules. Max 1,200 tokens.

---

## Step 9 — Generate the master SKILL.md

**CRITICAL TOKEN BUDGET: keep the SKILL.md body under 4,000 tokens.** Compaction truncates
from the END — put the most important content FIRST.

```markdown
---
name: <skill_name>
description: "Knowledge base from \"<Full Title>\" by <Author(s)>. Use when applying <author>'s frameworks for <3–6 key topics>, studying the book, or referencing its concepts."
---

<!-- argument-hint: [topic, framework name, or chapter number] -->

# <Full Title>
**Author**: <Author(s)> | **Chapters**: <N> | **Calibre id**: <BOOK_ID> | **Generated**: <YYYY-MM-DD>

## Attribution
<!-- Mandatory. Fill from library metadata (Step 1); ISBN may be backfilled via calibre_extract_isbn (Step 1). Leave "—" only if truly absent. -->
- **Title**: <Full Title>
- **Author(s)**: <Author(s)>
- **Publisher**: <Publisher>
- **ISBN**: <ISBN-13>
- This is a lossy, transformative study aid — **buy the book for the full treatment**.

## How to Use This Skill
- **Without arguments** — load core frameworks for reference
- **With a topic** — ask about an indexed topic; I read the relevant chapter
- **With chapter** — ask for `ch05`; I load that chapter
- **Browse** — ask "what chapters do you have?"

## Core Frameworks & Mental Models
<!-- ~2,000 tokens: the author's most important named frameworks and principles.
     Preserve exact names. Write as "Use X when Y", "Prefer X over Y because Z". -->

## Chapter Index
| # | Title | Key Frameworks |
|---|-------|----------------|
| [ch01](chapters/ch01-<slug>.md) | <Title> | <framework1>, <framework2> |
...

## Topic Index
<!-- Alphabetical. Major terms/frameworks → chapter(s). This is how the agent navigates. -->
- **<Term>** → ch<N>[, ch<N>]

## Supporting Files
- [glossary.md](glossary.md) — key terms
- [patterns.md](patterns.md) — techniques & patterns
- [cheatsheet.md](cheatsheet.md) — decision rules & quick reference

## Scope & Limits
This skill covers the book content only. Source: Calibre book <BOOK_ID>. For topics beyond
this book, check related skills or ask the agent directly.

Step 9.5 — Library write-back (optional, opt-in) — calibre-only

Distillation byproducts can flow back into the catalog so it starts answering topic queries without the semantic index, and raw-metadata books get enriched as a side effect of being studied. This is a separate, opt-in, final step — the core distill above writes nothing to Calibre.

Requires the write gate on (CALIBRE_MCP_ENABLE_WRITE=1). If the write tools are absent, report "skipping library stamping (writes disabled)" and finish normally.

Artifact	Destination	Mechanics
Topic-Index topics (~5–12, not every glossary term)	`tags` (+ marker tag `distilled`)	`calibre_update_book`; read → union → write (set_metadata replaces the whole field, so merge first — same pattern as `calibre_extract_isbn` identifiers)
Compact distill note (date + skill slug + core framework names, a few lines)	`comments` (append a delimited block)	human-visible in the GUI, agent-visible via `calibre_get_book`
Full glossary / machine artifacts	a `#custom` column (e.g. `#distill`), only if it already exists	probe first; degrade with a note if absent — never auto-create columns

Rules:

Preview-first: show the proposed tag/comment diff and ask before applying. Never stamp silently.
Idempotent re-runs: on fold-in (Mode 4/5) replace the distill note block and re-union tags — no duplicate blocks, no tag churn.
Cap tag spam: stamp only Topic-Index-level topics.

Payoff: calibre_search "tags:exactly-once" now finds the book; the book-surface work feeds the catalog surface.

Step 10 — Report

Nothing to clean up (no temp files — the server owns its cache). Report:

✅ Skill created: $SKILLS_HOME/<skill_name>/

📚 Book: <Full Title> — <Author>   (Calibre id <BOOK_ID>)
📄 Chapters: <N>

Files generated:
  SKILL.md         — core frameworks + index   (~X tokens)
  chapters/        — <N> chapter summaries     (~X total)
  glossary.md      — key terms                 (~X tokens)
  patterns.md      — techniques & patterns     (~X tokens)
  cheatsheet.md    — decision rules            (~X tokens)
  Total (on-demand): ~X tokens

Usage:
  Ask for <skill_name>                → load core frameworks
  Ask <skill_name> about <topic>      → find and explain a topic
  Ask <skill_name> for ch<N>          → dive into a chapter
  (Reload: Claude Code — restart the session.)

If Step 9.5 ran, add a line: 🏷 Library: stamped <k> tags + distill note on book <BOOK_ID>.

Update / Fold-in Workflow (Mode 4 — whole source)

When updating an existing skill at $SKILLS_HOME/<skill_name>/ with an entire new book:

1. Read Existing Skill Structure

Parse SKILL.md (Chapter Index, Topic Index, metadata, Core Frameworks); list chapters/ to find the highest chapter number; read glossary.md, patterns.md, cheatsheet.md for what's already indexed.

2. Match Content & Identify Revisions vs. Additions

Get the new book's chapter map (Step 2) and probe topics (Step 2.6) to decide, per section:

Revision — updates an existing chapter's topic → merge into that chapter file.
Addition — new material → new chapter files, numbered after the highest existing one.

3. Generate or Update Chapter Files

For each new/revised chapter, read the source slice (via cursors) and follow Step 7.

4. Merge Supporting Files

glossary.md — combine + alphabetize; if a term exists, append the new chapter/source ref (**Term** — definition (Ch 4, Ch 13)).
patterns.md — append new patterns, keep under ~2,500 tokens.
cheatsheet.md — integrate new decision rules / tables cleanly.

5. Re-generate SKILL.md

Increment chapter count, update Generated date, add source; fold high-impact frameworks into Core (keep under 4,000 tokens); append to Chapter Index; merge Topic Index alphabetically (append new chapter links to existing topic lines).

6. Report (and optional Step 9.5)

Print a custom update report — new chapters, merged glossary terms, updated indices. Offer Step 9.5 write-back for the new topics.

Targeted Fold-in Workflow (Mode 5 — topic-scoped) — calibre-only

Their Mode 4 always merges the whole new source. This variant merges only what a book says about one topic — impossible for a flat-file pipeline (no ranked, cross-lingual retrieval).

Trigger: existing skill + book ref + an explicit topic/question.

Resolve the book (Step 1) and get its chapter map (Step 2).
Locate the topic: calibre_semantic_search(scope=book, bookId=<id>, query="<topic>") (+ calibre_search scope=book for exact terms). Map hit offsets → chapters via the map. Read only those chapters through their cursors. Nothing else from the book enters context.
Merge, scoped: revise the matching chapter file(s) or add one new chapter/section for the topic; fold only topic-relevant terms into the glossary (with the new source ref), topic-relevant rules into the cheatsheet; append the new chapter to the topic's line in the Topic Index. Do not renumber or rewrite unrelated files.
Report what was merged and from which chapters (provenance line in the updated chapter: source book + chapter heading).

Guardrail: if calibre_semantic_search returns lowConfidence, say so and ask before merging — don't fold in weak matches silently.

Quality Rules

Extract structure, not summaries — named frameworks, exact formulations, anti-patterns; not chapter recaps.
Preserve the author's precision — "The 5 Whys" ≠ "ask why multiple times".
Density over completeness — a 1,000-token summary beats a 10,000-token excerpt.
Practitioner voice — write "Use X when Y", not "The book explains X".
Front-load SKILL.md — compaction keeps the first ~5,000 tokens; most important first.
Chapter files are on-demand — they don't count against skill budget until loaded.
Never copy raw book text — always synthesize (also respects the source's license). Verbatim quoting is capped: max 25 words per quote, max 200 quoted words total per skill, non-contiguous, and every quote is always attributed to the source.
Topic index is critical — it's how the agent navigates to the right chapter file.
Verify before you claim — use calibre_search scope=book to confirm a framework is really in the book before naming it.

calibre-distill

Calibre Distill