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

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/master/scripts/extract.py), with supporting library code organized under the book_to_skill/ package.

Run the extractor from the command line:

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

The resulting 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/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:

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:

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/master/scripts/extract.py)	Main entry point for document extraction
book_to_skill/	Library implementation for parsing and sanitization
[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/master/docs/architecture.md)	Comprehensive system documentation

Summary

• The deterministic Python extractor in scripts/extract.py transforms source documents into structured JSON.
• The spec-driven generator uses 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/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. 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.

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