Book-to-Skill Turns Your PDF Shelf Into Agent Memory

Every few months a GitHub project crosses 20,000 stars by naming a workflow people were already doing badly by hand. book-to-skill is the latest. The pitch fits in a sentence: point it at a PDF or EPUB and get a Claude Code skill — a SKILL.md plus a folder of per-chapter files — that the agent loads on demand while you work. It sits at 24k stars and 2.6k forks, which is a lot of attention for what is, mechanically, a prompt and a Python extraction script.

That's not a dismissal. It's the interesting part.

What it actually builds

The tool isn't a RAG pipeline, and it isn't a summarizer. Running /book-to-skill your-book.pdf drives a three-stage process. Extraction turns the document into clean text, picking a backend per format: pdftotext for prose-heavy PDFs, Docling (slow, roughly 1.5 seconds a page) for technical ones with tables and code, ebooklib for EPUB, Calibre's ebook-convert for MOBI. Analysis then asks the model to pull out structure: named frameworks, decision rules, anti-patterns, glossary terms. Generation writes that structure into the Agent Skills layout.

The output budget is the design:

The author's headline number — 24× to 51× fewer tokens than pasting the book into context to answer one question — is self-reported, measured on the author's own test books, and I couldn't find an independent replication. But the mechanism is sound and doesn't need a benchmark to believe. A 600-page book is 300k+ tokens. A 4k-token index plus one 1k-token chapter file is 5k. The ratio follows from arithmetic, not cleverness.

The smarter trick is on the input side. For books over ~50k tokens, the conversion agent doesn't read the whole thing. It samples the first 8,000 characters to map the table of contents, then uses grep and offset-bounded sed reads to jump to chapter boundaries. Generation cost scales with output size, not source size. A pre-flight estimate shows you expected input and output tokens before you commit, which matters because a dense reference book still produces 25k–40k output tokens, and you're paying for every one of them.

Why this lands now

Three things had to line up. First, Anthropic shipped Agent Skills in late 2025 and published the SKILL.md format as an open spec, so the same folder now loads in Claude Code, GitHub Copilot CLI and Amp. book-to-skill is installable with npx skills add virgiliojr94/book-to-skill and its output works anywhere the spec does. A year ago this would have been a Claude-only hack; today it's portable.

Second, progressive disclosure became the consensus answer to context bloat. The skill-budget model — a small always-loaded index, big files pulled only when relevant — is the same pattern as Claude Code's own CLAUDE.md plus @file imports, and the same idea behind MCP resources. book-to-skill just applies it to a corpus nobody had a clean container for: the O'Reilly shelf you've already paid for.

Third, the obvious alternative is genuinely worse for this use case. Vector RAG over a book returns chunks; you get paragraphs that mention "circuit breaker" without the author's actual decision rule about when to use one. Structured distillation keeps the author's framing intact. That's the bet here, and for well-organized technical books — Designing Data-Intensive Applications, anything with numbered patterns and explicit trade-off tables — it's the right bet.

Where it falls over

The failure modes are exactly where you'd expect a heuristic chapter-splitter to fail. Scanned PDFs without a text layer are rejected outright (the extractor checks the first pages and bails). Books organized as Part I / Part II rather than "Chapter N" can confuse detection. Narrative non-fiction and memoir-style writing produce thin, generic skills because there are no frameworks to extract. And a model distilling a book is still a model: it will occasionally invent a "principle" the author never stated, and nothing in the pipeline checks the output against the source. Treat a generated skill as a senior colleague's reading notes, not as the book.

There's also a quiet quality problem with the conversion being driven by whatever model your agent is running. Use Haiku to save money and you get Haiku-grade distillation of a book you bought because the author thought harder than Haiku does.

The copyright question nobody wants to answer

This is the part that will decide whether the pattern spreads or gets stomped. The repo is honest about it: processing is local, nothing is uploaded by the tool, the MIT license covers the converter and not the content, and generated skills from third-party books "must stay private." The publish step defaults to private and requires you to type the literal word public to override.

That's the correct posture and it's also entirely unenforceable. A chapters/ folder of 1k-token summaries with the author's frameworks and decision tables is a derivative work in any sense that matters to a publisher, and someone will push a skills/ddia repo within weeks if they haven't already. The personal-use case — you bought the book, you run it locally, your agent consults it — is about as defensible as highlighting a paperback. The sharing case is where publishers will eventually show up, and the most plausible endgame is that O'Reilly or Manning ships official skills as a product tier. If I were a technical publisher I'd be building that this quarter rather than sending takedowns next year.

Should you use it

If you have a shelf of technical books you own in PDF or EPUB and you work in Claude Code, Copilot CLI or Amp: yes, for the two or three books you actually reach for. Run python3 scripts/extract.py --check first to confirm your extraction backends, choose "technical" over "text-heavy" for anything with code listings so Docling gets used, and look at the cost estimate before saying yes. Budget roughly the price of a long agent session per book.

Don't convert your whole library. The always-loaded SKILL.md is small, but twenty of them is 80k tokens of index competing for the agent's attention, and skills that never trigger are pure overhead. Pick books whose decision rules you want the agent to apply — system design, SQL performance, a language's idiom guide — not books you want it to quote.

And if your team writes internal engineering handbooks, this is the more interesting target than anything published. An architecture guide nobody reads becomes an architecture guide the agent enforces. That's the use case with no copyright asterisk, and it's the one I'd expect to outlast the novelty of turning DDIA into a folder.