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.
The underlying problem is one most developers recognise. Pasting a whole PDF into a chat burns through the context window on every question, while relying on the model's general training gets you vague, sometimes invented answers about a specific author's framework. A standard retrieval pipeline is a heavier lift than most people want for a shelf of reference books. book-to-skill sits in between: a one-time conversion into a structured skill, then cheap, targeted lookups whenever a question actually needs the book.
This explainer covers how the generated skill is structured and why that matters for token use, what the project's own measured savings claim says, how its fair-use design is built into the extraction rules, which extraction tools do the work and where they fail, how to run it, what the latest reliability release fixed, uses beyond books, and how it differs from Cangjie Skill.
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.
book-to-skill vs Pasting the PDF vs a RAG Pipeline
The project positions itself between two familiar options: pasting the whole source into the chat, or building a retrieval pipeline. Putting the three side by side shows where each one fits.
| Factor | Paste the whole PDF | book-to-skill | RAG pipeline |
|---|---|---|---|
| Setup effort | None | One-time conversion per source | Chunking, embeddings, vector store, retrieval code |
| Context cost per question | Whole book, every time | Core file plus the chapters you ask about | Retrieved chunks only |
| What the agent sees | Raw text | Synthesized frameworks, rules, glossary, cheatsheet | Raw passages matched by similarity |
| Raw passages from the source | Yes, all of them | Excluded by a stated quality rule | Yes, by design |
| Adding new material | Paste again | Update or fold-in mode | Re-index |
| Best fit | A one-off question about a short document | A personal or team reference shelf used repeatedly | Large, frequently changing corpora with many users |
Pasting is the zero-effort option, and for a short document and a single question it is perfectly reasonable. The cost appears with repetition: every question pays for the whole book again, and long inputs dilute the model's attention across material that has nothing to do with the question. For a reference you consult weekly, that tax adds up quickly.
A retrieval pipeline solves the cost problem by fetching only the passages that look relevant. It scales to very large and fast-changing collections, which is why it remains the default for enterprise knowledge search. The trade-off is engineering effort, and the fact that what reaches the model is raw text chunks chosen by similarity, which may split a framework across several fragments or miss the passage that explains the idea best.
book-to-skill takes a third route. It does the interpretation once, up front, turning the source into structured notes that a coding agent can navigate by chapter. That makes it closer to a well-organised set of study notes than to a search index. It suits a shelf of books and document folders that change occasionally and that one person or a small team queries often. It is less suited to huge collections that change daily, where a retrieval system's automatic re-indexing earns its complexity.
Benefits of book-to-skill
The tool's design choices translate into a handful of practical gains for developers who rely on reference material.
Answers grounded in the book you actually own
Asking a model about a specific author's framework from memory invites confident but invented detail. With the skill loaded, the agent answers from structured notes derived from the real source, organised by chapter. You get responses tied to what the book actually says, and you can trace an answer back to the chapter file it came from when something looks off.
Far less context spent per question
Because the core file is compact and chapter files load only when relevant, a question about one topic does not drag the whole book into context. The project documents its own token-savings measurements; the exact ratio for your queries will differ, but the mechanism of loading less is what keeps repeated lookups cheap. Smaller inputs also tend to keep the model focused on the question, rather than spreading its attention across hundreds of pages that have nothing to do with it.
No retrieval infrastructure to maintain
There is no vector database, embedding job, or retrieval service to run. The conversion happens once per source and produces plain files. For an individual developer or a small team, that removes the main reason reference books never make it into their agent's working knowledge. The files can sit in a repository or a home directory like any other configuration, and they are easy to inspect, diff, and delete.
Portable across coding agents
The output follows the Agent Skills format, so the same skill can be used with Claude Code, Copilot CLI, or Amp. Teams that use different agents, or switch between them, do not have to rebuild their reference library for each one. That matters in a market where teams change tools often.
Local processing and a built-in copyright boundary
Extraction runs on your machine, and the output deliberately avoids copying raw passages. That makes it easier to use the tool on internal material without uploading files to a new service, and it gives a clear rule for what the generated skill should contain.
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.
book-to-skill Use Cases
The extraction technique isn't actually book-specific — it works on any structured prose. The project explicitly points at several legitimate uses beyond a personal bookshelf, and several of them avoid the copyright question entirely because the content belongs to your own team.
A personal technical library
A developer has a shelf of books on system design, testing, and a language they use daily, read once and half-remembered. Converting each into a private skill lets them ask the agent how a specific author recommends handling a problem, mid-task, without hunting through a PDF. The outcome is reference material that actually gets used at the moment it is relevant, kept private as the project instructs.
Internal documentation folders
Architecture decision records, runbooks, and onboarding guides tend to sprawl across a folder nobody reads end to end. Folding the whole folder into one queryable skill lets engineers ask the agent why a decision was made or how to run a recovery procedure. New team members get answers grounded in the team's own documents rather than generic advice, and the update mode keeps the skill current as runbooks are added. Because this is the team's own material, the skill can be shared internally within normal access policies.
Brand and design-system guides
A long brand or design-system PDF is easy to skim and easy to misapply. Turning it into a skill means a developer building a component can ask the agent about spacing rules or naming conventions and get an answer based on the actual guide. The likely outcome is fewer inconsistencies caught late in review, and less time spent by the design team answering the same questions in chat.
Research paper collections
Researchers and engineers tracking a topic accumulate papers plus their own notes. Merging the stack into one unified, updatable skill gives a single place to ask how papers compare on a method or which result supports a claim. When new papers arrive, they can be folded in rather than starting over. Openly licensed papers can be shared within their licence terms; anything else follows the same keep-it-private rule as books.
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.
Common book-to-skill Mistakes
Most disappointing results with the tool come from a few avoidable missteps in setup and use.
Feeding it scanned PDFs
A scanned book has no text layer, so no extractor can pull anything from it. The tool detects this and stops, but users sometimes take that as a failure of the tool rather than a missing step. Run ocrmypdf on scanned files first, then convert the OCR'd output.
Using a prose extractor on a technical book
Fast plain-text extractors handle novels and essays well but can flatten tables and code blocks. Converting a technical book with them produces a skill missing exactly the material you wanted. Answer the technical-or-prose question honestly and install docling for books heavy in code, tables, and formulas.
Sharing skills built from copyrighted books
It is tempting to commit a useful skill to a team repository or publish it. The project is explicit that skills built from third-party copyrighted works should stay private. Redistributing them can infringe the rights holder's copyright, whatever the format of the notes.
Never checking the output against the source
The generated skill is an interpretation, and extraction can still miss or mangle content. Users who never spot-check a chapter file against the original may not notice gaps until the agent gives a wrong answer at a bad moment. Ask questions you already know the answers to before relying on a new skill, and open one or two chapter files to see whether the key frameworks made it through.
Running an outdated version
The latest release fixed several silent extraction errors, including dropped words and inconsistent table-of-contents detection. Skills built with older versions may carry those errors. Update the tool and regenerate skills you depend on, particularly any built from multiple source files or from CJK-language books, where the older bugs had the largest effect.
book-to-skill Best Practices
- 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.
- Run the extractor check before your first conversion.
python3 scripts/extract.py --checkshows which tools are installed and what to add, so you do not discover a missing extractor halfway through a large book. - Use analyze-only mode on important sources. Review what the extractor pulled out before generating the full skill, especially for books with complex layouts, and fix problems at the extraction stage where they are cheapest.
- Name skills clearly and keep a source list. Record which files and editions each skill was built from. When a new edition appears or a runbook changes, you know which skill needs regenerating or updating.
- Test with questions you can verify. After each conversion, ask the agent several questions whose answers you know from the source. Wrong or vague answers point to extraction problems worth fixing before the skill becomes part of daily work.
- Trial it on internal documentation first. A runbook folder or design-system guide is low risk, easy to verify, and shows quickly whether the skill format suits how your team asks questions.
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. Because the agent pulls in only the relevant piece when you ask, it avoids pasting a whole book into context on every question.
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. In practice, that means keeping any skill built from a third-party book private to you, which is the tool's documented usage boundary rather than optional caution.
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. If that matters for sensitive internal documents, check your agent's model and data retention settings before pointing the tool at them.
What file formats does book-to-skill support?
PDF, EPUB, DOCX, Markdown, HTML, RTF, and MOBI. For PDFs, the extractor works best when the file has a real text layer. Technical books with code and tables benefit from a layout-aware extractor such as docling, while prose-heavy books can use faster plain-text tools. Scanned books need an OCR pass first, which the tool tells you about rather than silently producing an empty skill.
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. A runbook folder or a design-system PDF turned into a skill can be shared across the team within your own policies, which makes these internal sources a low-risk way to trial the tool before using it on personal book purchases.
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. If copyright posture matters to your team, that difference in design philosophy is the main thing to weigh when choosing between them.
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. This saves you from grinding through the whole document only to end up with an empty skill.
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. That matters because the extractor tries a ranked list of tools and uses whichever is installed. For technical PDFs with code and tables, check that docling is present, since faster tools like pdftotext or pypdf suit plain prose better.
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. You don't need to rebuild from scratch each time. If you want to review what the extractor pulled out before changing anything, the analyze-only and generate-from-analysis modes let you inspect the extraction first and commit to the build afterwards.
Conclusion
book-to-skill addresses a narrow but real gap: technical knowledge you already own, sitting in books and document folders your coding agent cannot use well. Dumping the whole source into context is expensive and noisy, and relying on the model's general training invites confident guesses. A structured skill with a compact core file and chapter files loaded on demand gives the agent grounded answers at a fraction of the token cost, according to the project's own documented measurements.
Two points stand out. First, the extraction step is where quality is won or lost, so check which extractors you have installed, pick the right one for technical versus prose-heavy books, and run OCR on scanned files before starting. Second, the fair-use design only works if you respect it: skills built from third-party copyrighted books should stay private, while internal documentation and openly licensed material are the cleanest, most shareable uses. Treat the token-savings figure as a benchmark to verify against your own query patterns, not a guarantee.
A practical first test is converting one internal runbook folder and asking the agent questions you already know the answers to. If you want help designing agent skills or knowledge tooling around your team's documentation, our AI agent development team can help you scope it.