# Understanding the Two Main Components of Book-to-Skill

> Discover the two main components of Book-to-Skill: a Python extractor for structured data and a generator for reusable Agent Skills. Learn how they work together.

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

---

**Book-to-Skill consists of two core components: a deterministic Python extractor that parses documents into structured data, and a spec-driven generator that transforms that data into a reusable Agent Skill.**

The [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) repository implements a clean separation between **data extraction** and **skill generation**. This architecture allows users to process any book or document format and produce LLM-ready outputs without mixing parsing concerns with presentation logic.

## The Deterministic Python Extractor

The first component handles all document ingestion and normalization. It is implemented as a deterministic Python pipeline that converts raw files—PDFs, EPUBs, DOCX, HTML, and others—into a canonical JSON representation.

The extraction logic resides in two locations:

- **[[`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)](https://github.com/virgiliojr94/book-to-skill/blob/master/scripts/extract.py)** – The CLI entry point that orchestrates the extraction workflow
- **[`book_to_skill/`](https://github.com/virgiliojr94/book-to-skill/tree/master/book_to_skill)** – The core package containing parsers, text sanitizers, and format handlers

This separation ensures that parsing remains **reproducible and testable**. The same input document always produces identical structured output, which is critical for downstream processing.

Run the extractor from the command line:

```bash
python -m book_to_skill.cli extract path/to/book.pdf --out extracted.json

```

The `--out` parameter specifies where the canonical JSON representation is saved. This file serves as the bridge to the second component.

## The Spec-Driven Generator

The second component transforms extracted data into the final **Agent Skill**. Unlike the extractor, which operates on fixed parsing rules, the generator follows an external specification defined in **[[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md)**.

This design provides flexibility:

- Modify output structure without touching Python code
- Version skill formats independently of the extraction engine
- Support multiple target skill formats through different spec files

Generate a skill from extracted data:

```bash
python -m book_to_skill.cli generate extracted.json --spec SKILL.md --out skill.md

```

The generator reads the JSON produced by the extractor, applies the rules and templates from [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), and emits a markdown file formatted for agent consumption.

## How the Components Work Together

The two components form a linear pipeline:

1. **Extract** – Document → [`extracted.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/extracted.json) (deterministic, format-agnostic)
2. **Generate** – [`extracted.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/extracted.json) + [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) → [`skill.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/skill.md) (spec-driven, customizable)

This architecture mirrors classical **ETL patterns**: extraction handles messy real-world inputs, while generation applies business logic through configuration rather than code.

Development teams benefit from this split:

- **Engineers** focus on parser accuracy and performance in `book_to_skill/`
- **Prompt engineers or domain experts** refine [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) to control output quality
- **Operations** cache or version [`extracted.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/extracted.json) to avoid re-parsing unchanged documents

## Command-Line Interface Reference

Both components expose unified CLI commands under `book_to_skill.cli`:

| Command | Purpose | Primary Files |
|---------|---------|-------------|
| `extract` | Parse document to structured JSON | [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), `book_to_skill/*` |
| `generate` | Render JSON to Agent Skill via spec | [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) |

Add `--help` to any command for parameter details:

```bash
python -m book_to_skill.cli --help
python -m book_to_skill.cli extract --help
python -m book_to_skill.cli generate --help

```

## Summary

- **Deterministic Python extractor** – Parses documents into canonical JSON using the `book_to_skill` package and [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)
- **Spec-driven generator** – Produces Agent Skills by applying [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) templates to extracted data
- **Clean separation** – Parsing logic and output formatting remain independent, enabling parallel development and flexible deployment

## Frequently Asked Questions

### What file formats does the Book-to-Skill extractor support?

The extractor handles PDF, EPUB, DOCX, HTML, and other common document formats through the parsing utilities in the [`book_to_skill/`](https://github.com/virgiliojr94/book-to-skill/tree/master/book_to_skill) package. Specific format support depends on the underlying libraries integrated into the extraction pipeline.

### Can I customize the output format without modifying Python code?

Yes. The **spec-driven generator** reads rules from [[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md), allowing you to change output structure, field mappings, and formatting by editing this specification file. No changes to `book_to_skill/` or [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) are required.

### Is the extraction process deterministic and repeatable?

Yes. The **Python extractor** is designed to produce identical JSON output for identical inputs. This determinism enables caching, regression testing, and reproducible build pipelines when processing large document collections.

### Where can I find the CLI implementation for both components?

The unified command-line interface is accessed through `python -m book_to_skill.cli`, which exposes `extract` and `generate` subcommands. The CLI orchestration logic resides in [[`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)](https://github.com/virgiliojr94/book-to-skill/blob/master/scripts/extract.py) and supporting modules within the [`book_to_skill/`](https://github.com/virgiliojr94/book-to-skill/tree/master/book_to_skill) package.