How to Use book-to-skill with Claude Code: Complete Setup and Usage Guide

book-to-skill converts PDFs, EPUBs, DOCX, and other document formats into reusable Claude Code skills that slash token costs by 24-51× and enable instant slash-command access to book contents.

The book-to-skill project transforms static documents into Agent Skills — a structured format that Claude Code can query on demand. Instead of repeatedly passing an entire PDF into context, you generate a skill once and invoke specific chapters via slash commands. This guide covers installation, conversion workflows, and practical usage patterns based on the virgiliojr94/book-to-skill source code.

What book-to-skill Does and Why It Matters

Traditional approaches to referencing books in Claude Code require either copying text blocks or re-uploading files. book-to-skill eliminates this friction through a three-layer pipeline: extraction, generation, and runtime loading.

Extraction Layer

The deterministic extractor at scripts/extract.py detects your file type and selects the appropriate parsing tool. It supports PDF (pdftotext), EPUB/MOBI (ebooklib), DOCX (docling), plus HTML and Markdown. Output includes clean text and structured metadata that feeds into the generation stage.

Generation Layer

The CLI in book_to_skill/cli.py drives the spec-driven generator, which produces a SKILL.md bundle following the open Agent Skills format. This bundle contains:

• A table-of-contents index
• Per-chapter markdown files
• A glossary extracted from key terms
• Pattern definitions for common queries
• A quick-reference cheatsheet

Runtime Layer

Claude Code reads skills from ~/.claude/skills/<slug>/. When you invoke /your-book-name, Claude loads only the chapter file matching your query, keeping token usage minimal. The architecture documentation in docs/architecture.md specifies this directory structure and runtime behavior.

Installing book-to-skill in Claude Code

Add book-to-skill to your Claude Code environment as a global skill:

# Clone directly into Claude's skill directory

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

This one-time installation exposes the /book-to-skill slash command in any Claude Code session. The docs/install.md file confirms this path and provides fallback instructions for non-standard Claude installations.

Converting Documents to Skills

Basic Conversion

Inside an active Claude Code session, run:

/book-to-skill /path/to/awesome-book.pdf

The command executes the full pipeline: extraction → generation → skill deployment. Upon completion, a new directory appears at ~/.claude/skills/awesome-book/ containing SKILL.md and chapter files in chapters/.

Supported Input Formats

Format	Extractor Tool	Notes
PDF	pdftotext	Best for scanned books with text layers
EPUB, MOBI	ebooklib	Preserves chapter structure natively
DOCX	docling	Handles complex formatting
HTML	Built-in	Strips tags, preserves hierarchy
Markdown	Passthrough	Minimal processing needed
RTF	Built-in	Legacy document support

Updating an Existing Skill

When the source document changes, refresh the skill without re installing:

/book-to-skill /path/to/awesome-book.pdf --update

This flag re-runs scripts/extract.py and regenerates only modified chapters, preserving your existing skill configuration.

Using Generated Skills

Slash Command Invocation

After conversion, invoke your book by its slug:

/awesome-book replication strategies

Claude automatically routes to chapters/ch03-replication.md (or whatever chapter matches "replication strategies") and answers using the exact source text. No token-heavy PDF re-upload required.

Query Routing Behavior

The Agent Skills format in SKILL.md defines how Claude maps natural language queries to chapter files. The index file contains metadata tags that Claude uses for routing decisions. This design ensures that multi-chapter queries fetch only relevant sections, not the entire book.

Key Source Files and Architecture

Understanding the codebase helps with customization and debugging:

• scripts/extract.py — Core extraction logic with format detection. Call this directly for headless automation.
• book_to_skill/cli.py — Entry point that orchestrates extraction, generation, and skill publishing. Contains the main() function and argument parsing.
• SKILL.md — Specification document defining the generated skill structure. Claude Code, GitHub Copilot CLI, and Amp all consume this format.
• CLAUDE.md — Claude-specific execution rules imported during skill operation. References AGENTS.md for cross-platform compatibility.
• docs/usage.md — Extended examples including batch conversion and custom extractors.

The docs/architecture.md diagram illustrates how these components interact across Claude Code, Copilot CLI, and Amp environments.

Performance and Cost Benefits

The README documents 24-51× token reduction compared to naive PDF-in-context approaches. This efficiency comes from:

1. One-time extraction — Parse the book once, not per-query
2. Selective chapter loading — Claude fetches only relevant sections
3. Structured indexing — Pre-computed metadata eliminates search overhead

For technical books exceeding 500 pages, this translates to substantial cost savings and faster response times.

Summary

• Install once with git clone into ~/.claude/skills/book-to-skill
• Convert documents via /book-to-skill <path> inside Claude Code sessions
• Invoke skills with /<slug> <query> to load specific chapters on demand
• Update incrementally using --update when source files change
• Reduce tokens 24-51× compared to repeated PDF uploads

The virgiliojr94/book-to-skill toolchain integrates cleanly with Claude Code's native skill system, turning static documents into queryable knowledge bases.

Frequently Asked Questions

What file formats does book-to-skill support?

PDF, EPUB, DOCX, HTML, Markdown, RTF, and MOBI. The scripts/extract.py module auto-detects the format and invokes the appropriate parser. Each format has optimized extraction logic to preserve structure and minimize noise.

Where does Claude Code store generated skills?

Skills reside in ~/.claude/skills/<slug>/ as documented in docs/architecture.md and docs/install.md. The <slug> derives from the input filename. Claude Code monitors this directory and loads available skills on startup.

Can I use book-to-skill skills in other AI tools?

Yes. The SKILL.md format is an open specification consumed by GitHub Copilot CLI and Amp in addition to Claude Code. Skills generated by book-to-skill are portable across these environments without modification.

How do I troubleshoot a failed extraction?

Check scripts/extract.py output for format-specific errors. For PDFs, ensure pdftotext is installed and the PDF has a text layer (not image-only). For DOCX, verify docling dependencies. Run with --verbose to see per-stage diagnostics in the CLI at book_to_skill/cli.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}