# How to Convert Books and Documents Into Structured Agent Skills for GitHub Copilot CLI

> Convert books and documents to structured agent skills for GitHub Copilot CLI with the book-to-skill tool. Load your knowledge on demand.

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

---

**Use the `book-to-skill` open-source tool to transform any PDF, EPUB, DOCX, or other document into a modular Agent Skill that GitHub Copilot CLI loads on-demand.**

Converting technical books and documentation into structured agent skills for GitHub Copilot CLI requires a pipeline that extracts content, sanitizes it, and packages it according to the open Agent Skills specification. The [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) repository implements this end-to-end workflow through two coordinated components: a deterministic Python extractor and a spec-driven generator.

## Understanding the Agent Skills Architecture

Agent Skills follow a standardized format that enables any compatible host—GitHub Copilot CLI, Amp, Claude Code, or Hermes Agent—to load domain expertise only when needed. This **lazy-loading** approach keeps context windows small while giving agents access to deep technical knowledge.

The `book-to-skill` pipeline separates concerns cleanly:

| Component | Responsibility | Key Source Files |
|-----------|----------------|----------------|
| **Extractor** | Parse multi-format sources, clean text, identify structure | [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), `book_to_skill/parsers/*`, [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) |
| **Generator** | Emit skill package ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) + chapters + glossary + patterns) | [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) |

## Step 1: Extract Content From Any Document Format

The extraction phase handles **10+ input formats** through specialized parsers that automatically select the best available tool.

### Input Resolution and Dependency Probing

The CLI entry point in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) accepts files, folders, or glob patterns:

```bash

# Single file

book-to-skill ./design-patterns.pdf

# Entire directory

book-to-skill ./docs/

# Glob pattern

book-to-skill "./books/*.epub"

```

Before processing, [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) probes for external tools and falls back to pure-Python alternatives when needed. This ensures portability across environments.

### Format-Specific Parser Selection

Each document type routes to a dedicated parser in `book_to_skill/parsers/`:

- **PDF** → [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) — tries `pdftotext`, `pypdf`, `pdfminer.six`, or `docling` for technical layouts
- **EPUB** → [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) — uses `ebooklib` + `beautifulsoup4`
- **DOCX** → [`book_to_skill/parsers/docx.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/docx.py) — via `python-docx`
- **HTML** → [`book_to_skill/parsers/html.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/html.py) — `beautifulsoup4`
- **RTF** → [`book_to_skill/parsers/rtf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/rtf.py) — `striprtf`
- **Markdown / TXT / ReST / AsciiDoc** → [`book_to_skill/parsers/text.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/text.py) — built-in handler

### Content Sanitization

After extraction, [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) performs critical safety steps:

1. Removes **Bidi control characters** that could alter text direction maliciously
2. Strips **annotation characters** and editorial markup
3. Filters **raw copyrighted passages** to maintain fair-use compliance

This sanitization layer ensures generated skills are safe to distribute and use in professional contexts.

## Step 2: Generate the Structured Skill Package

The generator consumes cleaned content and produces a spec-compliant skill directory.

### Core Skill Definition ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md))

The [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file serves as the skill's manifest and mental model. It contains:

- High-level description and intended use cases
- Table of contents mapping to chapter files
- Loading hints for the host agent

### Modular Chapter Files

Rather than dumping everything into context, the generator creates **per-chapter markdown files** under `chapters/`:

```

chapters/
├── ch01-introduction.md          (~1,000 tokens)
├── ch02-observer-pattern.md      (~1,000 tokens)
├── ch03-factory-pattern.md       (~1,000 tokens)
└── ...

```

Each file is sized to stay within token budgets and is **loaded only when the agent queries that specific topic**.

### Reference Materials

The generator also produces:

- **[`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md)** — extracted terminology with definitions
- **[`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md)** — design patterns detected in the source
- **[`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md)** — quick-reference commands and syntax

### Host-Specific Validation

[`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) checks the generated package against host constraints:

```bash

# Validate for Copilot CLI

python tools/validate_skill.py --lens copilot ./my-skill/

# Validate for Claude Code

python tools/validate_skill.py --lens claude ./my-skill/

```

Supported lenses: `copilot`, `claude`, `amp`, `hermes`.

## Step 3: Deploy to Your Agent Host

Generated skills install to host-specific directories:

| Host | Installation Path |
|------|-------------------|
| GitHub Copilot CLI | `~/.copilot/skills/<slug>/` |
| Amp / cross-agent | `~/.agents/skills/<slug>/` |
| Claude Code | `~/.claude/skills/<slug>/` |
| Hermes Agent | `$HERMES_HOME/skills/<category>/<slug>/` |

The `book-to-skill` CLI handles placement automatically based on detected host environment.

## Complete End-to-End Usage

Install and run with a single command sequence:

```bash

# Install via npx (works for any host)

npx skills add virgiliojr94/book-to-skill

# Convert your document

book-to-skill ./clean-code.pdf

# Use in Copilot CLI (loads only relevant chapter)

/copilot clean-code tell me about the single responsibility principle

```

The agent receives only the chapter covering **Single Responsibility Principle**, not the entire book.

## Advanced Configuration Options

For production workflows, [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) supports additional flags:

```bash

# Analysis-only mode (preview structure without generating)

book-to-skill --analyze ./large-book.pdf

# Incremental update (only process changed chapters)

book-to-skill --incremental ./updated-book.pdf

# Custom output directory

book-to-skill --output ./custom-skills/ ./source.pdf

# Specific host target

book-to-skill --host claude ./book.epub

```

See [`docs/usage.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/usage.md) in the repository for complete option reference.

## Key Implementation Files

Understanding these source files helps with customization and debugging:

| File | Purpose |
|------|---------|
| [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) | CLI orchestration wiring extractor → generator |
| [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) | Source resolution, glob expansion, chapter detection heuristics |
| [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) | Multi-backend PDF extraction with format auto-detection |
| [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/epub.py) | EPUB content unpacking and HTML-to-markdown conversion |
| [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) | Security and compliance text filtering |
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | Skill specification template consumed by generator |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | Host constraint validation and linting |
| [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) | Component diagrams and data flow documentation |

## Performance and Token Optimization

The chunked chapter approach delivers **significant efficiency gains**:

- Typical technical book: ~100,000+ tokens if loaded whole
- Single chapter on demand: ~1,000 tokens
- **~99% reduction** in context usage per query

This architecture makes it practical to maintain**dozens of skills** without exhausting model context windows.

## Summary

- **Install** via `npx skills add virgiliojr94/book-to-skill` for any supported host
- **Extract** using format-specific parsers in `book_to_skill/parsers/` that auto-select optimal tools
- **Sanitize** through [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) to remove unsafe characters and copyrighted text
- **Generate** modular skills with [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) manifest and per-chapter files (~1,000 tokens each)
- **Validate** against host rules using `tools/validate_skill.py --lens copilot|claude|amp|hermes`
- **Deploy** automatically to `~/.copilot/skills/`, `~/.claude/skills/`, or equivalent host directory
- **Query** with `/copilot <skill-name> <topic>` to load only relevant chapters on demand

## Frequently Asked Questions

### What document formats does book-to-skill support?

The tool supports PDF, EPUB, DOCX, HTML, RTF, MOBI, Markdown, plain text, ReStructuredText, and AsciiDoc. Each format routes to a dedicated parser in `book_to_skill/parsers/` that selects the best extraction library available in your environment.

### How does the tool handle copyrighted material?

[`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) applies fair-use filtering that removes raw verbatim passages while preserving factual knowledge and concepts. The generated skill contains transformed, excerpted content suitable for personal use and internal team knowledge bases.

### Can I use generated skills with agents other than GitHub Copilot CLI?

Yes. The **Agent Skills spec** is host-agnostic. Pass `--lens claude`, `--lens amp`, or `--lens hermes` to [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) to target Claude Code, Amp, or Hermes Agent respectively. The same skill package works across all supported hosts when validated for that environment.

### Why are chapters split into separate files instead of one large document?

Chunking into ~1,000-token chapter files enables **lazy loading**—the agent pulls only the relevant chapter into context when you ask about a specific topic. This keeps token usage low, reduces costs, and improves response quality by minimizing distraction from irrelevant content.