book-to-skill — Turn Technical Books into AI Agent Skills

Overview

book-to-skill (by virgiliojr94) is a Python tool that converts technical books, documentation, and structured documents into AI agent skills — compact, structured reference materials that AI coding assistants like Claude Code, GitHub Copilot CLI, and Amp can load on demand.

The core insight: dumping an entire book into context is wasteful. A single book can exceed 100K tokens, far more than an agent needs. book-to-skill distills each book into a structured skill with a ~4,000-token core file and per-chapter files (~1,000 tokens each) loaded only when needed — claiming 24×–51× fewer tokens than raw book ingestion.

With approximately 10,700 GitHub stars and rapid daily growth (366 stars/day at peak), book-to-skill has become a popular tool in the Claude Code ecosystem for turning reference materials into agent-accessible knowledge.

Features

• Multi-Format Support: PDF, EPUB, DOCX, HTML, RTF, MOBI/AZW/AZW3, Markdown, TXT, reStructuredText, and AsciiDoc.
• Structured Skill Output: Generates a SKILL.md core file (~4,000 tokens), per-chapter files (~1,000 tokens each), a glossary, patterns summary, and cheatsheet.
• 24×–51× Token Reduction: Agent loads only relevant sections on demand instead of the full book.
• On-Demand Chapter Loading: Chapters are loaded only when the agent queries them, keeping context lean.
• Agent Skills Standard: Compatible with any agent following the open Agent Skills standard.
• Folder and Glob Support: Not just books — handles folders of documents and research clusters.
• Framework Extraction: Pulls out "frameworks, decision rules, anti-patterns" rather than producing simple summaries.
• MIT License: Free for personal and commercial use.

Installation

As a Claude Code Skill (Recommended)

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

This registers the /book-to-skill slash command directly in Claude Code.

Standalone CLI

pip install "book-to-skill[pdf,epub,docx]"

Note: The pip install provides the CLI only and does not register the slash command.

Quick Start

# Convert a book to a skill
/book-to-skill ~/Documents/Design-Patterns.pdf

# Or convert an EPUB
/book-to-skill ~/Downloads/Architecture-Patterns.epub

# Convert a folder of documents
/book-to-skill ~/research/papers/

After conversion, query the skill directly:

/your-book-slug replication
/your-book-slug ch05
/your-book-slug "what chapters do you have?"

Core Concepts

• Distillation: The tool parses the input document and distills the essential knowledge — frameworks, patterns, decision rules, anti-patterns — into structured markdown files.
• Core + Chapter Structure: The SKILL.md core file contains the most important concepts (~4,000 tokens). Per-chapter files hold deeper detail and are loaded on demand.
• On-Demand Loading: The agent loads only the chapters relevant to the current question, avoiding context waste.
• Glossary + Patterns: Extracted glossaries and pattern summaries give the agent quick-reference knowledge without needing to read full chapters.

Advanced Features

Folder Mode

Point book-to-skill at a folder to convert multiple documents:

/book-to-skill ~/my-docs/ --output my-docs-skill

Document Cluster Mode

Combine a set of related documents (research papers, specs, RFCs) into a single skill:

/book-to-skill ~/rfcs/*.md --cluster

Format-Specific Backends

• PDF: Uses pdftotext/poppler for text-heavy PDFs; Docling for technical PDFs with tables and code blocks
• EPUB: Uses ebooklib for structural parsing
• Plain Text: Standard library tools for Markdown, TXT, reStructuredText, AsciiDoc

Examples

Converting "Designing Data-Intensive Applications"

/book-to-skill ~/books/Designing-Data-Intensive-Applications.pdf

The agent now has:

• A core skill file summarizing the key architectural patterns
• Per-chapter files on distributed systems, replication, batch processing, etc.
• A glossary of key terms (consistency, availability, partitions, etc.)
• A cheatsheet for quick reference

Querying the Converted Skill

/designing-data-intensive-applications replication
# → Loads only the replication chapter (~1,000 tokens)

/designing-data-intensive-applications "what chapters do you have?"
# → Lists all available chapters

Pros

• ✅ 24×–51× token savings vs. raw book ingestion
• ✅ Works across all Agent Skills standard-compatible agents
• ✅ Broad format support (PDF, EPUB, DOCX, HTML, and more)
• ✅ On-demand chapter loading keeps context lean
• ✅ Simple CLI with slash command integration for Claude Code
• ✅ MIT license, open source

Cons

• ✅ Distillation quality depends on input document structure
• ✅ pip install does not register the slash command
• ✅ PDFs with complex layouts (tables, code) may need Docling
• ✅ No built-in incremental update — re-run to refresh converted skills

When to Use

• Loading reference books into Claude Code — turn any technical book into an on-demand agent skill.
• Building agent knowledge bases — convert documentation, specs, and research into structured skills.
• Reducing token costs — 24×–51× fewer tokens than dumping raw documents into context.
• Team knowledge sharing — convert internal docs into skills that any agent can use.

Resources

• Official Repository
• npm/Claude Code Skill