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

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) 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)

npx skills add virgiliojr94/book-to-skill

Option B: Clone and install manually

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 orchestrates both extraction and generation. Run it against any PDF:

# 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.

---

Step 3: Inspect and Debug the Extraction

Before generating files, verify your PDF backend availability:

python3 scripts/extract.py --check

This lists which PDF engines are installed on your system.

For a dry run that analyzes without writing files:

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:

# 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:

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:

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	CLI entry point; orchestrates full pipeline
book_to_skill/utils.py	Multi-source resolution, chapter detection, runner logic
book_to_skill/cli.py	Command-line interface definition
book_to_skill/parsers/pdf.py	PDF-specific parsers with backend selection
SKILL.md	Spec-driven manifest format
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) 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 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 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.

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