Converting Books to Skills
Bash# Install the skill npx skills add virgiliojr94/book-to-skill # or: git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill # Convert a source (path, folder, or glob) /book-to-skill path/to/book.pdf my-skill-name
Result: a SKILL.md (~4,000 tokens) plus one ~1,000-token markdown file per chapter, loaded only when needed — claimed 24×–51× token reduction versus pasting the source into context.
Progress:
- Confirm the source material is lawful to process (MIT license covers the converter, not the book's copyright)
- Ensure Python 3 is installed; install format extractors as needed (poppler for PDF, ebooklib for EPUB)
- Run the converter against a path, folder, or glob, optionally naming the output skill
- Review the generated
SKILL.mdfirst — this is what the agent reads every time - Spot-check
glossary.md,patterns.md, andcheatsheet.mdfor accuracy - Skim a sample chapter file to confirm chapter splits are coherent and self-contained
- Install the resulting skill into the target harness (Claude Code, Copilot CLI, Amp, Hermes Agent)
- Test the agent on a task that should trigger on-demand loading of a specific chapter
Example 1:
Input: A single PDF of a software architecture book, run as /book-to-skill architecture-book.pdf arch-patterns
Output: arch-patterns/SKILL.md with mental models and a chapter index, chapter-01.md through chapter-12.md (~1,000 tokens each), plus glossary.md, patterns.md, and cheatsheet.md — installable as a normal Agent Skill.
Example 2:
Input: A folder of internal onboarding docs, run as /book-to-skill ./docs/onboarding/ team-handbook
Output: A single shareable team-handbook skill the whole team's agents can load, rather than each engineer pasting different doc excerpts into prompts.
- Always read the generated
SKILL.mdbefore trusting it — it's the always-loaded entry point and errors there propagate to every task. - Treat one skill per source book/doc-set; build a small library of domain skills rather than one sprawling system prompt.
- Use globs for multi-file documentation sets so related material converts into a single coherent skill instead of scattered ones.
- Verify you hold rights to process copyrighted material — the MIT license applies only to the converter tool, not the input content.
- Prefer this approach specifically when only a fraction of the source is relevant to any given task — that's where the token savings materialize.
- Don't skip reviewing
SKILL.md— if the extracted mental models are wrong or garbled, every downstream task inherits the error. - Don't feed copyrighted books without checking usage rights; the tool's license doesn't cover that.
- Don't use this for short or single-topic documents where the whole thing fits cheaply in context anyway — the two-tier split adds overhead without payoff.
- Don't assume extraction is lossless for scanned/image-heavy PDFs — poppler-based text extraction can mangle layout-dependent content (tables, diagrams).