book-to-skill: Compile Books into On-Demand Agent Skills, Cut Tokens 24-51x

Project Overview

book-to-skill (GitHub: https://github.com/virgiliojr94/book-to-skill) is an open-source tool that transforms entire books into structured, installable Skills for AI coding agents. As of July 30, 2026, the repository has 12,739 stars and 1,416 forks, with active commits since its creation in early May 2026.

Unlike standard PDF Q&A where an agent loads the whole document into context for each query, book-to-skill performs a one-time "pre-compilation": it extracts text from PDF, EPUB, DOCX, Markdown, HTML, and RTF files, then uses an LLM to organize the content into a modular Skill directory. The resulting structure includes a master SKILL.md (core mental models and chapter index), per-chapter Markdown files under chapters/, plus glossary.md, patterns.md, and cheatsheet.md. At runtime, the agent loads only the ~4,000-token core Skill plus ~1,000 tokens for the relevant chapter, avoiding the "Discovery Loop Tax" of repeatedly searching tables of contents and re-reading context.

Token Savings and Comparison with RAG

The README benchmarks three real books. For a specific question, book-to-skill loads roughly 5,000 tokens total versus the full book context, yielding a 24–51× reduction in input tokens. The author clarifies this advantage applies to repeated use of the same material; compared to a one-off "discovery loop" (where the agent searches the book once), the gain is 2.4–15.6×. For single-use PDF queries, direct reading may be simpler. The key distinction from RAG: RAG excels at broad, shallow retrieval across many documents, while book-to-skill is designed for deep, repeated use of a few high-value sources by pre-structuring frameworks, judgment rules, anti-patterns, and cross-chapter relationships.

Extraction and Generation Pipeline

The process has two stages:

Local extraction : For text-heavy PDFs, it tries pdftotext first, falling back to pypdf or pdfminer.six. For technical books with heavy code, tables, and formulas, Docling is an option (slower but preserves more structure).

Agent structuring : The LLM identifies title, author, table of contents, and chapters, then extracts frameworks, methods, anti-patterns, and examples per chapter, finally generating the index, glossary, pattern list, and cheatsheet.

The project also supports incremental updates: new papers, chapters, or internal documents can be folded into an existing Skill without full regeneration.

Installation Paths

Two distinct installation routes exist:

Agent Skill (full pipeline) : Clone the entire repo into the agent's skill directory. For Claude Code:

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

, then invoke /book-to-skill ~/path/to/book.pdf. GitHub Copilot CLI uses ~/.copilot/skills/book-to-skill or the cross-agent path ~/.agents/skills/book-to-skill. Supported hosts: GitHub Copilot CLI, Amp, and Claude Code.

Python CLI (extraction only) : pip install "book-to-skill[pdf,epub,docx]" installs the text-extraction command-line tool but does not register the /book-to-skill agent Skill. The full book-to-Skill workflow still requires the repo clone.

Author's Verification

On macOS, the author ran the repo's dependency check and Markdown extraction. The README.md was recognized as ~4,424 tokens with 14 chapter-level headings detected. The test suite (163 tests) passed completely. This confirms the extraction entry point, chapter detection, and current codebase are functional, though end-to-end cloud generation quality, speed, and cost will vary with book layout, extractor choice, model, and prompting.

Caveats and Limitations

Chapter splitting reliability depends on consistent heading formatting; books with only chapter numbers, Roman numerals, or complex layouts may need manual review.

Fast text-mode extraction on technical PDFs can fragment tables and code structure.

Copyright: the tool ships no book content, but generated Skills are structured derivatives. Personal study and internal documents are generally acceptable; public distribution of Skills from copyrighted books is not.

Prompt injection risk: any pipeline turning external documents into agent instructions must guard against malicious input. The master branch includes a safety scan during Skill generation, but it is a heuristic check, not a guarantee. Verify sources for internal docs, unfamiliar e-books, and downloaded files.

When to Use

The author recommends book-to-skill for materials you revisit repeatedly — technical references, research papers, brand guidelines, architecture docs. If you've opened the same PDF three times and expect a fourth, the upfront compilation pays off. For one-off questions, direct agent reading is simpler.