Reading a good technical book once and actually retaining it three months later, right when you need it, is a genuinely common failure. book-to-skill is built around a narrow, practical fix: point it at a technical book, document folder, or paper stack you already have legitimate access to, and it converts that material into a structured Agent Skill your coding agent can load on demand — so asking about a specific chapter gets an answer grounded in the actual content, instead of an agent hallucinating or admitting it has no idea what's in the book.
Structure, Not a Summary
The three-step pitch is deliberately plain: point the tool at a file, folder, or glob; it distills the source into frameworks, decision rules, anti-patterns, and per-chapter files rather than a flattened summary; your agent then loads the relevant piece on demand when you actually ask about it. That last part is the meaningful design decision — a generated skill isn't one giant document dumped into context. It's SKILL.md (core mental models plus a chapter index, roughly 4,000 tokens), individual chapter files loaded only when a specific topic comes up, a glossary, a patterns file, and a cheatsheet of decision tables. Chapter files specifically don't count against the skill's token budget until you actually ask about that chapter — the structure is built around selective retrieval, not front-loading everything.
The Actual Numbers Behind "Fewer Tokens"
The project claims 24×–51× fewer tokens than dumping a whole book into context to answer one question, and it backs that with a documented measurement methodology rather than leaving it as an unverifiable marketing number — worth checking directly if the efficiency claim matters for your evaluation, the same way you'd want to see methodology behind any vendor-published benchmark. The practical case for this over "just paste the whole PDF into the chat" is straightforward: a full technical book is often hundreds of thousands of tokens, most of which is irrelevant to any single question you're actually asking — the "discovery loop tax" of scanning the whole thing every time compounds badly across repeated queries.
Fair Use Is a First-Class Design Constraint, Not an Afterthought
This is the part worth reading directly rather than skimming, because the project handles it more carefully than most tools that touch copyrighted source material. The README states plainly that the tool ships no book content — it's a converter you point at files you already own, processing runs locally rather than uploading your files anywhere, and the generated output is explicitly designed to never copy raw passages from the source, framed instead as structured, synthesized notes — mental models, definitions, and takeaways, the same category as detailed handwritten study notes. The project is equally direct about the boundary that matters most: don't redistribute a generated skill built from a copyrighted work, since publishing or sharing it can infringe the rights holder, and third-party book skills should stay private, while internal docs, your own writing, and openly-licensed material are fine to share within their own license terms.
That's a genuinely different posture than a tool that treats copyright as someone else's problem — it's baked into a specific quality rule in the extraction process itself (never copy raw passages) rather than left as a disclaimer nobody reads.
What's Actually Doing the Extraction
The tool splits into two halves: a deterministic Python extractor that turns a source document into clean text and metadata, and a spec-driven generator where your coding agent follows SKILL.md's own instructions to turn that text into the structured skill described above. The extractor doesn't rely on a single library per format — it tries a ranked list of tools and uses whichever is actually installed, and before running on a PDF it asks whether the book is technical (code, tables, formulas) or text-heavy (mostly prose), since those call for different tools: docling preserves markdown tables and code blocks at roughly 1.5 seconds a page, while pdftotext, pypdf, or pdfminer.six are near-instant but better suited to plain prose. python3 scripts/extract.py --check prints exactly which extractors are present on your machine and the install command for anything missing. One hard limit is worth knowing upfront: a scanned PDF with no actual text layer has nothing for any of these tools to extract, and the extractor detects that in the first few pages and stops immediately with an instruction to run ocrmypdf first, rather than grinding through the whole document to produce an empty skill.
Actually Running It
The command shape is simple by design: /book-to-skill <path|folder|glob> [skill-name], which also supports an analyze-only mode, a generate-from-analysis mode for reviewing the extraction before committing to the full build, and an update or fold-in mode for merging new source material into a skill that already exists — useful when a research cluster grows or a documentation folder gets a new runbook added later. Point it at one file for a single book, a folder or glob for a set of related sources, or a mixed pile of papers and your own notes to merge into one unified skill.
Reliability Fixes Worth Knowing About
The most recent release (v1.4.0) is specifically an extraction-reliability release, and what it fixed is a reasonable way to gauge how seriously the project treats silent failure — a real risk for a tool whose whole job is turning a document into something you'll trust without re-reading the source. Page-edge cleanup used to treat any short word built entirely from Roman-numeral letters as a stray page number, so real words like "MIX", "CIVIL", or "VIVID" could vanish if they landed alone on a page's first or last line; that's now gated behind actual heading context. Table-of-contents detection used to depend on which order multiple source files were passed in, silently giving different answers for the same two books depending on input order — it's now derived consistently regardless of order. A single unreadable file used to abort an entire batch conversion; now it's skipped and the rest of the batch still completes. Token-cost estimates for CJK-language books were off by roughly a thousand times because the estimator counted whitespace-delimited words, which doesn't work for languages written without spaces between them — it now counts CJK codepoints directly instead.
Beyond Books
The extraction technique isn't actually book-specific — it works on any structured prose, and the project explicitly points at other legitimate uses: folding a whole internal documentation folder (architecture decision records, runbooks, onboarding guides) into one queryable skill, turning a brand or design-system guide into something a team can query instead of skimming a 60-page PDF, or merging a stack of research papers plus your own notes into one unified, updatable skill. These are the cases where the copyright question doesn't even come up — content your own team already has full rights to.
Where This Differs From cangjie-skill
If you've looked at Cangjie Skill, the surface pitch sounds similar — both turn long-form content into structured Agent Skills. The actual design philosophies diverge in a way worth understanding. Cangjie Skill's pipeline explicitly includes a quoted original excerpt as one of six required structuring dimensions and showcases dozens of already-published, publicly-hosted extraction repos built from specific commercially-copyrighted books. book-to-skill takes the opposite stance on both counts: raw passage copying is explicitly excluded by a stated quality rule, and its own documentation directly warns against redistributing skills built from copyrighted material. If you're choosing between tools in this category, that design difference is the one to actually evaluate on, not just the feature list.
Practical Implications
- Use it on books you've bought and technical references you own — that's the tool's own stated, straightforward use case, and it sidesteps any copyright ambiguity entirely.
- The "beyond books" use cases are arguably the safest, highest-value application — internal documentation and brand guidelines are content your team already controls, with no fair-use question to weigh at all.
- Keep any skill generated from a third-party copyrighted book private, exactly as the project's own README instructs — this isn't optional caution, it's the tool's documented intended usage boundary.
- Check the performance methodology before trusting the token-savings number for your own use case — a documented benchmark is a good sign, but your actual query patterns against your actual books may not match the measured scenario exactly.
Practical Takeaway
book-to-skill is a well-scoped answer to a real, common problem — a book you bought and read once, effectively forgotten three months later — built with a design that takes the copyright question seriously instead of ignoring it. For anyone accumulating technical books and internal documentation they never actually re-reference, it's worth trying on material you clearly have rights to, with the Agent Skills standard's cross-tool compatibility meaning the resulting skill isn't locked to one coding agent.
Teams building internal knowledge tooling or evaluating Agent Skills for institutional reference material can get hands-on architecture help from Woyce Technologies.
FAQ
What is book-to-skill?
book-to-skill is an open-source tool that converts a technical book, document folder, or set of papers into a structured Agent Skill — chapter files, a glossary, patterns, and a cheatsheet — that a coding agent like Claude Code, GitHub Copilot CLI, or Amp can load on demand.
Is it legal to use book-to-skill on a book I bought?
The project is designed around exactly this personal use case: local processing, no raw passage copying in the output, and the resulting skill treated as personal study notes for your own reference. The project explicitly warns against redistributing or publicly sharing a skill generated from a copyrighted work.
Does book-to-skill upload my files anywhere?
No — extraction and analysis run locally on your machine. If your coding agent's underlying model runs in the cloud, the text you query follows that provider's normal data handling terms, the same as any other prompt you'd send it.
What file formats does book-to-skill support?
PDF, EPUB, DOCX, Markdown, HTML, RTF, and MOBI.
Can book-to-skill work on things other than books?
Yes — internal documentation folders, brand and design-system guides, and research paper collections all work with the same extraction approach, and these are arguably the cleanest use cases since there's no third-party copyright question involved.
How is book-to-skill different from Cangjie Skill?
Both convert long-form content into Agent Skills, but book-to-skill's extraction explicitly avoids copying raw passages and its documentation directly warns against redistributing skills built from copyrighted books, while Cangjie Skill's methodology includes verbatim quoted excerpts as a required output element and showcases already-published extraction repos of specific commercial books.
What happens if I point book-to-skill at a scanned PDF?
It fails fast rather than processing the whole book. The extractor checks the first few pages for an actual text layer, and if it's page images with no extractable text, it stops immediately and tells you to run ocrmypdf on the file first, then feed it the OCR'd output.
How do I know which extraction tools I actually have installed?
Run python3 scripts/extract.py --check — it prints which extractor is available for every supported format and the exact install command for anything missing, without needing to point it at a real file first.
Can I add new material to a skill I already generated?
Yes — an update or fold-in mode merges new source material into an existing generated skill, which is useful when a documentation folder grows or a research cluster gets new papers added after the initial conversion.