# book-to-skill

> Convert any technical book, document folder, or collection of sources into a structured agent skill ready to use in GitHub Copilot CLI, Amp, or Claude Code.

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.

## Features
- Convert PDF, EPUB, DOCX, Markdown, HTML, RTF, and MOBI files to agent skills
- Generates SKILL.md, per-chapter files, glossary, patterns, and cheatsheet
- On-demand chapter loading to minimize active context tokens
- 24×–51× fewer tokens than context-dumping, per project benchmarks
- Supports folder and glob inputs for multi-document skills
- Update/fold-in mode to add new sources to existing skills
- Optional GitHub publishing of generated skills
- Skill validation tool with per-host lens (Claude, Copilot, Amp)
- Discovery Loop Tax measurement tool
- Compatible with GitHub Copilot CLI, Amp, and Claude Code via Agent Skills standard
- Scanned PDF detection with OCR guidance
- Automatic extractor selection based on book type (technical vs. text-heavy)
- Dependency check command (--check) for all supported formats
- MIT-licensed and fully local processing

## Integrations
GitHub Copilot CLI, Amp, Claude Code, Agent Skills open standard, pdftotext (poppler), pypdf, pdfminer.six, docling, ebooklib, BeautifulSoup4, python-docx, striprtf, Calibre (ebook-convert), ocrmypdf, npx skills CLI

## Platforms
LINUX, API, CLI

## Pricing
Open Source

## Version
v1.4.0

## Links
- Website: https://github.com/virgiliojr94/book-to-skill
- Documentation: https://github.com/virgiliojr94/book-to-skill/blob/master/docs/usage.md
- Repository: https://github.com/virgiliojr94/book-to-skill
- EveryDev.ai: https://www.everydev.ai/tools/book-to-skill