# How to Convert Technical Books into Agent Skills for Copilot CLI

> Convert technical books into agent skills for Copilot CLI using Book-to-Skill. Effortlessly query your documentation on demand with this powerful tool.

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

---

**Book-to-Skill transforms any technical book (PDF, EPUB, DOCX, HTML, or RTF) into a structured Agent Skill that GitHub Copilot CLI, Amp, or Claude Code can query on-demand through a deterministic two-stage extraction and generation pipeline.**

The virgiliojr94/book-to-skill repository provides a complete toolchain to convert technical books into compact, queryable Agent Skills. By converting static documentation into structured skills, you enable AI assistants to reference specific frameworks, decision rules, and anti-patterns without exceeding token limits. This guide explains how to convert technical books into agent skills for Copilot CLI using the actual source implementation.

## Understanding the Two-Stage Conversion Pipeline

The conversion process separates content extraction from skill generation, ensuring deterministic output and optimal runtime performance.

### Stage 1: The Extractor (Format-Aware Parsing)

In [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), the extractor parses source files and produces a clean monolithic [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) alongside [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json). The implementation in `book_to_skill/parsers/` automatically selects the best tool for each format:

- **Technical PDFs** use `docling` via [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py)
- **Prose-heavy PDFs** fall back to `pdftotext` or `pypdf`
- **EPUB files** are processed by [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) using `ebooklib` and `beautifulsoup4`

The extractor records pages, chapters, word counts, and Table-of-Contents structure. It also strips invisible Unicode characters through [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) to prevent XML entity attacks and subprocess injection vectors.

### Stage 2: The Generator (Spec-Driven Output)

The generator consumes the extracted text and follows the step-by-step specification in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (steps 0-10). It emits:

- A core [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file (approximately 4K tokens)
- Per-chapter markdown files (approximately 1K tokens each)
- A glossary, pattern collections, and cheatsheet

Output validation occurs via [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py), which checks compliance with host-specific rules for `~/.copilot/skills/<slug>/` directories.

## Command-Line Conversion Workflow

### Basic Conversion

Convert a single PDF into a Copilot-CLI skill:

```bash
/book-to-skill ./my-technical-book.pdf my-book-skill

```

This creates the skill directory structure under `~/.copilot/skills/my-book-skill/`.

### Python API for Advanced Scripting

For programmatic control, import the CLI module directly from [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py):

```python
from book_to_skill.cli import main as b2s_cli

# Run extractor and generator with explicit parameters

b2s_cli([
    "./my-technical-book.pdf",
    "--skill-name", "my-book-skill",
    "--check"  # Lists available extractors before processing

])

```

### Incremental Updates

Add new material to existing skills without rebuilding:

```bash
/book-to-skill ./additional-chapter.epub my-book-skill --update

```

## Querying Skills in Copilot CLI

After conversion, reference the skill in natural language:

```bash
copilot chat "/my-book-skill replication strategies"

```

The runtime loads only the requested chapter file, keeping the active context minimal while providing full access to the book's technical content.

## Security and Performance Architecture

### Compile-Time Cost Reduction

According to [`docs/performance.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/performance.md) and measured by [`tools/discovery_tax.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/discovery_tax.py), the chapter-on-demand approach yields a **24×–51× token reduction** compared to dumping the entire book into context. Heavy parsing happens once during extraction; queries pull only necessary chapters, maintaining a tiny runtime token budget.

### Security Hardening

The toolchain implements defense-in-depth across multiple files:

- [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) removes zero-width and Unicode-tag characters
- [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) audits output for injection vectors
- Input validation in `book_to_skill/parsers/` prevents XML entity attacks

## Key Implementation Files

- [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) — Core CLI parsing and multi-source resolution
- [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) — Technical PDF handling with format detection
- [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) — EPUB extraction pipeline
- [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) — Generator specification (steps 0-10)
- [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) — Component diagrams and design principles
- [`docs/usage.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/usage.md) — Complete CLI reference

## Summary

- Book-to-Skill uses a two-stage pipeline: the **Extractor** ([`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)) parses diverse formats, and the **Generator** creates structured [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) files following the specification
- Runtime token efficiency achieves **24×–51× reduction** by loading chapters on-demand rather than injecting full text into context
- Security measures in [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) and [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) mitigate Unicode attacks and injection vectors
- Generated skills install to `~/.copilot/skills/<slug>/` for immediate use with Copilot CLI
- Incremental updates via `--update` flag allow adding new sources without rebuilding existing skills

## Frequently Asked Questions

### What file formats does Book-to-Skill support?

The extractor in `book_to_skill/parsers/` handles PDF, EPUB, DOCX, HTML, and RTF files. According to the source code in [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) and [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py), the system automatically selects optimal parsing strategies—using `docling` for technical PDFs with complex layouts and `pdftotext` for prose-heavy documents.

### How does the tool handle copyright concerns?

Rather than copying raw excerpts, the generator captures frameworks, decision rules, and anti-patterns as structured data. This transforms the source material into a new creative work while respecting copyright boundaries and ensuring practical utility for AI assistance.

### Why is my generated skill missing certain chapters?

The generator validates output against host-specific rules using [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py). If chapters fail validation due to encoding issues or content filtering, check the logs and run [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) to identify sanitization errors or Unicode anomalies that may have triggered exclusion.

### Can I use this with AI assistants other than Copilot CLI?

Yes. While the default output targets `~/.copilot/skills/<slug>/` for GitHub Copilot CLI, the structured markdown format works with Amp, Claude Code, and any agent supporting skill directories. The [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) specification provides a universal interface for agent consumption.