# How to Convert a PDF Book into an Agent Skill: The book-to-skill Workflow Explained

> Convert your PDF book into a reusable agent skill using the book-to-skill CLI. Extract text, detect chapters, and load on-demand into Copilot CLI, Amp, or Claude Code effortlessly.

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

---

**Use the `book-to-skill` CLI tool to extract text from any PDF, detect chapters, and generate a structured Agent Skill that loads on-demand in Copilot CLI, Amp, or Claude Code.**

The open-source `book-to-skill` repository by virgiliojr94/book-to-skill provides a deterministic pipeline for converting static PDF documents into queryable, agent-compatible knowledge bases. This guide walks through the exact process, from PDF conversion to skill deployment, grounded in the actual source code implementation.

---

## Overview of the Conversion Pipeline

Converting a PDF book into an agent skill happens in two deterministic stages:

1. **Extraction** – Parse the PDF using backend-specific engines, clean the text, and produce a normalized, chapter-aware representation
2. **Generation** – Feed that normalized content into a spec-driven generator that writes the **Skill Manifest** ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)) and per-chapter markdown files

The raw PDF never leaves your machine. All processing is local, private, and token-efficient.

---

## Step 1: Install book-to-skill

You have two installation paths depending on your environment.

**Option A: One-line install via npx (recommended)**

```bash
npx skills add virgiliojr94/book-to-skill

```

**Option B: Clone and install manually**

```bash
git clone https://github.com/virgiliojr94/book-to-skill.git
cd book-to-skill
pip install -e .

```

Both methods register the `book-to-skill` command globally.

---

## Step 2: Run the PDF-to-Skill Conversion

The CLI entry point in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) orchestrates both extraction and generation. Run it against any PDF:

```bash

# Basic conversion with auto-detected backend

book-to-skill ./my-book.pdf my-book

```

The tool will prompt you to classify the book:

- **Technical** – Triggers the `docling` backend for structured technical content with diagrams, tables, and code
- **Text-heavy** – Uses `pdftotext`, `pypdf`, or `pdfminer.six` for prose-heavy documents

The modular parsers live in `book_to_skill/parsers/`, selected via resolver logic in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py).

---

## Step 3: Inspect and Debug the Extraction

Before generating files, verify your PDF backend availability:

```bash
python3 scripts/extract.py --check

```

This lists which PDF engines are installed on your system.

For a dry run that analyzes without writing files:

```bash
book-to-skill ./my-book.pdf --analyze-only

```

---

## Step 4: Use the Generated Agent Skill

The output directory structure follows the open Agent Skills standard:

```

~/.copilot/skills/
└── my-book/
    ├── SKILL.md              # Skill manifest

    ├── chapters/
    │   ├── ch01-introduction.md
    │   ├── ch02-*.md
    │   └── ...
    ├── glossary.md
    └── patterns.md

```

Invoke the skill from any supported agent:

```bash

# In Copilot CLI, Amp, or Claude Code

/my-book explain the caching strategy from chapter 4

```

The agent loads only the relevant chapter file on-demand, answering from actual content rather than hallucinating.

---

## Python API Usage

Load and query a skill programmatically:

```python
from copilot import Agent

agent = Agent(skill_slug="my-book")
response = agent.ask("What are the key patterns in chapter 7?")
print(response)

```

---

## Advanced: Update an Existing Skill

When your PDF receives a new edition, merge changes without rebuilding from scratch:

```bash
book-to-skill ./my-book-v2.pdf my-book --update

```

This **fold-in mode** preserves your customizations while incorporating new content.

---

## Key Source Files

Understanding the codebase helps with customization and debugging:

| File | Purpose |
|------|---------|
| [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) | CLI entry point; orchestrates full pipeline |
| [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) | Multi-source resolution, chapter detection, runner logic |
| [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) | Command-line interface definition |
| [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) | PDF-specific parsers with backend selection |
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | Spec-driven manifest format |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | Validates generated skills against host rules |

---

## Summary

- **Install** via `npx skills add` or manual clone
- **Convert** with `book-to-skill <pdf> <slug>` — choose technical or text-heavy mode
- **Extract** using `pdftotext`, `pypdf`, `pdfminer.six`, or `docling` backends
- **Generate** a standard Skill Manifest ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)) plus chapter files
- **Query** via `/slug <question>` in any compatible agent

The entire workflow runs locally. No PDF content is transmitted to remote APIs during conversion.

---

## Frequently Asked Questions

### What PDF formats does book-to-skill support?

The tool supports any PDF renderable by its four backends: `pdftotext` (fastest for plain text), `pypdf` (Python-native), `pdfminer.six` (precise layout preservation), and `docling` (best for technical books with tables, diagrams, and code blocks). Backend selection happens automatically based on your classification or can be forced with flags.

### Where are the generated skill files stored?

By default, skills install to `~/.copilot/skills/<slug>/` for Copilot CLI compatibility. Other hosts like Amp or Claude Code scan equivalent paths. You can override the output directory with `--output-dir`.

### Can I edit the generated SKILL.md manually?

Yes. [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) is plain markdown following the open Agent Skills specification. After generation, you can customize descriptions, add examples, or refine the chapter index. Run [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) afterward to ensure compliance with your target host.

### How do I verify my skill works before sharing it?

Use the built-in validator: `python3 tools/validate_skill.py ~/.copilot/skills/my-book/`. This checks manifest syntax, required fields, and host-specific rules without requiring a live agent session.