book-to-skill: Transform Books into AI Agent Skills
virgiliojr94/book-to-skill
book-to-skill delivers on its core promise: turning books you already own into structured, queryable skills that don't hallucinate. The token efficiency gains are real and measured, and the on-demand chapter loading means you're never burning context budget on content you didn't ask about. Reach for this when you have technical books, documentation, or reference material you keep re-reading. Skip it if you just want quick summaries — the extraction pipeline adds setup overhead that only pays off when you actually query the skill repeatedly.
The Challenge of Using Technical Books with AI Agents
Technical books become forgotten after a single read. Three months later, you can't recall chapter 7 exists. The usual workaround — asking an AI agent about the book — either produces hallucinations or fails entirely because the agent lacks the content. Dumping the PDF into context is expensive and slow, with agents spending tokens re-navigating the table of contents on every query. There's no middle ground between 'memorize everything' and 'waste tokens on a full context load every time.'
Transforming Documents into Agent Skills
book-to-skill is a Python CLI that turns documents into structured agent skills following the open Agent Skills standard. Point it at a PDF, EPUB, or folder of docs and it generates a skill directory — a core SKILL.md, per-chapter content files, a glossary, and a cheatsheet — that works in Claude Code, GitHub Copilot CLI, and Amp. You invoke it with a slash command, and the agent loads only the relevant chapter instead of guessing.
Structured Output for AI Agents and Token Efficiency
- ✓Generates a full skill directory from a single file, folder, or glob pattern — SKILL.md, chapter files, glossary, patterns, and cheatsheet included
- ✓On-demand chapter loading: agents read only the relevant chapter file, not the entire skill, keeping token costs proportional to the question
- ✓Compatible with the Agent Skills standard used by Claude Code, GitHub Copilot CLI, and Amp — one skill format works across all three hosts
- ✓Format support for PDF, EPUB, DOCX, HTML, RTF, MOBI/AZW/AZW3, TXT, Markdown, reStructuredText, and AsciiDoc
- ✓Extractor selection is automatic: the tool detects book type (text-heavy vs. technical) and picks the right parser (pdftotext, docling, ebooklib, etc.)
- ✓A --check flag verifies all optional dependencies are installed and prints the exact install command for anything missing
- ✓Update/fold-in mode lets you merge new content into an existing skill as you read more of the source material
- ✓Discovery tax measurement tool included: tools/discovery_tax.py lets you benchmark token costs against raw context dumps
Applying book-to-skill to Diverse Content
- •Technical books: convert programming, systems design, or domain-specific books into queryable skills you reference while coding
- •Internal documentation: fold an entire docs/ folder into one skill — ADRs, runbooks, onboarding guides — and ask questions while you code
- •Brand and design systems: turn voice guidelines, tone-of-voice docs, or component principles into skills your team queries instead of skimming PDFs
- •Research clusters: merge a stack of papers plus your own notes into a unified skill, updated as new material lands via the fold-in mode
- •Specs and standards: convert RFCs, API contracts, or compliance documentation into skills you can reference on-demand without memorizing
- •Course material: transform a collection of tutorials or lecture notes into a skill you query while working on related projects
Getting book-to-skill Set Up
Clone the repository into your agent's skills folder. For Claude Code: `git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill`. For GitHub Copilot CLI: use `~/.copilot/skills/` instead. For Amp or cross-agent setups: use `~/.agents/skills/`. After cloning, run `python3 scripts/extract.py --check` to verify which format extractors are available and get the exact command to install any missing ones. No pip install is required for plain text, Markdown, reStructuredText, or AsciiDoc — those formats work out of the box.
Converting Documents to Agent Skills
Run `/book-to-skill ./my-book.pdf` from your agent's command line to begin extraction. The tool prompts you to classify the book as text-heavy or technical — this determines which extractor is used (pdftotext for prose, docling for code-heavy or tabular content). After extraction, it generates the full skill directory and tells you where it was placed. Use `python3 scripts/extract.py --help` to see all modes: analyze-only (inspect content without generating), generate-from-analysis (rebuild skill from cached extraction), and update/fold-in (merge new content into an existing skill). Generated skills are invoked with a slash command matching the skill name, like `/my-book replication`.
Strengths
- ✓**Significant token efficiency**: It reduces token usage by 24×–51× compared to dumping an entire book into an agent's context, as measured on real books. This helps manage costs and improves query performance by paying the structuring cost once at conversion.
- ✓**Structured, on-demand skill generation**: The tool distills content into a structured skill, generating specific files like `SKILL.md`, chapter files, `glossary.md`, `patterns.md`, and `cheatsheet.md`. Chapter files are loaded only when needed, keeping the active skill small and ensuring answers come directly from the source content, preventing hallucination.
- ✓**Broad input and agent compatibility**: It processes various document types—PDFs, EPUBs, DOCX, HTML, Markdown, and more—and integrates with multiple agent hosts that support the open Agent Skills standard, including GitHub Copilot CLI, Amp, and Claude Code.
- ✓**Local and private processing**: All extraction and analysis occur on the user's local machine, ensuring that source files are never uploaded by the tool. This protects the privacy and confidentiality of technical books and internal documentation.
Considerations and Dependencies
- △Requires your agent host to support the Agent Skills standard — if your tooling doesn't use that format, book-to-skill won't work without adapter work
- △PDF extraction quality varies by tool and source: scanned image PDFs won't extract without OCR preprocessing, and complex layouts may lose structure regardless of parser choice
- △The extractor dependencies (docling, pdfminer.six, ebooklib, etc.) are optional and must be installed manually for non-trivial formats — there's no bundled all-in-one installer
- △Skills generated from copyrighted books should not be redistributed per the README's fair use guidance — this limits team sharing workflows for purchased books
- △Token savings are measured on specific books; real-world savings will vary depending on how you query the skill and whether chapter boundaries align with your questions
Approaches for AI Agent Knowledge
Frequently Asked Questions
Dumping a PDF into context forces the agent to re-navigate the entire document on every query — a 'discovery loop' tax that costs tokens and latency even for simple questions. book-to-skill pays that structuring cost once during conversion, so each query loads only the relevant chapter file. The README reports 24×–51× fewer tokens as a result.
Extraction and analysis run locally on your machine — book-to-skill itself doesn't upload anything. The README notes that should your agent's model operate in the cloud, the text you process follows that provider's normal data terms, just like any prompt you send.
Yes. The README lists internal documentation, brand and design systems, research paper collections, specs, RFCs, and compliance docs as valid inputs. Any structured prose you re-read constantly is a candidate.
book-to-skill generates skills in the open Agent Skills format used by GitHub Copilot CLI, Amp, and Claude Code. The same SKILL.md and chapter files work across all three hosts.
The README advises against redistributing skills generated from copyrighted books. It compares them to personal study notes — fine for private use, but sharing can infringe rights holders. Skills built from internal docs, your own writing, or open-licensed material are fine to share within their license bounds.
book-to-skill requires Python 3 and runs on macOS, Linux, and likely Windows (the README doesn't specify Windows compatibility but the codebase is standard Python). For PDF extraction, you need at least one of: poppler-utils (pdftotext), pypdf, pdfminer.six, or docling. Plain text and Markdown work with no extra dependencies.
Who should try it — and who should skip
Developers who read technical books and use Claude Code, GitHub Copilot CLI, or Amp daily will get the most value — the setup cost (installing extractors, running the conversion) pays off quickly when you query the skill repeatedly. It's also a strong fit for teams with internal documentation that gets referenced but never memorized. Skip it if you rarely re-read technical material, don't use an agent host that supports the Agent Skills standard, or just want one-off summaries — the pipeline overhead isn't worth it for single-use extraction.