# What Are the Two Main Components of the book-to-skill Architecture?

> Discover the two main components of the book-to-skill architecture: a Python extractor for JSON parsing and a spec-driven generator for creating Agent Skills with SKILL.md.

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

---

**The book-to-skill architecture consists of two core components: a deterministic Python extractor that parses source documents into structured JSON, and a spec-driven generator that transforms that JSON into reusable Agent Skills using a declarative SKILL.md specification.**

The **book-to-skill** project by virgiliojr94 provides a clean, modular pipeline for converting raw books and documents into executable agent capabilities. Understanding its two-component architecture is essential for anyone looking to extend the system, add new source formats, or customize skill generation behavior.

## Component 1: Deterministic Python Extractor

The first component handles **content acquisition and structural analysis** through a fully deterministic extraction process.

This subsystem ingests source books in formats like PDF, EPUB, or HTML, sanitizes the extracted text, discovers the underlying document structure, and outputs a well-defined JSON representation. Because this step is deterministic, it produces reproducible results suitable for automated pipelines, continuous integration, and testing scenarios.

The extractor lives primarily 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), with supporting library code organized under the [`book_to_skill/`](https://github.com/virgiliojr94/book-to-skill/tree/master/book_to_skill) package.

Run the extractor from the command line:

```bash
python -m scripts.extract \
    --input path/to/book.pdf \
    --output extracted.json

```

The resulting [`extracted.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/extracted.json) contains structured content that downstream tools can consume without re-parsing the original document.

## Component 2: Spec-Driven Generator

The second component handles **skill generation and packaging** guided by a declarative specification.

This generator takes the JSON output from the extractor and, using the constraints 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), produces a concrete Skill—a Python module plus metadata that agents can load and invoke. The specification describes critical properties including the skill's name, expected inputs, outputs, and any helper prompts needed for operation.

Generate a skill programmatically:

```python
import json
import pathlib
from book_to_skill import generate_skill

data = json.load(open('extracted.json'))
generate_skill(data, pathlib.Path('SKILL.md'))

```

The generated skill can then be imported and executed within an agent context:

```python
from my_generated_skill import MySkill

skill = MySkill()
result = skill.run(query="Explain the concept of recursion")
print(result)

```

## Separation of Concerns in the book-to-skill Architecture

These two components enforce a strict separation that enables independent evolution:

- **Extraction** focuses solely on reliable parsing and structural preservation. Changes to PDF parsing logic or new format support happen here without touching skill generation.
- **Generation** focuses exclusively on transforming structured data into consumable, version-controlled skills. Tweaking output formats or adding new skill metadata fields happens here without disturbing extraction.

This architectural split allows developers to plug in new source formats or experiment with skill specifications while keeping the core pipeline stable.

## Key Files Supporting the Architecture

| File | Purpose |
|------|---------|
| [[`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) | Main entry point for document extraction |
| [`book_to_skill/`](https://github.com/virgiliojr94/book-to-skill/tree/master/book_to_skill) | Library implementation for parsing and sanitization |
| [[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md) | Declarative spec driving skill generation |
| [[`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md)](https://github.com/virgiliojr94/book-to-skill/blob/master/docs/architecture.md) | Comprehensive system documentation |

## Summary

- The **deterministic Python extractor** in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) transforms source documents into structured JSON.
- The **spec-driven generator** uses [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) to convert that JSON into executable Agent Skills.
- This two-layer design separates content acquisition from skill production, enabling modular extensions and stable pipelines.

## Frequently Asked Questions

### Can I use book-to-skill with document formats other than PDF?

Yes. The extractor architecture is designed for extensibility. According to the source code in `book_to_skill/`, the parsing layer abstracts format-specific logic, allowing you to add EPUB, HTML, or other parsers without modifying the downstream generation step.

### Where is the skill behavior defined?

Skill behavior is declared 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) at the repository root. This specification file drives the generator component, defining inputs, outputs, prompts, and metadata that shape the final Python module.

### Is the extraction step deterministic for reproducibility?

Yes. The extractor is explicitly designed to be **fully deterministic**, as stated in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md). This ensures identical source documents produce identical JSON outputs, critical for testing and version-controlled pipelines.

### How do the two components communicate?

They communicate through a **well-defined JSON intermediary format**. The extractor outputs structured JSON, and the generator consumes that same schema. This file-based interface decouples the components so they can run independently or on different systems.