book-to-skill

book-to-skill turns documents into Agent Skills, the SKILL.md folder format that GitHub Copilot CLI, Amp, Claude Code, Hermes Agent, OpenCode and OpenClaw all read. It is two halves that the repository refuses to blur. A deterministic Python extractor takes a file, a folder, a glob or a list of paths — PDF, EPUB, DOCX, HTML, RTF, MOBI or plain text — and writes a merged full_text.txt and a metadata.json holding pages, words, tokens, chapters and table of contents; every format has a standard-library fallback, and one unreadable source is skipped rather than killing the batch. Then the reader’s own coding agent follows a 55,009-byte specification to distil that text into a folder: a core of mental models and a topic index at about 4,000 tokens, one file per chapter at about 1,000 tokens each, plus a glossary, a patterns file and a decision cheatsheet. Around that sit analyze-only, fold-in and publish modes. The claim underneath is a token bill: an agent reading a PDF re-processes the table of contents on every turn, and this pays that structuring cost once, at conversion.

Who built itA solo maintainer whose account wrote 89 of the repository’s 202 commits. GitHub lists 41 contributors in all, and the largest after the owner is dex0shubham with 23, then Hotragn with 11, Stamina9 with 10 and a dependency bot with nine. The owner’s commits are signed under three names — Virgilio Junior, Virgilio Borges and the account handle — which is why the per-name counts split. Eighty-six commits carry a co-author trailer, and most of the names in them are tools rather than people: Claude Opus 5 on 21, Claude Opus 4.8 on 16 with a further seven on a million-token context, Copilot on nine, Amp on three, Cursor on one.

1. 01

   Two halves: a deterministic extractor and a 55,009-byte specification

   The architecture document states the split as a rule, not a description: a deterministic Python extractor, and a spec-driven generator that is whatever coding agent the reader already runs. SKILL.md is the second half, and it is the largest thing in the tree that is read as prose — 55,009 bytes, smaller only than the extractor’s 65,957-byte utils.py and a 111,646-byte test module. It is written as numbered steps: Step 1.5 asks whether the book is technical or text-heavy, Step 2.6 is a read-eval-print loop for large books that greps and slices instead of re-reading them, Step 7 writes the per-chapter summaries on a budget that is the product of book type and depth, and Step 9.5 scans the files that were just written. The extractor half is more conventional: parsers/ is eight modules and 38 KB, sanitize.py is 6,357 bytes, and scripts/extract.py survives as a 1,333-byte shim so that older invocations keep working. Its output is two files in a per-run work directory — merged text with source markers, and metadata with the counts — deleted when the conversion ends. The command surface is wider than one command: analyze-only, generate-from-analysis and an update or fold-in mode that merges new material into a skill that already exists, plus an optional publish step that puts the result into a private GitHub repository so any host can install it with npx skills add.

2. 02

   What a book costs to read, and what the conversion costs

   The extractor picks its tool by book type instead of trying everything. Prose goes through pdftotext, falling back to pypdf and then pdfminer.six, all three effectively instant. Books with tables and formulas go through Docling at roughly 1.5 seconds a page, and the repository publishes the trade in one table: on a 103-page technical book run on CPU only, pdftotext finished in 0.1 seconds and produced 27K tokens with no tables and no code blocks, while Docling took 164 seconds and produced the same tokens, 1.2% more, with 48 tables and 36 code blocks kept as markdown. Four real conversions follow, with pages, extracted tokens, auto-detected chapters and a one-pass estimate priced on Claude Sonnet 4.5 at three dollars in and fifteen dollars out per million tokens: Think Python 2 at 244 pages, 119K tokens, nineteen chapters and about eighty-eight cents; Working Backwards at 371 pages, 175K tokens, ten chapters and about ninety-six cents; Pro Git at 501 pages and 229K tokens; and Moby-Dick as an EPUB at 301K tokens. The last two carry the honest footnote: automatic chapter detection needs an explicit “Chapter N” or “Capítulo N” heading, Pro Git uses section titles and Moby-Dick uses chapter titles and roman numerals, so neither segments on its own — extraction and conversion still work, and the reader points at sections by hand.

3. 03

   Chapter detection is where the project actually lives

   A chapter count decides what the generated skill looks like, and thirteen of the thirty issues and pull requests in the report concern what a chapter is or how it is counted. The multilingual half arrived as the same patch over and over: Malayalam, Gujarati and Odia headings, each adding a pattern, a map from native digits to Latin ones, a dispatch branch placed next to the existing Brahmic blocks and tests beside their neighbours, with the contributor behind three of them at 23 commits, second only to the owner. The other half is false positives, and they are the more interesting ones. A sentence wrapped at the column limit whose continuation line began with a cross-reference was counted as a chapter; so was a fenced unified diff; and on the structural path the rule took the shallowest heading depth with at least two distinct titles, which counted a preface, a table of contents, an appendix, a glossary, a bibliography and an index along with twenty real chapters. Two headings called “Part” collapsed the count in the other direction, reporting two chapters for a book of ten. The maintainer reproduced each with synthetic input and split them apart: numeric false positives in one change, structural selection and the sample of headings that produced the count in another, and a blanket prefix exclusion refused because it would have deleted a genuine “Introduction” chapter.

4. 04

   Eight reports in one evening, each reproduced against the real library

   Between 2026-09-30 and 2026-10-01 one account filed eight of the report’s last items, each reproduced against the real dependency, not a mock. ebooklib 0.20 extracts an EPUB in manifest order, ignoring the declared spine and reordering chapters the standard-library fallback keeps in order. python-docx 1.2.0 emits every top-level paragraph before every table, so a table between chapters one and two lands at the end. On Windows, a Markdown source with ordinary CRLF endings is persisted with doubled carriage returns, so a plain read then sees a blank line between every line, though the count printed before the write is right. BeautifulSoup inserts a newline between every text node, inline ones included, so a synthetic two-chapter source containing Chapter <span>1</span> yields zero chapters and exits cleanly. Three more aim at the guard that lets an interrupted run reuse its corpus: reuse_is_safe() says the work directory is intact and every source matches even when the extracted text has been deleted, emptied or replaced, and when two inputs in different directories share a basename and a hash, a substituted third file is never examined. The reporter is careful about the claim — what fails is the helper’s verdict, not a known bad skill — and the gap is the seam an earlier change left: every source’s name and hash are recorded and checked, nothing checks the output.

5. 05

   What it refuses to do with the file, and what it refuses to ship

   Scanned pages are handled by stopping, not by trying harder: a PDF with no text layer is caught on the first pages and exits with an explanation rather than grinding through the book to produce an empty skill; the README says to run ocrmypdf first. Copyright is the same kind of decision, and the design rests on it: the tool ships no book content, extraction runs on the reader’s machine, and a generated skill is a structured derivative — framework names, definitions, takeaways — because the specification forbids copying raw passages at all; its own tests use synthetic or licensed fixtures for the same reason. The security work follows the document’s path into an agent: invisible and zero-width characters are stripped from every parser’s output before anything is measured; a DOCX part declaring a DTD is rejected before parsing; paths are absolutised before reaching pdftotext or ebook-convert, so a name starting with a dash cannot be read as a flag; and the generator ends with an advisory scan that names a rule and a location, never the matched text. When a reader showed that nine Default_Ignorable code points survived the scrub, the maintainer confirmed the gap, refused a blanket format-character filter because it would strip semantic controls, called it a coverage gap and not a successful prompt injection, and asked for the rest through private vulnerability reporting.

6. 06

   Five releases, a quiet September, and 33,182 stars the material does not explain

   The first commit is stamped six seconds before the repository itself, so the project arrived from a working copy rather than the platform. From there: 202 commits in 151 days, in a monthly shape that reads like a response rather than a schedule — twenty in May, sixty-two in June, nineteen in July, seventy-four in August, twenty-seven in September. Five releases came out of the first three months, none since: v1.0.0 on 2026-06-08, v1.1.0 four days later, v1.2.0 on 2026-06-17, an installable package plus multilingual chapter detection, v1.3.0 on 2026-07-30 and v1.4.0 on 2026-08-10. September brought twenty-seven commits, a long stretch of triage and no release — the last commit is a contributor’s EPUB spine fix merged on 2026-09-29 — so the record says active, not finished. A reviewer also showed the translated READMEs had drifted past the English destination policy, each pinning the revision it was made from with nothing enforcing the pin, and the fix was accepted on two conditions: the pin may only move to a source actually reviewed, and no check may depend on git history, which shallow checkouts would fail. The material contains no account of the 33,182 stars; the only traces of how it travelled are two Trendshift badges for repository 27038, a companion use-cases repository whose index takes a one-line pull request, and 3,466 forks against 41 contributors.