book-to-skill Compiles a Technical Book Into an Agent Skill, Then Deletes the Book

A converter with 12,000 stars turns your PDFs into skill files your agent follows. Its own quality rules make those files impossible to check against the author.

Point book-to-skill at a 500-page technical PDF and about a dollar of tokens later you have a skill folder: a 4,000-token core file, one summary per chapter, a glossary, a patterns file, a cheatsheet. Type /designing-data-intensive-apps replication and your agent reads the right chapter and answers from it.

Two lines in its own SKILL.md are worth reading next to each other. Quality Rule 7: "Never copy raw book text, always synthesize, summarize, extract signal." Step 10: rm -rf /tmp/book_skill_work.

So the artifact your agent will cite for months contains none of the author's actual sentences, and the extracted text it was derived from is deleted when the run finishes. What you keep is a model's reading of a book, formatted as instructions, with the book gone.

Why this is not a filing question

Skills stopped being a personal convenience this month. GitHub moved Agent Skills and MCP connections to general availability inside Copilot code review on July 29, so a SKILL.md in a repo now shapes review comments on every pull request. Microsoft Agent Framework shipped skill discovery from MCP servers for .NET, so a central team publishes once and a fleet picks it up. Skills are the distribution format for how agents are told to behave.

Which changes what a book skill is. A note you wrote is something you read and judge. A skill is something the model treats as guidance while it works, and the model does not know whether a given decision rule came from the author or from a summarizer having an off paragraph on chapter 9. That gap is where the interesting risk lives, and it is fixable, but only if you go in knowing it exists.

I am not arguing against the tool. It solves a real problem well, and it is more honest about its own numbers than most repos on any trending board. I am arguing that the verification step is missing by design, and you should add it back.

How it actually works

The pipeline is compile-time, and that is the whole design bet.

Extraction runs locally through whatever is installed, tried in order per format. For prose-heavy books, pdftotext then pypdf then pdfminer.six, all effectively instant. For technical books with tables and code, Docling at roughly 1.5 seconds per page. The skill asks which kind of book you handed it before it starts, which matters more than it sounds: on the repo's own 103-page benchmark, pdftotext finished in 0.1 seconds and produced zero tables and zero code blocks, while Docling took 164 seconds and produced 48 tables and 36 code blocks from nearly identical token counts. Same book, and one run silently dropped every code listing in it.

Then the model reads the merged text and writes the skill. Chapter summaries run 800 to 1,200 tokens each, structured into core idea, frameworks with their exact names preserved, key concepts, mental models, anti-patterns, takeaways, and cross-references. The glossary caps at 1,500 tokens, patterns at 2,000, the cheatsheet at 1,000. The master SKILL.md stays under 4,000 tokens and front-loads the most important content, on the stated reasoning that compaction keeps the beginning and discards the end.

Before any of that, there is a pre-flight cost estimate you have to confirm. That single step is the most respectful thing in the repo, and it is missing from most skills that spend your tokens on your behalf.

The measured conversions in the README are specific enough to be checked: Think Python 2 at 244 pages and 119K tokens for about $0.88, Working Backwards at 371 pages and 175K for $0.96, Pro Git at 501 pages and 229K for $1.23, Moby-Dick as EPUB at 301K for $1.42, all estimated at Sonnet pricing. Roughly a dollar a book.

The number the README argues down

Most repos lead with their best figure and hope you stop reading. This one leads with 24x to 51x fewer tokens than dumping the book into context, then spends a section explaining why that is the wrong comparison.

The section is called the Discovery Loop Tax, and the argument is good. An agent reading a PDF does not read, it navigates: pulls the table of contents, hits a term it cannot define, fetches more pages, backtracks. Every hop lands in conversation history and gets reprocessed on every later turn. book-to-skill pays that navigation cost once, at compile time.

Then comes the table that undercuts the headline. Against a realistic discovery loop rather than a context dump, the advantage runs 2.4x on a book of small chapters, 6.7x on medium, and 15.6x on a book of large chapters. The caveats are printed right under it: the discovery figures are a model, not a measurement, and a well-tuned agent lands nearer the best case. And then the line most maintainers would have cut: "book-to-skill wins when you return to the knowledge repeatedly; for a single one-off read, a plain PDF agent is fine."

The 24x to 51x is not dishonest, it is just answering a question about a workflow (paste the whole book every session, forever) that a competent engineer would not choose. The 2.4x to 15.6x is the number to plan with. The repo ships tools/discovery_tax.py so you can reproduce it on your own book, which is the right response to anyone quoting either figure at you, including me.

Put this into practice

Start with a book you can grade. Convert something you know cold, or your own internal documentation. Then interrogate the generated skill on three or four things you already know the answer to. You are not testing whether it produces plausible output. It will. You are testing whether the frameworks it named are the frameworks the author actually named.

Run analyze-only first. The skill has a mode that stops after extraction and hands you a report of frameworks, principles, techniques, and anti-patterns it found, without writing any files. On a book that matters, look at that report before you let it generate.

Copy the extraction out before it is deleted. The run leaves /tmp/book_skill_work/full_text.txt behind until Step 10 removes it. Copy it somewhere durable, or edit that step out of your local clone. Without it, every claim in the skill is unfalsifiable, and the whole point of grounding a skill in your own copy of the book was to be able to check it.

Aim it at documents you own. Architecture decision records, runbooks, onboarding guides, internal specs, your own writing. You get the amortization benefit, the copyright question disappears, and you can diff a generated skill against a source you control when the source changes.

Put the generated skill folder in git. It is a set of standing instructions for your agent. Treat a change to it like a change to any other instruction file: reviewable, attributable, revertible.

Keep skills of third-party books private. The repo's own copyright section says this plainly, and it is right. Publishing a generated skill of a copyrighted work can infringe the rights holder regardless of how synthesized the output is.

Honest limitations

The star count will not sit still. The repository page served 12.4k stars, 1.4k forks, 62 watchers, and 89 commits during this run, while the SKILL.md file page served 50 stars, 10 forks, and zero open issues in the same session minutes later. GitHub is serving inconsistent cached views of the same repo, and the Trendshift badge in the README points at a placement from May 23, 2026, not this week. Read the code, not the counter.

The two documents also describe different tools. The README covers folders, globs, ten input formats, folding new material into an existing skill, and install paths for Copilot CLI and Amp alongside Claude Code. The SKILL.md served to me accepts a PDF or EPUB path only, writes to ~/.claude/skills/ only, and has no fold-in mode. One of those is stale, and the one your agent executes is whatever is in your clone. Open the SKILL.md you installed and read it, because that file is the program.

The README says the full extracted source stays on disk for verification. Step 10 of the SKILL.md deletes the working directory. Both statements cannot be true, and the one that runs is the rm -rf.

Chapter detection needs explicit "Chapter N" or "Capítulo N" headings. Pro Git uses section titles and Moby-Dick uses chapter titles and roman numerals, so neither auto-segments, and the README says so. Conversion still works, you just point at sections by hand. Expect this on any book with an unconventional structure, which is a lot of them.

Compression drops the hedging. A chapter squeezed to 1,000 tokens of decision rules loses the conditions under which the author's advice holds, and confident-sounding rules stripped of their caveats are exactly the input that makes an agent wrong with conviction. The instruction to preserve exact framework naming helps. It does not restore the "except when" clauses.

Processing is local, and your model probably is not. The tool never uploads your files. The text you feed a cloud model follows that provider's terms like any other prompt, which the copyright section states plainly. The MIT license covers the converter, not the book.

And it is one maintainer's project on personal time, with a sponsors link and an active PR queue. That is not a criticism, it is a bus factor.

What to do with this

The pattern here is bigger than one converter. We are moving from asking a model what it knows about a book to compiling books into files that steer the model, and a compiled artifact has no bibliography. Nothing in a skill file distinguishes a decision rule the author spent a chapter earning from one a summarizer inferred at two in the morning.

book-to-skill handles this better than most: it forces a cost confirmation, it argues down its own headline number, it prints an honest caveat block, and it tells you not to redistribute what it makes. Then it deletes the only thing that would let you audit the output.

So keep the extraction. Convert a book you can grade before you convert one you cannot. And if you are about to generate skills from a shelf of books for a team of agents, ask who is going to notice when a summarized rule is subtly wrong. It will not be the agent, and it will not be the reader of the pull request.

Sources: virgiliojr94/book-to-skill README and SKILL.md, both read live July 30, 2026; Agent Skills standard; GitHub Changelog on Copilot code review skills and MCP GA; Microsoft Agent Framework skill discovery from MCP servers.