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

> Learn to use book-to-skill with Claude Code to convert documents into reusable skills. Slash token costs and get instant slash-command access to book content. Setup and usage guide.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-27

---

**`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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) drives the **spec-driven generator**, which produces a [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```text
/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

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

```

This flag re-runs [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```text
/awesome-book replication strategies

```

Claude automatically routes to [`chapters/ch03-replication.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)** — Core extraction logic with format detection. Call this directly for headless automation.
- **[`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py)** — Entry point that orchestrates extraction, generation, and skill publishing. Contains the `main()` function and argument parsing.
- **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** — Specification document defining the generated skill structure. Claude Code, GitHub Copilot CLI, and Amp all consume this format.
- **[`CLAUDE.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/CLAUDE.md)** — Claude-specific execution rules imported during skill operation. References [`AGENTS.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/AGENTS.md) for cross-platform compatibility.
- **[`docs/usage.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/usage.md)** — Extended examples including batch conversion and custom extractors.

The [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and [`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py).