# How to Convert Books and Documents into Agent Skills for GitHub Copilot CLI > Convert books and documents into GitHub Copilot CLI agent skills with book-to-skill. Save tokens and access documentation efficiently on demand. Learn how to create your own skills today. - Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill) - Tags: how-to-guide - Published: 2026-08-26 --- **`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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) specification to create a hierarchical markdown structure: - [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md): Core mental-model definitions and chapter index - `chapters/chXX-*.md`: Individual chapter files loaded on demand - [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md), [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md), [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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: ```bash npx skills add virgiliojr94/book-to-skill ``` Verify that required extractors are installed on your system: ```bash python3 scripts/extract.py --check ``` Convert a PDF or documentation folder into a skill: ```bash /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: ```bash /my-book replication strategies ``` The CLI entry point in [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and [`docs/how-it-works.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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: ```bash /book-to-skill publish ./my-book skill-repo ``` Install the published skill on another machine or share with teammates: ```bash npx skills add /skill-repo ``` Skills remain private by default and conform to the open [Agent Skills](https://github.com/agentskills/agentskills) 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) and the `book_to_skill/parsers/` package - The two-stage pipeline (extraction → generation) creates a [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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//`. 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file. This standard ensures compatibility with any host implementing the protocol, including Amp, Claude Code, and other Agent-Skills-compatible environments.