book-to-skill

book-to-skill is an open-source Python tool that converts technical books, documentation folders, and document collections into structured agent skills compatible with the open Agent Skills standard. It targets developers who want to query book content through AI coding agents without hallucination or manual PDF searching. The project is MIT-licensed and maintained by virgiliojr94 on GitHub, where it has accumulated over 25,000 stars.

What It Is

book-to-skill sits at the intersection of document processing and agent tooling. It takes a PDF, EPUB, DOCX, Markdown, HTML, RTF, or MOBI file — or an entire folder of them — and distills the content into a set of structured Markdown files that an AI agent can load on demand. The output follows the open Agent Skills (SKILL.md) format, which GitHub Copilot CLI, Amp, and Claude Code all read natively. The core idea is that structuring cost is paid once at conversion time, so every subsequent agent query stays proportional to the answer rather than re-navigating the whole document.

How the Conversion Pipeline Works

The pipeline has two halves: a deterministic Python extractor and a spec-driven generator.

• Extractor (scripts/extractor/) handles format detection, optional-dependency probing, and per-format parsers for PDF (via pdftotext, pypdf, pdfminer.six, or docling for technical books with code and tables), EPUB (ebooklib + BeautifulSoup4), DOCX (python-docx), HTML, RTF, MOBI (Calibre), and plain text/Markdown/reStructuredText/AsciiDoc with no extra dependencies.
• Generator follows the SKILL.md spec to produce a full skill directory: a core SKILL.md (~4,000 tokens), per-chapter files (~1,000 tokens each, loaded on demand), a glossary.md, a patterns.md, and a cheatsheet.md.
• Chapter files are only loaded when the user asks about that topic, keeping the active context small.

The README reports a measured 24×–51× reduction in tokens compared to dumping a full book into context, attributed to eliminating what the project calls the "Discovery Loop Tax" — the repeated ToC fetches and backtracking a PDF-reading agent performs on every turn.

Supported Inputs and Use Cases

The tool accepts more than books. Any structured prose that a developer re-opens frequently is a candidate:

• Internal documentation — architecture decision records, runbooks, onboarding guides, entire docs/ folders
• Brand and design systems — voice guidelines, component principles, tone-of-voice documents
• Research clusters — stacks of papers plus personal notes, merged into a single skill and updated as new material arrives
• Specs and standards — RFCs, API contracts, compliance documents

The fold-in update mode lets users add new sources to an existing skill without rebuilding from scratch.

Installation and Agent Compatibility

Installation is a single command via the cross-agent skills CLI:

npx skills add virgiliojr94/book-to-skill

Alternatively, the repository can be cloned directly into the appropriate skills directory (~/.copilot/skills/ for Copilot CLI, ~/.agents/skills/ for Amp, ~/.claude/skills/ for Claude Code). After conversion, the tool can optionally publish the generated skill to a private GitHub repository so any host can install it with npx skills add.

A --check flag on the extractor script prints which optional extractors are installed for every supported format and the exact install command for anything missing.

Update: v1.4.0

The latest release is v1.4.0, published on 2026-08-10. The repository was last pushed on 2026-08-26, indicating active maintenance. The project also ships a tools/validate_skill.py utility that checks a generated SKILL.md against host-specific rules (with --lens flags for claude, copilot, and amp), and a tools/discovery_tax.py script that measures token cost versus context-dump and discovery-loop baselines. A Russian-language README (README.ru.md) is included, reflecting multilingual contributor activity noted in the changelog.