book-to-skill: Turn Any Technical Book PDF Into a Claude Code Skill, 24x Fewer Tokens (2026 Guide)
book-to-skill is a free, open source tool that converts any PDF book into a structured agent skill. Works with Claude Code, GitHub Copilot CLI, and Amp. On-demand chapter loading, 24x-51x fewer tokens than dumping the PDF.
You buy a great technical book. You read it once. Three months later you cannot remember chapter 7 existed. The usual workarounds do not help. Searching the PDF gives you a list of pages, not answers. Asking your AI agent about the book either hallucinates or says it does not have the content. Taking notes as you read gives you a 200-line document you never open again.
book-to-skill, built by Virgilio Jr, is a free, open source tool that turns any technical book PDF into a structured agent skill your AI coding assistant can load on demand. Once installed, you type a slash command and your agent reads the right chapter and answers from the actual content. No hallucination, no digging through PDFs. The book becomes part of your workflow. Works with Claude Code, GitHub Copilot CLI, and Amp. 19,300+ stars on GitHub.
In this guide, you'll learn what book-to-skill is, how it works, and how to convert your first book into a skill.
What is book-to-skill?
book-to-skill is an open source tool that converts any technical book, document folder, or collection of sources into a unified agent skill. The skill is ready to study, reference, and use while you work in GitHub Copilot CLI, Amp, or Claude Code.
The tool has two halves: a deterministic Python extractor (document to clean text plus metadata) and a spec-driven generator (your agent follows the SKILL.md spec to turn that into a structured skill). On-demand chapter files keep the loaded skill small.
When you run book-to-skill on a PDF, it generates a full skill in your agent's skills directory containing:
- SKILL.md: Core mental models and chapter index (about 4,000 tokens)
- chapters/ch01-*.md: One file per chapter, loaded on-demand (about 1,000 tokens each)
- glossary.md: Every key term, alphabetically sorted with chapter references (about 1,500 tokens)
- patterns.md: All techniques, algorithms, and design patterns (about 2,000 tokens)
- cheatsheet.md: Decision tables and quick-reference rules (about 1,000 tokens)
Chapter files are loaded on-demand. They do not count against the skill budget until you ask about that topic. This is what makes it 24x to 51x more token-efficient than dumping the entire book into context.
Who is it for?
- Developers who read technical books: If you buy O'Reilly, Manning, or Packt books and want to reference them while coding without searching through 500-page PDFs, book-to-skill turns them into queryable skills.
- Teams with internal documentation: Fold a whole
docs/folder (architecture decision records, runbooks, onboarding guides) into one skill and ask it while you code. No more skimming 60-page PDFs. - AI agent power users: If you use Claude Code, GitHub Copilot CLI, or Amp daily, book-to-skill gives your agent access to structured knowledge from books and docs instead of hallucinating or guessing.
- Researchers and students: Turn a stack of research papers plus your own notes into a single unified skill. Update it as new material lands using the fold-in mode.
What makes book-to-skill different from just dumping a PDF into context?
- 24x to 51x fewer tokens: A PDF-reading agent does not just read. It navigates: it re-fetches the table of contents, backtracks, and re-processes everything on every turn. book-to-skill pays that structuring cost once, at conversion, so queries stay proportional to the answer. Measured on real books.
- On-demand chapter loading: Chapter files are loaded only when you ask about that topic. The SKILL.md (about 4,000 tokens) gives the agent the chapter index and mental models. When you ask about a specific topic, it loads just that chapter file (about 1,000 tokens). The rest of the book never enters context.
- Structured output, not a summary: book-to-skill does not summarize the book. It extracts frameworks, decision rules, anti-patterns, glossary terms, and per-chapter files. Structure, not a summary. The agent answers from the actual content, not a lossy paraphrase.
- Works beyond books: The name says "book" but the input is any structured prose. Internal documentation, brand and design systems, research clusters, specs and standards (RFCs, API contracts, compliance docs). If you re-open a document often enough to wish you had memorized it, it is a candidate.
- Privacy-first: Processing is local. Extraction and analysis run on your machine. Your files are never uploaded by this tool. If your agent's model runs in the cloud, the text you feed it follows that provider's normal data terms, same as any prompt.
- Open Agent Skills standard: Works with any host that supports the open Agent Skills standard. GitHub Copilot CLI, Amp, and Claude Code all read the same SKILL.md format. One conversion, three agents.
- Free and open source: MIT license. 19,300+ stars. 25 contributors.
What you need before you start
- An AI coding agent: Claude Code, GitHub Copilot CLI, or Amp. All three support the open Agent Skills standard and read the same SKILL.md format.
- Python 3.10+: For the deterministic extractor that processes the PDF into clean text and metadata.
- A PDF or document folder: The book or docs you want to convert. You must own the content or have the right to read it.
- Disk space: Minimal. The generated skill is text files, typically under 10,000 tokens total across all files.
Step-by-step installation
Step 1: Install the agent skill
Clone the book-to-skill 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:
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# For Amp or cross-agent:
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill
Step 2: Convert your first book
In your agent (Claude Code, Copilot CLI, or Amp), run:
/book-to-skill ./my-technical-book.pdf
The tool will extract the text, identify chapters, build the glossary, extract patterns, and generate the cheatsheet. This takes a few minutes depending on book length.
Step 3: Use the skill
Once the skill is generated, you can ask your agent questions about the book:
/my-book-slug replication
The agent reads the right chapter and answers from the actual content. No hallucination. No digging through PDFs.
Step 4: Update with new material (fold-in mode)
If you get a new edition of the book or want to add related papers:
/book-to-skill ./new-chapter.pdf --update my-book-slug
This folds the new content into the existing skill without regenerating everything.
Common errors and how to fix them
| Error | What it means | How to fix it |
|---|---|---|
| "No chapters detected" | The PDF does not have a detectable table of contents or chapter structure. | Ensure the PDF has a proper ToC. book-to-skill detects Markdown-prefixed chapter headings. For scanned PDFs without text layers, run OCR first. |
| Skill not found by agent | The skill was generated in the wrong directory or the agent does not scan that skills folder. | Verify the skill exists in ~/.claude/skills/<slug>/ (or the equivalent for your agent). Restart the agent to refresh the skills list. |
| Extraction quality is poor | The PDF has complex formatting, multi-column layouts, or embedded images that confuse the extractor. | Try the analyze-only mode first to see what the extractor produces, then adjust. For complex PDFs, pre-process with a PDF cleaner to remove headers, footers, and page numbers. |
| Bidirectional control characters warning | The PDF contains invisible Unicode control characters that can cause security issues. | book-to-skill automatically scrubs these. If you see the warning, the tool has already cleaned them. No action needed. |
book-to-skill vs dumping the PDF into context
| Feature | book-to-skill (structured skill) | Dumping PDF into context |
|---|---|---|
| Token cost per query | 1,000-4,000 tokens (on-demand chapter) | 50,000-200,000 tokens (entire book) |
| Token efficiency | 24x to 51x fewer tokens | Baseline |
| Hallucination risk | Low (answers from actual content) | High (agent may hallucinate from compressed context) |
| Multi-turn navigation | No (structure paid once at conversion) | Yes (re-fetches ToC, backtracks, re-processes every turn) |
| Persistent reference | Yes (skill stays in skills folder) | No (context lost when session ends) |
| Cross-agent compatibility | Yes (Claude Code, Copilot CLI, Amp) | No (tied to one session) |
| Best for | Books and docs you reference repeatedly | One-time Q&A on a document |
Bottom line: book-to-skill solves the "read once, forget forever" problem with technical books. By converting a book into a structured, on-demand skill, your AI agent can reference the actual content of the book without hallucinating and without burning 200,000 tokens to dump the entire PDF into context. The 24x to 51x token savings are measured on real books, not estimated. If you read technical books and use AI coding agents, this tool pays for itself in token savings on the first query. For developers who want their agents to actually know the content of the books they read, book-to-skill is the best free open source tool available.
3 alternatives worth checking out
- Google Skills (github.com/google/skills): Official agent skills for Google products and technologies. While not a converter like book-to-skill, Google Skills provides pre-built skills for Google Cloud, Android, and other Google products. If you work with Google technologies, these are ready-to-use skills that follow the same Agent Skills standard.
- Ponytail (github.com/DietrichGebert/ponytail): An agent skill that forces AI coding assistants to write minimal code. While book-to-skill adds knowledge, Ponytail changes behavior. They complement each other: use book-to-skill to give your agent book knowledge, and Ponytail to keep its code output lean.
- Cursor Rules (cursor.directory) (cursor.directory): A community database of
.cursorrulesfiles for specific tech stacks. While not book-based, cursor rules serve a similar purpose: giving your agent structured context about your project conventions. Use cursor rules for project-specific conventions and book-to-skill for book-level knowledge.
Found this guide useful? Check out more AI tools and developer tools on Sudo Scout.
Related posts
Prime Agent: The Self-Improving AI Coding Agent With Persistent IPython and Built-In Subagents (2026 Guide)
Prime Agent is a free, open source self-improving RLM agent for coding and long-running autonomous tasks. Persistent IPython, built-in subagents, continual harness refinement, daemon-backed sessions. 15.8K stars.
NVIDIA Switchyard: Route LLM Traffic Across Models and Providers Without Changing Your API (2026 Guide)
NVIDIA Switchyard is a free, open source Rust proxy that routes LLM requests across providers. Translates between OpenAI and Anthropic APIs, supports Claude Code and Codex, A/B benchmarking, cost optimization. Apache 2.0.
Needle 2: The 14MB AI Model That Runs on Phones, Wearables, and Smart Home Devices (2026 Guide)
Needle 2 is a free, open source 45M-parameter foundation model for tool calling on tiny devices. 14MB binary, 28MB RAM, runs fully offline. LoRA fine-tuning, confidence gating, structured extraction. 5.4K stars.