book-to-skill Setup: Turn Any Book PDF Into an Agent Skill

book-to-skill is a free, MIT licensed converter that turns a technical book, a docs folder or a stack of papers into a structured skill your coding agent loads on demand, and today it is the top repository on GitHub trending with roughly 1,400 stars added in a day on top of 13,100 total. Setup is short: one git clone into your agent's skills folder, about five minutes, then one pip install per document format you use.

• One clone registers the skill on Claude Code, GitHub Copilot CLI and Amp, which share the open Agent Skills SKILL.md format.
• Extraction runs on your machine; the tool ships no book content and uploads nothing itself.
• The maintainer measures 24x to 51x fewer tokens per question than dumping the same book into context.
• The README's pip install book-to-skill line does not work yet: the name is not on PyPI.

What is book-to-skill and why is it trending?

The tool is a compiler for prose. Point it at a file, a folder or a glob and it writes a skill folder: a SKILL.md holding the book's core mental models and a chapter index, one summary file per chapter, plus a glossary, a patterns file and a cheatsheet. Your agent keeps only the small core resident and reads a single chapter when you ask about that topic. The repo is Python, MIT licensed, and has 1,444 forks since it appeared on May 1, 2026.

RelatedSuperpowers Setup: Give Your AI Coding Agent a Real Workflow

It is spiking on the token math. Running tools/discovery_tax.py on three real books, one targeted question costs 119,264 tokens as a context dump of Think Python 2, 175,253 for Working Backwards and 256,287 for AI Engineering; a compiled skill answers from roughly 5,000. Against a one-time discovery loop rather than a raw dump, though, the advantage narrows to between 2.4x and 15.6x, and the README says so plainly.

How do you install it on Linux, macOS and Windows?

Same clone on all three platforms; only the destination differs. For Claude Code:

# Claude Code
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

For GitHub Copilot CLI, clone into its skills root and reload inside a session:

# GitHub Copilot CLI
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# then, in a copilot session:
/skills reload
/skills info book-to-skill

Amp, and Copilot CLI if you want one shared location, both read the cross-agent path:

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

On Windows those tilde paths resolve under your user profile, so clone from Git Bash or use the full path. Claude Code and Amp pick the skill up next session; only Copilot CLI needs the reload.

What actually varies by operating system is the extractors. Plain text, Markdown, reStructuredText and AsciiDoc need nothing extra; everything else uses the first available tool it finds, and one command tells you what is missing:

$ python3 scripts/extract.py --check

For PDFs the README splits by book type: prose-heavy books want pdftotext from poppler, which is instant, while technical books with tables and code want Docling, which preserves both at roughly 1.5 seconds per page:

# prose-heavy PDFs, Debian and Ubuntu
sudo apt install poppler-utils
# cross-platform fallbacks, no system package needed
pip3 install pypdf
pip3 install pdfminer.six
# technical PDFs: tables and code blocks preserved
pip3 install docling
# EPUB, best quality
pip3 install ebooklib beautifulsoup4

The README documents only the apt package for poppler, so on macOS and Windows the documented route is the pip fallbacks, which is why --check is the honest first command there: it prints the install line for whatever your formats need. Before extraction the skill also asks whether the book is technical or text heavy, and picks the tool from your answer.

How do you convert your first book?

One command, with an optional slug:

# one book
/book-to-skill ~/path/to/your-book.pdf
# a whole folder, merged into one skill
/book-to-skill ~/workspace/project-docs/ project-knowledge
# a glob
/book-to-skill "~/books/*.epub" my-library
# fold new material into a skill you already built
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

Afterwards the book is a slash command of its own, which is what makes it stick:

/designing-data-intensive-apps replication
/designing-data-intensive-apps ch05
/designing-data-intensive-apps "what chapters do you have?"

The README's measured conversions put Think Python 2 at 244 pages and 19 auto-detected chapters, at roughly one dollar of model spend per book on Sonnet-class pricing.

RelatedOpen Code Review Setup: Alibaba's Free AI Reviewer CLI

How does it compare to RAG and NotebookLM?

The README is fair here: for eighty books and a "find the part that mentions X" workflow, it says a RAG tool or NotebookLM wins.

What are the gotchas before you rely on it?

Four, and the first bites immediately. The README advertises pip install book-to-skill as a standalone CLI path, but that name returns a 404 on PyPI as of July 30, 2026; the metadata sits in pyproject.toml at version 1.2.0 and has never been published. Clone the repo and you get everything anyway.

Second, chapter segmentation needs explicit headings, so books using only titles or roman numerals, such as Pro Git and Moby-Dick, do not auto-segment. Third, local extraction is not local inference: the text still goes to whatever model you run. Fourth, and most interesting, this tool reads documents you did not write and turns them into instructions your agent will follow, which is a prompt injection surface by construction. The maintainer clearly agrees, because most of July went into hardening it:

1. Jun 17, 2026v1.2.0 ships installable package, multilingual chapters
2. Jul 16, 2026UTF-8 decoding fix for pdftotext issue 68
3. Jul 23, 2026Invisible Unicode scrubbed from every parser zero-width chars, U+E0000 tag block
4. Jul 24, 2026Prompt injection scanner for generated skills override phrases, control tags, exfiltration shapes
5. UnreleasedAll of it still untagged clone master, not the release

That scanner, tools/scan_generated_skill.py, reports only a rule name and file location rather than echoing the suspicious text back at you. Thoughtful, but it is advisory and opt-in, so if you feed this thing PDFs off the open internet, run it yourself.

Our take

The clever part is not the extraction, which is a thin wrapper over poppler, pypdf and Docling. It is paying the reading cost once. Every other way to let an agent use a book is a runtime cost you pay again every turn, whether a context dump, a retrieval hop or a discovery loop through a PDF. Compiling it into named frameworks and a chapter index turns a recurring bill into a fixed one, and the artefact is Markdown you can fix when the model gets something wrong.

The gap between what the README promises and what has shipped is real but small, and it points one way: this project is moving faster than it releases. If you have a book you keep reopening, or a docs folder nobody has read end to end, it is a five minute install and about a dollar to find out. Clone master, and run the scanner on anything you did not write.

Original analysis by GenZTech. Tool documentation: virgiliojr94/book-to-skill on GitHub.