Short answer: book to skill works, the tool is real, and one documented optional pip route was unavailable when I tested it. The bigger surprise is what it is measured against. Compared with dumping a whole book into context it always saves tokens. Compared with best-case discovery, where the agent opens just the one chapter it needs, short chapters cost more than they save.
I installed it, ran it against five different document shapes, and measured the token math myself instead of repeating the number on the front page. Here is what came back.
What book to skill actually is
book-to-skill is an MIT-licensed converter that turns a document you already own into an agent skill. Point it at a PDF, EPUB, DOCX, HTML, Markdown or RTF file and it produces a SKILL.md core plus one file per chapter, a glossary, a patterns file and a cheatsheet. Your agent then loads the core plus whichever chapter your question touches, instead of holding the whole book in context.
book to skill follows the open Agent Skills format, so the same output works in Claude Code, GitHub Copilot CLI and Amp. When I checked on 2026-08-09 it carried roughly 19k stars and 2k forks, and the latest tagged release was v1.3.0, published 2026-07-30.
Everything below was run against book to skill on Ubuntu 22.04, Python 3.10.12, with poppler installed and docling not installed, against commit 442aaaa dated 2026-08-07. That commit declares version 1.3.0.
1. The documented pip install path was unavailable
The installation guide is emphatic that there are two ways to use book to skill and that you should not confuse them. Clone the repository into your skills folder to register the slash command, or run pip install book-to-skill to get the extraction engine on its own. Note that the repository README itself shows only the clone route; the pip line lives in the separate installation document.
The second one fails.
$ pip install book-to-skill
ERROR: Could not find a version that satisfies the requirement book-to-skill
(from versions: none)“from versions: none” means the index has no such project at all. Before blaming the network I installed pypdf in the same shell, which worked, then queried the package index directly for three spellings. All three returned 404.
| Check | Result |
|---|---|
pip install pypdf (control) | installed 6.13.1 |
book-to-skill on the index | HTTP 404 |
book_to_skill | HTTP 404 |
booktoskill | HTTP 404 |
The repository is not faking it. pyproject.toml declares the project name, a console script and version 1.3.0, and the changelog entry for 1.2.0 announced an installable package back in June. It also builds and installs locally without complaint. The narrow conclusion available to me is that the documented index route was unavailable when I tested it on 2026-08-09, not that the package was never published there. A 404 shows absence today; it cannot rule out an upload that was later removed.
What to do: use the clone path. It works exactly as documented. Treat the pip line as not yet available rather than as a broken tool.
2. Against best-case discovery, book to skill crosses near 5,200 tokens
The headline claim is 24x to 51x fewer tokens than dumping the book into context, measured by the project on real books. The repository ships the script that produces it, which is more than most projects do. My own runs reproduced the shape of that saving against a context dump but topped out at 28.7x, because I used a synthetic book rather than the titles they measured. And none of it is a benchmark of measured generated skills unless you pass --skill-dir.
But a context dump is not the thing most people actually do. The realistic alternative is letting the agent open the one chapter it needs. The repository measures that too and calls it the discovery loop. So I built a twelve-chapter book, changed only the length of each chapter, and ran the project’s own measurement script six times.
| Tokens per chapter | vs context dump | vs best-case discovery | Verdict vs best-case discovery |
|---|---|---|---|
| 753 | 1.8x | 0.2x | costs more |
| 1,500 | 3.6x | 0.3x | costs more |
| 2,993 | 7.2x | 0.6x | costs more |
| 5,233 | 12.6x | 1.0x | break-even |
| 8,220 | 19.7x | 1.6x | saves |
| 11,953 | 28.7x | 2.4x | saves |
Under those defaults the modeled crossover appears near 5,200 tokens per chapter. That number is not a universal measured break-even, and it matters how it is produced. Run without --skill-dir, the script does not measure a generated skill at all. It substitutes a 4,000-token core cap plus a 1,000-token compiled chapter, and labels the figure “design cap (no –skill-dir)” in its own output. My six runs are therefore a parameter sweep against that fixed 5,000-token model, not six skills benchmarked head to head.
The project documentation says the advantage scales with chapter size without giving a figure. The table above is where that crossover lands under the tool’s own default assumptions. The real crossover moves with content type and depth: SKILL.md sets the per-chapter budget anywhere from 800 to 3,000 tokens depending on whether the book is prose or technical and whether you want reference or study depth. A technical book at study depth compiles chapters up to three times larger than the 1,000 assumed here, which pushes the crossover up.
Two caveats, and the first is sharper than I first assumed. My run had no tiktoken installed, so the script counted the book with a words-divided-by-0.75 heuristic. The 4,000 and 1,000 on the other side of the comparison are constants, not counted text. Only one side of the ratio moves when you change tokeniser, so installing tiktoken would shift both the multiples and the exact crossing point. The heuristic also degrades badly on languages that do not delimit words with spaces, which is a live issue the project is currently fixing. Second, the discovery column is explicitly a model, stated in the script’s source comments and printed under every run. What survives all of this is the qualitative result: a fixed resident cost means a threshold exists. Its precise location does not survive.
Which books clear the bar
- Worth it: thick reference books with long chapters, dense internal documentation, standards and specifications you return to repeatedly.
- Not worth it: books chopped into short sections, quick-start manuals, collections of blog posts, anything you will read once.
3. Chapter detection is where it breaks, and non-English is not the problem
The whole book to skill design depends on finding chapter boundaries. If automatic detection returns zero, automatic segmentation is unavailable and the discovery model above stops describing your workflow. I fed it five shapes.
| Input | Chapters found | Result |
|---|---|---|
English Chapter 1 to Chapter 5 | 5 | correct |
Korean 제1장 to 제5장 | 5 | correct |
| Korean statute with an inserted chapter | 3 | correct, including the inserted form |
Korean articles 제1조 to 제5조 | 0 | correct by design |
| Title-only headings (Moby-Dick style) | 0 | no automatic chapters, manual mapping required |
The last row is the one to watch. A book whose chapters are headed by bare titles rather than a numbered word segments into nothing automatically. It is not silent about it: the extractor prints “0 detected” with a warning, and the measurement script refuses to run and suggests technical mode. Conversion can still proceed, with the documentation telling you to point at sections by hand. The project names Moby-Dick and Pro Git as examples, and my run reproduced the behaviour exactly.
Non-English support, by contrast, is better than I expected, and it is not incidental. Korean heading detection is a headline feature of v1.3.0, covering four classifiers and the suffixed form that Korean statutes use for inserted chapters. The release notes report validation against a corpus of roughly three thousand statutes at 0.999 precision and 1.000 recall, and the pattern deliberately requires a prefix so that an everyday phrase meaning “ten photographs” cannot false-match as a chapter. Article-level headings are excluded on purpose, which is the right call, since treating every article as a chapter would produce hundreds of them. My five test cases reproduce that documented behaviour rather than discover it.
One synthetic Korean PDF also came through cleanly: all five chapters found in 44 milliseconds across five pages, with a character-count ratio of 102.8 percent against the raw extractor output. That ratio is a crude size check rather than a fidelity score, since output can grow while individual passages are still lost, and one generated file is not evidence about real Korean books.
One failure mode worth knowing about
The PDF cleaner strips running headers by finding lines that repeat at the top or bottom of more than half the pages. The judgement uses page edges, but the deletion does not check position.
boiler = {ln for ln, c in edge.items() if c > len(pages) / 2}
for i, ln in enumerate(lines):
if s in boiler: continue # removed anywhere on the page
if i in (first, last) and _PDF_PAGE_NUM.match(s): continue # position checked herePage numbers get a position check on the very next line. Running headers do not. I built a deliberately pathological PDF in which every line was identical, and 7,380 characters collapsed to 181, leaving only the headings.
Do not over-read this. It was an artificial file built to trigger exactly this path. The precise behaviour is narrower than the demonstration suggests: a line is removed everywhere it appears only if that same line was already classified as a running header or footer from the page edges. Ordinary varied prose is unlikely to trigger it, and a varied PDF came through fine in the same run, but a body line identical to text already classified as a running header can still be removed. Check the reported word count against your source if your document repeats a short line at the top or bottom of most pages.
The security work has already shipped
Version 1.3.0 carries a substantial set of hardening entries: a scanner that inspects generated skills for prompt-injection phrasing, removal of invisible Unicode, DOCX entity-expansion defences, and argument-injection fixes for filenames beginning with a dash. These are in the released version, not pending.
The presence of that work is an acknowledgement by the project that converting an untrusted document into an agent skill has an injection surface. That is worth pausing on if you plan to convert files other people sent you: a document can carry instructions aimed at the agent that reads it, and the generated skill is loaded with your agent’s authority.
What remains unreleased is narrower and worth knowing for a different reason. The default branch carries broader control-character stripping, and a fix for the token estimator, which undercounted languages that do not put spaces between words by around a thousandfold. If you plan to convert Chinese or Japanese material, that fix is not in the tagged release yet.
How it compares to the alternatives
| Approach | Cost shape | Best for |
|---|---|---|
| Paste the whole book | Full book, re-billed every turn | A single one-off pass |
| Let the agent open the PDF | Table of contents plus the chapter, once | Short chapters, occasional questions |
| book to skill | Fixed core plus compiled chapter | Long chapters, repeated use |
| Retrieval over a library | Per-query chunks | Many books, find-the-passage questions |
This table compares designs, not benchmark runs. I measured the first three rows of behaviour with the project’s own script; I did not run a retrieval system side by side.
A book to skill checklist before you convert anything
- Clone the repository into your agent’s skills folder. Ignore the pip line for now.
- Run the dependency preflight first. It reports which extractors are present and the exact command for anything missing.
- Check that your book uses numbered chapter headings. If chapters are bare titles, expect zero segmentation.
- Estimate chapter size. Under roughly 5,000 tokens a chapter, the modeled result favours letting the agent open the chapter directly. Against a full context dump the conversion still wins at any size.
- After extraction, compare the reported word count against the source. A large drop may indicate the header cleaner removed body text.
- Install
tiktokenbefore running the measurement script if you want BPE-based ratios. It does not replace the extractor’s own preflight estimator, which uses a separate heuristic. - Only convert documents you own, and be cautious with files from other people.
If you are weighing up other agent tooling before committing, I applied the same measure-first approach to the Open Design Codex plugin, and put Claude and ChatGPT through the same document to see where each one broke.
Who should install book to skill
Install it if you keep returning to the same thick technical book, or you maintain internal documentation with long numbered sections that your team queries repeatedly, or you work with regulations and rulebooks in a language with numbered chapter conventions, which my testing suggests is worth trying but does not confirm.
Skip it if your material is short-chaptered, or you only need one answer from one book, or your documents use titles instead of numbered headings. In those cases the agent opening the file directly is cheaper and simpler.
Frequently asked questions
Is book to skill free?
The converter is MIT licensed and free. The cost you do pay is the model usage for the conversion itself, since an agent reads the extracted text and writes the skill files. The repository publishes measured per-book estimates of roughly a dollar per book, which I did not independently verify.
Why does pip install book-to-skill fail?
Because no matching distribution was available on the index when I tested it on 2026-08-09. The project is packaged and versioned, and it builds and installs locally as version 1.3.0, so the package itself is not broken. What I can say is that it was not installable from the index at that moment. Use the clone path instead.
Does it work with books that are not in English?
It supports several numbered chapter conventions rather than every language. Korean and Thai detection both arrived in v1.3.0, and I verified the Korean cases directly, including the inserted-chapter form used in statutes. Earlier releases added Portuguese, French, German, Italian, Dutch, Chinese and Japanese. One caveat for Chinese and Japanese: the cost pre-flight currently undercounts languages without spaces between words, and the fix is on the default branch rather than in the tagged release.
Is this just retrieval with extra steps?
The difference is when the work happens. Retrieval matches chunks at query time. This does one analysis pass up front and writes structured files. That front-loading is exactly why it loses on short chapters and wins on long ones.
Does it upload my book anywhere?
Extraction runs locally. The extracted text is then read by your agent, so it follows whatever data terms your model provider applies to any other prompt. The repository ships no book content itself.
How long does conversion take?
Text extraction was 28 to 29 milliseconds for a five-chapter document and 44 milliseconds for a five-page PDF on my machine. That is only the extraction step. The agent analysis that follows is the slow part, and technical mode using docling is documented at around 1.5 seconds per page, which I did not measure.
Will it work with EPUB files?
Yes. EPUB, DOCX, HTML, RTF, Markdown and plain text are supported, with MOBI and AZW handled through an external converter. Quality is better with the optional libraries installed, and the preflight tells you which are missing.
What I did not test
I measured the book to skill extraction pipeline and the token model. I did not evaluate the quality of a finished skill, because generating one requires an agent session rather than the converter alone. I did not run technical mode, and I did not convert a commercial technical book. Anyone claiming the generated summaries are good or bad has tested something I have not.
Sources
- Repository at the tested commit: virgiliojr94/book-to-skill @ 442aaaa
- Measurement script used for the token table: tools/discovery_tax.py
- Release notes for the Korean and Thai detection and the shipped hardening: v1.3.0
Last verified 2026-08-09 against commit 442aaaa. Star count, package availability and the remaining unreleased fixes are all likely to change; the break-even structure of book to skill will not, because it follows from the fixed core cost. Next review scheduled for November 2026.
