How to Use book-to-skill with Amp Agent: A Complete Integration Guide

Use book-to-skill to convert any book into a SKILL.md file that the Amp agent consumes directly, then register it via amp skill add to expose book content as callable tools.

The book-to-skill repository by virgiliojr94 provides a deterministic Python extractor that transforms documents—PDF, EPUB, DOCX, HTML, and more—into structured skill definitions. Because Amp supports Claude-compatible tool naming conventions plus its own shell_command shorthand, the generated skills work without modification. This guide walks through the complete integration pipeline from extraction to agent execution.

What book-to-skill Generates

The extractor produces a SKILL.md file containing four key sections that Amp expects:

Field	Purpose	Amp Usage
label	Human-readable skill identifier	Displays in amp skill list
description	Free-form capability summary	Shown in help text and UI
tools	Tool definitions with names, arguments, and descriptions	Registered as callable agent capabilities
runtime	Optional Docker image or execution command	Spawns isolated containers when specified

Amp's loader recognizes these fields natively. The tools section specifically leverages Claude-style naming that Amp already understands, as noted in the validation logic at tools/validate_skill.py lines 53–75.

Step-by-Step Integration Workflow

1. Extract a Skill from Your Document

The core extraction logic lives in book_to_skill/parsers/. Each format has a dedicated parser—pdf.py, epub.py, docx.py, html.py, and others—while shared utilities handle sanitization and metadata in book_to_skill/utils.py and book_to_skill/sanitize.py.

Install and run the extractor:

# Install in editable mode

pip install -e .

# Generate SKILL.md from a PDF

python -m book_to_skill extract \
    --input path/to/my_book.pdf \
    --output my_book_skill.md \
    --format pdf

Key flags:

• --input: Source document path
• --output: Destination SKILL.md file
• --format: Parser selector matching files in book_to_skill/parsers/

2. Validate Against Amp Conventions

Before loading into Amp, verify schema compliance using the dedicated validator:

python -m tools.validate_skill my_book_skill.md

The validator at tools/validate_skill.py performs two functions: it checks standard SKILL.md structure and adds Amp-specific warnings for token-MCP name collisions. A passing result prints ✅ Skill is valid.

3. Register with Amp Agent

Load the validated skill through Amp's CLI:

# Register the skill

amp skill add --file my_book_skill.md

# Confirm registration

amp skill list

Once registered, tools from your book appear under the skill's label and execute via:

amp run --tool summarize_chapter --args '{"chapter": 5}'

4. Programmatic Access (Optional)

For Python-based workflows, load the skill through Amp's SDK:

import amp_client

client = amp_client.AmpClient()
client.load_skill("my_book_skill.md")

result = client.run_tool(
    tool_name="summarize_chapter",
    arguments={"chapter": 5}
)
print(result)

The SDK automatically resolves Amp's shell_command shortcuts, enabling direct invocation of shell-based tools extracted from your document.

Source File Reference Map

Component	File Path	Purpose
CLI entry point	book_to_skill/cli.py	User-facing command interface
Extraction script	scripts/extract.py	CI-friendly wrapper for batch processing
PDF parser	book_to_skill/parsers/pdf.py	Document-to-skill conversion logic
Configuration	book_to_skill/config.py	Default settings including Amp options
Validation	tools/validate_skill.py	Schema and Amp-convention checking

All parsers follow the same interface defined in the book_to_skill/parsers/ package, making format extensions straightforward.

Amp-Specific Compatibility Notes

The book-to-skill output requires no transformation for Amp because:

• Tool naming: Uses Claude conventions that Amp already supports
• Shell shortcuts: Amp's shell_command shorthand works with generated tool definitions
• Validation: The optional validator catches Amp-specific edge cases like name collisions

As implemented in virgiliojr94/book-to-skill, the extraction pipeline produces portable skills compatible with multiple agent frameworks while optimizing for Amp's loader expectations.

Summary

• Install book-to-skill and extract documents using python -m book_to_skill extract with --format matching your source type
• Validate output with python -m tools.validate_skill to catch Amp-specific issues before registration
• Register via amp skill add --file SKILL.md to make tools available to the agent
• Invoke tools through amp run, Python SDK, or shell commands depending on your workflow
• Source parsers in book_to_skill/parsers/ handle PDF, EPUB, DOCX, HTML; extend by implementing the shared parser interface

Frequently Asked Questions

What document formats does book-to-skill support?

PDF, EPUB, DOCX, HTML, and RTF are supported out-of-the-box through dedicated parsers in book_to_skill/parsers/. Each parser normalizes content into the same internal representation before skill generation.

Why validate before loading into Amp?

The validator at tools/validate_skill.py catches schema violations and Amp-specific naming collisions that would cause registration failures. Running validation prevents silent tool registration errors.

Can I use the same SKILL.md with Claude and Amp?

Yes. The SKILL.md format uses Claude-compatible tool conventions that Amp recognizes natively. No format conversion is required when switching between agents.

Where are the default extraction settings configured?

Amp-related defaults live in book_to_skill/config.py. Modify this file to change output formatting, default tool prefixes, or validation strictness without altering extraction logic.

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