book-to-skill

book-to-skill is a Python tool that converts a technical book, folder of documents, or set of files into a structured skill for AI coding agents. It's built for developers who use GitHub Copilot CLI, Amp, or Claude Code and want their agent to reference a book or internal doc set accurately, without re-reading the whole thing every time or getting hallucinated answers.

The core idea: instead of dumping a PDF into an agent's context window, book-to-skill extracts the text once and restructures it into a SKILL.md file plus per-chapter files, a glossary, a patterns file, and a cheatsheet. The agent loads the core skill file first, then pulls in individual chapter files only when a question touches that chapter. This keeps token usage proportional to the question instead of the size of the source document.

Key features

• Format support: handles PDF, EPUB, DOCX, Markdown, HTML, RTF, and MOBI/AZW inputs, with format-specific extractors and fallbacks for each.
• On-demand chapter loading: chapter files don't count against the loaded skill's token budget until the agent actually needs them.
• Structured output, not summaries: generates a mental-model overview, glossary, pattern list, and decision cheatsheet rather than a condensed retelling.
• Open Agent Skills standard: produces a standard SKILL.md readable by any compliant host (Copilot CLI, Amp, Claude Code).
• Cross-format inputs: works on a single file, a folder, or a glob, so it can fold an entire docs/ directory or a stack of research papers into one skill.
• Update / fold-in mode: existing skills can be updated as new source material arrives instead of regenerating from scratch.
• Local processing: extraction runs on your machine; the tool doesn't upload your files anywhere itself.
• Dependency self-check: python3 scripts/extract.py --check reports which optional extractors are installed and what to install for missing formats.

Ideal use cases

• You own a technical book (PDF or EPUB) you reference occasionally and want your coding agent to answer questions from it accurately instead of guessing.
• Your team has a docs/ folder of architecture decision records, runbooks, or onboarding guides that people re-read but never fully internalize.
• You maintain a brand or design-system doc that people should query instead of skimming a long PDF.
• You have a cluster of research papers and personal notes you want merged into a single, queryable reference.
• It's not a fit if your source is a scanned PDF with no text layer (you'll need to run OCR first with a tool like ocrmypdf), or if you want to redistribute a generated skill of a copyrighted book (the README explicitly discourages that; keep skills of third-party copyrighted books private).
• It's also not the right tool if you just need a one-off summary; this is meant for material you reference repeatedly, not material you read once.

Installation

Install via the cross-agent skills CLI, which works with any supported host:

npx skills add virgiliojr94/book-to-skill

Or clone it manually into your agent's skills folder:

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# Copilot CLI: ~/.copilot/skills/
# Amp / cross-agent: ~/.agents/skills/

Once installed, invoke it from your agent with /book-to-skill <path|folder|glob> [skill-name]. Some formats need optional extractors depending on the source type:

# check what's installed and what's missing
python3 scripts/extract.py --check

# example installs
sudo apt install poppler-utils     # PDF via pdftotext
pip3 install docling               # PDF with tables/code
pip3 install ebooklib beautifulsoup4  # EPUB
pip3 install python-docx           # DOCX

Plain text, Markdown, reStructuredText, and AsciiDoc need no extra dependencies. Scanned PDFs with no text layer require OCR first (ocrmypdf input.pdf output.pdf) before conversion.