How to Convert Books and Documents into Agent Skills for GitHub Copilot CLI

book-to-skill transforms any technical book or documentation collection into a structured Agent Skill that GitHub Copilot CLI can query on-demand, consuming 24×–51× fewer tokens than full-text context injection.

The virgiliojr94/book-to-skill repository provides a deterministic pipeline to convert books and documents into agent skills for GitHub Copilot CLI, enabling developers to reference specific chapters and glossary terms without overwhelming the model context. This open-source converter supports PDF, EPUB, DOCX, HTML, RTF, and plain text formats, generating standardized skill packages compatible with any Agent-Skills host including Amp and Claude Code.

The Two-Stage Conversion Pipeline

The conversion process implemented in virgiliojr94/book-to-skill operates through two tightly-coupled stages that transform raw documents into queryable knowledge bases.

Deterministic Extraction Phase

The extraction engine, implemented in scripts/extract.py, reads source files and normalizes raw text while collecting structural metadata such as chapter titles, headings, and glossary terms. The book_to_skill/parsers/ directory contains format-specific implementations that select the best tool for each file type:

• PDF documents: Auto-detects technical PDFs (using docling) versus text-heavy PDFs (using pdftotext for faster processing)
• EPUB files: Processed via ebooklib
• DOCX files: Handled by python-docx
• HTML and RTF: Parsed with dedicated sanitizers

Spec-Driven Generation Phase

The generator follows the canonical SKILL.md specification to create a hierarchical markdown structure:

• SKILL.md: Core mental-model definitions and chapter index
• chapters/chXX-*.md: Individual chapter files loaded on demand
• glossary.md, patterns.md, cheatsheet.md: Reference artifacts

Because the skill uses on-demand loading—only reading the specific chapter file requested by a query—this architecture eliminates the "Discovery Loop Tax" associated with dumping entire books into context.

CLI Installation and Basic Usage

Install the converter as a cross-agent CLI tool, then convert documents with a single command.

Install the tool globally:

npx skills add virgiliojr94/book-to-skill

Verify that required extractors are installed on your system:

python3 scripts/extract.py --check

Convert a PDF or documentation folder into a skill:

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

This creates a skill directory at ~/.copilot/skills/my-book/ containing the structured output.

Query the skill directly from Copilot CLI:

/my-book replication strategies

The CLI entry point in book_to_skill/cli.py provides the /book-to-skill command interface that orchestrates both extraction and generation phases.

Supported Document Formats and Parsing Strategy

The parser package under book_to_skill/parsers/ implements intelligent format detection and tool selection:

• PDF: Automatically routes technical documentation to docling for complex layout preservation, while sending text-heavy novels or simple documents to pdftotext for speed
• EPUB: Extracts semantic structure using ebooklib
• DOCX: Parses Office Open XML via python-docx
• HTML: Sanitizes and extracts main content blocks
• RTF and Plain Text: Handles with lightweight native parsers

Token Efficiency and the Discovery Loop Tax

According to the architecture documented in docs/architecture.md and docs/how-it-works.md, the on-demand skill architecture reduces token consumption by 24× to 51× compared to injecting full book text into the model context. When you query /my-book design patterns, only the relevant chapters/ch05-design-patterns.md file loads into context, rather than the entire manuscript.

Publishing Skills to GitHub

After conversion, publish your skill to a private GitHub repository for team distribution:

/book-to-skill publish ./my-book skill-repo

Install the published skill on another machine or share with teammates:

npx skills add <your-github-user>/skill-repo

Skills remain private by default and conform to the open Agent Skills standard, ensuring compatibility across Copilot CLI, Amp, Claude Code, and other compatible hosts.

Summary

• book-to-skill converts PDF, EPUB, DOCX, and other formats into standardized Agent Skills via scripts/extract.py and the book_to_skill/parsers/ package
• The two-stage pipeline (extraction → generation) creates a SKILL.md specification with on-demand chapter loading
• Token efficiency: On-demand loading consumes 24×–51× fewer tokens than full-text injection
• Skills install via npx skills add and integrate directly into GitHub Copilot CLI as slash commands
• Generated skills publish to GitHub and work across any Agent-Skills-compatible host

Frequently Asked Questions

What file formats does book-to-skill support?

The tool supports PDF, EPUB, DOCX, HTML, RTF, and plain text files. The book_to_skill/parsers/ directory contains dedicated handlers for each format, with PDFs receiving special treatment through auto-detection that routes technical documents to docling and text-heavy content to pdftotext.

How does the tool reduce token consumption?

The generated skills implement on-demand loading architecture. When you query a skill, only the specific chapter file (e.g., chapters/ch05-*.md) loads into the model context rather than the entire book. According to the project documentation, this design reduces token usage by 24× to 51× compared to traditional full-text context injection.

Where are generated skills stored locally?

By default, the book_to-skill command creates skill directories under ~/.copilot/skills/<skill-name>/. This location follows the GitHub Copilot CLI convention for agent skills, allowing immediate access via slash commands without additional configuration.

Can I use these skills with AI agents other than GitHub Copilot CLI?

Yes. The generated skills follow the open Agent Skills specification defined in the repository's SKILL.md file. This standard ensures compatibility with any host implementing the protocol, including Amp, Claude Code, and other Agent-Skills-compatible environments.

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