Loading
Converts books, documentation folders, and source collections (PDF, EPUB, DOCX, HTML, Markdown, RST, AsciiDoc, RTF, MOBI/AZW) into structured agent skills — extracting named frameworks, principles, te
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add alirezarezvani/claude-skills --skill book-to-skill -a cursor -y
Converts books, documentation folders, and source collections (PDF, EPUB, DOCX, HTML, Markdown, RST, AsciiDoc, RTF, MOBI/AZW) into structured agent skills — extracting named frameworks, principles, techniques, and anti-patterns into a master SKILL.md plus on-demand chapter files, a glossary, a patterns file, and a decision cheatsheet. Use when the user wants to study a document with an agent, apply an author's frameworks while working, turn internal docs or standards into a reusable knowledge base, or package a compiled book skill as a claude-skills plugin.
Converts books, documentation folders, and source collections (PDF, EPUB, DOCX, HTML, Markdown, RST, AsciiDoc, RTF, MOBI/AZW) into structured agent skills — extracting named frameworks, principles, techniques, and anti-patterns into a master SKILL.md plus on-demand chapter files, a glossary, a patterns file, and a decision cheatsheet. Use when the user wants to study a document with an agent, apply an author's frameworks while working, turn internal docs or standards into a reusable knowledge base, or package a compiled book skill as a claude-skills plugin.
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.
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.
| 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.
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.name and
description only — no allowed-tools, no model-invocation flags.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.
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" --skill-dir "$SKILLS_HOME/$SLUG" \
--dest ./engineering --source-note "<Title> by <Author>" --dry-run
Every path above is a real variable, not a placeholder: run the block as written (with
<paths> and $SLUG filled in) and it works end to end. Without --workdir the extractor
creates a private temp directory and prints it — capture that instead.
extract_document.py --check reports which extractors are installed and prints the install
command for what is missing. Every tool supports --help, --sample and --output json.
The full step-by-step procedure — what to ask at each step, the file templates, the
per-chapter budget matrix, and the update/fold-in workflow — is in
references/conversion_workflow.md. Read it before
running a conversion. Summary of the eleven steps:
| Step | Does |
|---|---|
| 0–1 | Scope check; resolve paths; detect an update/fold-in against an existing skill |
| 1.5 | Ask content type → BOOK_TYPE (technical vs. text), which picks the extractor |
| 2 | Extract → full_text.txt + metadata.json |
| 2.5 | Pre-flight cost estimate and worth-converting verdict — wait for approval |
| 2.6 | Over ~50k tokens, probe with grep/sed instead of reading the source |
| 3 | Analyze structure (title, author, chapters, themes). Mode 2 stops here. |
| 4 | Ask purpose → DEPTH (reference vs. study). Never ask a second budget question. |
| 5 | Skill name and destination root; offer update / overwrite / rename on a collision |
| 6–8 | Create the structure; write chapter files; write glossary, patterns, cheatsheet |
| 9 | Write the master SKILL.md — under 4,000 tokens, indexes intact |
| 9.5 | Validate. Errors block. |
| 10 | Clean up the workdir and report |
| 11 | Optionally package as a plugin, behind the rights gate |
| Rule | Means |
|---|---|
index.dead_link | The chapter index links a file that was never written |
index.topic_dangling | A topic points at a chapter that does not exist |
budget.over_cap on SKILL.md | Compaction will truncate the indexes — navigation is the first thing lost |
unicode.invisible | Extraction should have stripped this; investigate the source |
frontmatter.allowed_tools | The generated skill is trying to grant itself tool authority |
Safety-family warnings are deliberately broad — a source about prompt injection legitimately trips them. Read each in context; do not auto-silence them.
Walk these one at a time, with a recommended answer, before running a conversion.
"Is this source worth converting, or should I just read it?" Recommended: convert when it is > 3× the compiled skill's size and you will return to it. One-shot reads are cheaper unconverted. (Step 2.5 verdict.)
"Reference or study?" Recommended: reference, unless you intend to internalize the author's reasoning. Study depth roughly doubles generation cost and is only worth it with real worked examples. (Step 4.)
"Technical or text?" Recommended: technical only when tables, code, or formulas carry meaning. Docling costs ~1.5s/page; picking it for a prose book buys nothing. (Step 1.5.)
"What will you actually ask this skill?" Recommended: name three real questions before generating. They tell you what belongs in Core Frameworks and what the topic index must resolve. A skill nobody queries is a summary nobody reads.
"Do you have the right to redistribute this?" Recommended: assume not. Keep it local unless the source is public-domain, openly licensed, your organisation's own documentation, or you have written permission. (Step 11 rights gate.)
"Does this belong beside an existing skill?" Recommended: check for an existing compiled skill on the same subject first — folding new sources into one skill (Mode 4) beats two skills that half-cover a topic and give the agent no way to choose. (Step 0.)
references/conversion_workflow.md — the full procedure: Steps 0–11, the file
templates, the per-chapter budget matrix, and the update/fold-in workflowreferences/knowledge_extraction_canon.md — why structure beats summary; the extraction
taxonomy; what makes a framework survive compressionreferences/progressive_disclosure_budgets.md — where the token budgets come from and
what breaks when they are exceededreferences/document_extraction_pipeline.md — per-format extractor chains, fallbacks,
and the failure modes that produce silently bad textreferences/rights_and_provenance.md — copyright posture, the rights gate, and what
provenance a compiled skill must carryengineering/write-a-skill — authoring a skill from your own expertise. Use that when
the knowledge is in your head; use this when it is in a document.engineering/skill-security-auditor — full security audit of a skill package. Step 9.5
is the converter's own gate; the auditor is the repo-wide one.engineering/llm-wiki — an incrementally-grown, interlinked vault across many sources.
This skill compiles one bounded source set into one skill.Adapted from virgiliojr94/book-to-skill (MIT).
See ../../README.md for the full list of deviations.