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

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 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, book_to_skill/parsers/*, book_to_skill/utils.py
Generator	Emit skill package (SKILL.md + chapters + glossary + patterns)	SKILL.md, 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 accepts files, folders, or glob patterns:

# 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 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 — tries pdftotext, pypdf, pdfminer.six, or docling for technical layouts
• EPUB → book_to_skill/parsers/epub.py — uses ebooklib + beautifulsoup4
• DOCX → book_to_skill/parsers/docx.py — via python-docx
• HTML → book_to_skill/parsers/html.py — beautifulsoup4
• RTF → book_to_skill/parsers/rtf.py — striprtf
• Markdown / TXT / ReST / AsciiDoc → book_to_skill/parsers/text.py — built-in handler

Content Sanitization

After extraction, 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)

The 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 — extracted terminology with definitions
• patterns.md — design patterns detected in the source
• cheatsheet.md — quick-reference commands and syntax

Host-Specific Validation

tools/validate_skill.py checks the generated package against host constraints:

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

# 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 supports additional flags:

# 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 in the repository for complete option reference.

Key Implementation Files

Understanding these source files helps with customization and debugging:

File	Purpose
scripts/extract.py	CLI orchestration wiring extractor → generator
book_to_skill/utils.py	Source resolution, glob expansion, chapter detection heuristics
book_to_skill/parsers/pdf.py	Multi-backend PDF extraction with format auto-detection
book_to_skill/parsers/epub.py	EPUB content unpacking and HTML-to-markdown conversion
book_to_skill/sanitize.py	Security and compliance text filtering
SKILL.md	Skill specification template consumed by generator
tools/validate_skill.py	Host constraint validation and linting
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 maintaindozens 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 to remove unsafe characters and copyrighted text
• Generate modular skills with 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 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 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.

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