book-to-skill: Turn a Technical Book Into a Claude Code Skill, Not a Summary
book-to-skill is an MIT-licensed tool that distills a technical book, doc folder, or paper stack into a structured Agent Skill (SKILL.md plus per-chapter files) for Claude Code, GitHub Copilot CLI, or Amp — loading only the chapter you need instead of dumping the whole book into context.
- ⭐ 15259
- Python
- MIT
- Updated 2026-08-03
Claude Code Skill Authoring Guide • k-skill: 100+ Skills That Turn Any AI Agent Into a Korea Local
What Is book-to-skill? #
book-to-skill turns a technical book, document folder, or paper stack into a unified Agent Skill — ready to study, reference, and use while you work in GitHub Copilot CLI, Amp, or Claude Code. The core idea, in the project’s own words: “You buy a great technical book. You read it once. Three months later you can’t remember chapter 7 existed.” Instead of hoping the agent has hallucination-free knowledge of the book, or re-searching a PDF every time, book-to-skill pre-extracts the book’s structure once and lets the agent load exactly the chapter it needs, on demand.
🔗 GitHub: https://github.com/virgiliojr94/book-to-skill
MIT licensed, at 15,200+ GitHub stars, with a commit from July 31, 2026, built on the open Agent Skills standard that Copilot CLI, Amp, and Claude Code all share (SKILL.md format) — so a skill generated once works across any of those three hosts.
How It Works: 3 Steps #
- Point it at a file, folder, or glob —
/book-to-skill ./my-book.pdf - It distills the book into a skill — mental models, decision rules, anti-patterns, and per-chapter files. Structure, not a summary.
- Your agent loads it on demand — ask
/my-book replicationand it reads the right chapter and answers from the real content.
What Gets Generated #
Running /book-to-skill your-book.pdf creates a full skill in your agent’s skills directory (~/.claude/skills/<slug>/ for Claude Code, ~/.copilot/skills/<slug>/ for Copilot CLI, ~/.agents/skills/<slug>/ for Amp or cross-agent use):
| File | Purpose | Size |
|---|---|---|
SKILL.md | Core mental models + chapter index | ~4,000 tokens |
chapters/ch01-*.md … | One file per chapter, loaded on-demand | ~1,000 tokens each |
glossary.md | Every key term, alphabetically sorted with chapter refs | ~1,500 tokens |
patterns.md | All techniques, algorithms, and design patterns | ~2,000 tokens |
cheatsheet.md | Decision tables and quick-reference rules | ~1,000 tokens |
Chapter files don’t count against the skill’s token budget until you actually ask about that topic.
Usage #
/book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]
# Process several files together into a unified skill
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research
# Process a whole folder
/book-to-skill ~/workspace/project-docs/ project-knowledge
# Process files matching a glob
/book-to-skill "~/books/*.epub" my-library
# Fold new material into an existing skill
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge
Once generated, you use it like any skill:
/designing-data-intensive-apps # load core mental models
/designing-data-intensive-apps replication # find and explain a topic
/designing-data-intensive-apps ch05 # dive into chapter 5
Supported formats: PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3. For PDFs, python3 scripts/extract.py --check reports which extractor (pdftotext, pypdf, pdfminer.six, or docling) is installed for every format and what to install if something’s missing — and the tool auto-picks between “text-heavy” and “technical” (code/tables/formulas) extraction depending on the book.
Beyond Books #
The name says “book,” but the extraction works on any structured prose you re-read often:
- Internal documentation — ADRs, runbooks, onboarding guides folded into one queryable skill
- Brand & design systems — voice guidelines and component principles instead of skimming a 60-page PDF
- Research clusters — a stack of papers plus your own notes, merged and updatable as new material lands
- Specs & standards — RFCs, API contracts, compliance docs you reference but never memorize
The project’s own heuristic: if you re-open a document often enough to wish you’d memorized it, it’s a candidate.
The Discovery Loop Tax: Measured, Not Asserted #
A PDF-reading agent doesn’t just read — it navigates: fetching a table of contents, pulling more pages when it hits an unfamiliar term, backtracking. Every hop lands in conversation history and gets re-processed on every subsequent turn, forcing a sub-agent to compress what it read into a summary the main agent can’t fact-check against the source.
book-to-skill pays that navigation cost once, at generation time. The README publishes a reproducible measurement (tools/discovery_tax.py) across three real books:
| Book (size) | Context-dump | Discovery loop | book-to-skill | vs. dump / loop |
|---|---|---|---|---|
| Think Python 2 (119K tokens) | 119,264 | 12,152 | ~5,000 | 24× / 2.4× |
| Working Backwards (175K tokens) | 175,253 | 33,444 | ~5,000 | 35× / 6.7× |
| AI Engineering (256K tokens) | 256,287 | 77,866 | ~5,000 | 51× / 15.6× |
Honest caveats the project states itself: the discovery-loop figures are a one-time cost and a model using the book’s real chapter structure — a well-tuned agent might land nearer the best case. The context-dump cost, by contrast, recurs on every turn. The extraction also needs recognizable chapter headings to segment cleanly (it detects Arabic, Roman, CJK, Korean, Thai, and several European heading forms) — a titles-only book may not segment well. For a single one-off read, the project itself says a plain PDF agent is fine; book-to-skill wins when you return to the material repeatedly.
“Isn’t This Just RAG?” — The Project’s Own Answer #
The FAQ addresses this head-on: raw text injection (whether pasted or retrieved via RAG chunks) is retrieval — the model searches for keyword/semantic matches in unstructured text. A book-to-skill chapter file is reasoning material — pre-extracted named frameworks, principles, and decision rules structured for application, not for search. The distinction matters most for technical books where the value is in the mental model, not in locating a specific sentence.
book-to-skill vs. Alternatives #
| Approach | Token cost per question | Fact-checkable against source | Setup |
|---|---|---|---|
| Paste whole book into context | Full book, every turn | Yes, but expensive | None |
| Agent searches the PDF live (discovery loop) | 2.4×-15.6× more than book-to-skill | Yes | None |
| book-to-skill | ~5,000 tokens (core + 1 chapter) | Yes — full source stays on disk | One-time generation |
| Generic RAG over chunked PDF | Varies, chunk-dependent | Partial — depends on chunk boundaries | Vector DB + embedding pipeline |
Use Cases #
1. Technical Reference You Actually Query #
Load /designing-data-intensive-apps replication mid-project instead of trying to remember which chapter covered it, or re-reading the whole book.
2. Turning a docs/ Folder Into a Queryable Skill #
Point book-to-skill at an internal documentation folder once, then ask the resulting skill questions while coding instead of grepping through Markdown files by hand.
3. Merging a Research Paper Stack #
Combine several related papers plus your own notes into one unified skill, updating it as new papers land via the fold-in usage pattern.
4. Onboarding Material That Doesn’t Go Stale in a Chat Log #
A brand guideline or architecture-decision skill that any team member’s agent can query, instead of a Slack thread nobody can find six months later.
Related Repositories #
| Repository | Purpose |
|---|---|
| Agent Skills standard | The open SKILL.md format book-to-skill outputs, shared across Copilot CLI, Amp, and Claude Code |
Related Articles #
- Claude Code Skill Authoring Guide — for writing Agent Skills by hand, versus generating one automatically from a document
- k-skill: 100+ Skills That Turn Any AI Agent Into a Korea Local — another large-scale Agent Skills project, service-integration skills rather than document-distillation skills
Conclusion #
book-to-skill makes a specific, well-argued bet: for knowledge you return to repeatedly, pre-extracting structure once beats both dumping raw text into context and letting an agent rediscover the same table of contents every session. The measured (not just claimed) 24×-51× token reduction, the honest caveats about when it doesn’t help, and the direct FAQ answers to the obvious “why not just use a big context window” objection all suggest a maintainer who’s thought carefully about the failure modes rather than just shipping a demo. Support across Claude Code, GitHub Copilot CLI, and Amp via the shared Agent Skills standard means the generated skill isn’t locked to one vendor either.
Best for: Anyone who owns technical books, internal docs, or paper stacks they reference constantly but can never quite remember the details of — not a one-off PDF question, which a plain agent already handles fine.
GitHub: https://github.com/virgiliojr94/book-to-skill
Last updated: 2026-08-03
💬 Discussion