How to Convert Technical Books into Agent Skills for Copilot CLI

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, the extractor parses source files and produces a clean monolithic full_text.txt alongside 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
• Prose-heavy PDFs fall back to pdftotext or pypdf
• EPUB files are processed by 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 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 (steps 0-10). It emits:

• A core 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, 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:

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

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:

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

Querying Skills in Copilot CLI

After conversion, reference the skill in natural language:

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 and measured by 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 removes zero-width and Unicode-tag characters
• 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 — Core CLI parsing and multi-source resolution
• book_to_skill/parsers/pdf.py — Technical PDF handling with format detection
• book_to_skill/parsers/epub.py — EPUB extraction pipeline
• SKILL.md — Generator specification (steps 0-10)
• docs/architecture.md — Component diagrams and design principles
• docs/usage.md — Complete CLI reference

Summary

• Book-to-Skill uses a two-stage pipeline: the Extractor (scripts/extract.py) parses diverse formats, and the Generator creates structured 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 and 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 and 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. If chapters fail validation due to encoding issues or content filtering, check the logs and run 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 specification provides a universal interface for agent consumption.

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