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

> Integrate book-to-skill with Amp Agent to transform books into callable tools. Learn how to convert any book into a SKILL.md file and register it easily.

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

---

**Use `book-to-skill` to convert any book into a [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/pdf.py), [`epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/epub.py), [`docx.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/docx.py), [`html.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/html.py), and others—while shared utilities handle sanitization and metadata in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) and [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py).

Install and run the extractor:

```bash

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash
python -m tools.validate_skill my_book_skill.md

```

The validator at [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) performs two functions: it checks standard [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash

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

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

```

### 4. Programmatic Access (Optional)

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

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) | User-facing command interface |
| Extraction script | [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) | CI-friendly wrapper for batch processing |
| PDF parser | [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) | Document-to-skill conversion logic |
| Configuration | [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) | Default settings including Amp options |
| Validation | [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py). Modify this file to change output formatting, default tool prefixes, or validation strictness without altering extraction logic.