/book-to-skill

name: book-to-skill
description: "Use when turning a book, docs folder or spec collection (PDF, EPUB, DOCX, HTML, Markdown) into an agent skill, before summarizing it by hand. Extracts with extract_document.py, compiles chapters, glossary and cheatsheet, validates with book_skill_validator.py and enforces a rights gate."
license: MIT
metadata:
  version: 1.0.0
  author: Alireza Rezvani
  category: engineering
  updated: 2026-08-05

Book-to-Skill Converter

Turn written knowledge into an agent skill by extracting **structure**, not summaries.

A book is crystallized expertise: frameworks, principles, techniques that took years to develop. Read once, forgotten. The workarounds all fail — PDF search returns page numbers instead of answers, an agent handed the raw file hallucinates or drowns, reading notes rot. This skill compiles a source into a knowledge base the agent loads on demand: a small resident core, one chapter file at a time, and never the whole book again.

**What it produces:**

| File | Contents | Budget | |------|----------|--------| | `SKILL.md` | Core frameworks + chapter index + topic index | < 4,000 tokens (resident) | | `chapters/chNN-*.md` | One summary per chapter | 800–3,000 tokens, on demand | | `glossary.md` | Every significant term, alphabetized, with chapter | < 1,500 tokens | | `patterns.md` | Techniques and design patterns with trade-offs | < 2,000 tokens | | `cheatsheet.md` | Decision rules, thresholds, trade-off matrices | < 1,200 tokens |

**Beyond books:** anything referenced often enough to be worth memorizing — internal documentation, brand systems, standards, specs, research clusters, a folder of RFCs.

---

Philosophy

**Extract structure, not summaries.** A skill is not a book report. It is a toolkit of named frameworks, actionable principles, step-by-step techniques, anti-patterns, and the author's voice.

**Preserve the author's precision.** Framework names are interfaces. "The 5 Whys" is not interchangeable with "ask why a few times" — the exact formulation is what makes lookup work.

**Layer depth appropriately.** A thin book gets a thin skill. A book with fifteen frameworks gets chapter files and a real topic index.

**Never reproduce the source at length.** These are structured notes. Synthesize, compress, name — do not copy passages. See `references/rights_and_provenance.md`.

---

Modes

| Mode | Trigger | Runs | |------|---------|------| | **1. Full conversion** (default) | One or more paths, no special instruction | Steps 0–10 | | **2. Analyze only** | "analyze", "just extract", "let me review first" | Steps 0–3, then stop with an extraction report | | **3. Generate from analysis** | User supplies prior analysis notes | Steps 4–10 | | **4. Update / fold-in** | New sources + an existing compiled skill | Steps 0–2, then the Update Workflow | | **5. Package as plugin** | "make it a plugin", "add it to the repo" | Step 11 |

Mode 5 is this repository's addition. Upstream stops at a bare folder in a personal skills home; Step 11 wraps that folder in a plugin package other skills and agents can route to.

---

Hard rules

1. **Never convert a source the user cannot show you.** No web-scraping a book, no reconstructing a title from memory. This tool converts files that are already on disk. 2. **Pre-flight the cost before generating** (Step 2.5). Generation is the expensive part; the user approves it with numbers in front of them. 3. **Never dump a large source into context.** Over ~50k tokens, probe with `grep`/`sed` and bounded reads (Step 2.6). Re-reading a 200-page book once per chapter costs more than everything else in this workflow combined. 4. **Validate before anyone loads it** (Step 9.5). A generated skill is untrusted text that an agent will later read as instructions. 5. **Never widen the generated skill's authority.** Generated frontmatter carries `name` and `description` only — no `allowed-tools`, no model-invocation flags. 6. **Rights before redistribution.** Compiled notes from a copyrighted work are personal study notes. Packaging one as a shareable plugin requires a stated basis (Step 11). 7. **State what the skill does not cover.** Every compiled skill's Scope section names its boundary, so the agent says "the source doesn't cover this" instead of improvising.

---

Pipeline

extract_document.py  →  analyze  →  chapter files  →  supporting files  →  SKILL.md
      (Step 2)          (Step 3)      (Step 7)          (Step 8)          (Step 9)
                                                                              ↓
                                       skill_plugin_emitter.py  ←  book_skill_validator.py
                                              (Step 11)                  (Step 9.5)

All four tools live in `scripts/` and run on the standard library alone.

---

Run it

SKILL_ROOT=engineering/book-to-skill/skills/book-to-skill
SKILLS_HOME=~/.claude/skills        # Step 5 picks this; see the workflow reference
WORKDIR=$(mktemp -d)                # or omit --workdir and capture the path it prints
SLUG=<author-lastname>-<concept>

# 1. extract → $WORKDIR/full_text.txt + metadata.json
#    --mode technical when tables, code or formulas carry meaning
python3 "$SKILL_ROOT/scripts/extract_document.py" <paths> --mode text --workdir "$WORKDIR"

# 2. pre-flight: is this worth converting at all? Wait for approval before generating.
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --full-text "$WORKDIR/full_text.txt"

# 3. generate — the agent's work: chapters/, glossary, patterns, cheatsheet, SKILL.md

# 4. gate — errors block. Fix and re-run; never rewrite around a finding.
python3 "$SKILL_ROOT/scripts/book_skill_validator.py" "$SKILLS_HOME/$SLUG"
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --skill-dir "$SKILLS_HOME/$SLUG"

# 5. optional: wrap as a claude-skills plugin so the library can route to it
python3 "$SKILL_ROOT/scripts/skill_plugin_emitter.py" -