# What Is the Role of the Spec-Driven Generator in book-to-skill?

> Discover the spec-driven generator's role in book-to-skill. This orchestration layer transforms book extractions into structured Agent Skills following the SKILL.md specification. Learn more now.

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

---

**The spec-driven generator is the orchestration layer that reads the [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) specification and transforms raw book extractions into structured, on-demand Agent Skills through a series of user-guided, agent-driven steps.**

The `book-to-skill` pipeline splits work between two distinct halves: a **deterministic Python extractor** that handles document parsing, and the **spec-driven generator** that handles intelligent transformation. This article examines how the generator functions, what steps it executes, and why this separation of concerns matters for building reliable Agent Skills.

## How the Spec-Driven Generator Fits Into the Pipeline

According to the `virgiliojr94/book-to-skill` source code, the generator serves as the second half of the conversion workflow. After [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) produces clean text ([`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt)) and metadata ([`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json)), the generator takes over by reading the **specification file** ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)) and executing its numbered steps.

The [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) file describes this two-half design explicitly: the extractor stays pure-Python for reliability, while the generator stays **language-agnostic** and driven entirely by the markdown spec. Any host agent can interpret the same [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), making the system portable across different AI platforms.

## Step-by-Step Execution Flow

The generator follows a fixed sequence defined in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), with flexibility injected through user choices at key decision points.

### Step 0–1.5: Content Type Identification

The generator first asks the user to classify the book as **technical** or **text-heavy**, storing this as `BOOK_TYPE`. This variable influences later token budget calculations. This step appears in the *Identify content type* section of [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)【2†L104-L118】.

### Step 2–2.5: Text Extraction Launch

Using `BOOK_TYPE`, the generator launches [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) to process the source document. It then consumes the resulting [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) from the extraction output. See the *Extract text from the source documents* section【2†L27-L33】.

### Step 3–4: Structure Analysis and Purpose Definition

The generator analyzes the extracted content to discover:
- Title and author
- Chapter structure
- Core themes

It then prompts the user for `DEPTH`—what the skill should *do*. This answer determines how much detail each chapter summary receives. These steps appear in the *Analyze book structure* and *Ask purpose* sections【2†L44-L53】【2†L79-L95】.

### Step 6–9: Skill Artifact Generation

The generator creates the complete file hierarchy:
- `chapters/` directory with individual summaries
- [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md) for key terms
- [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md) for recurring concepts
- [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md) for quick reference
- Final composed [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) for host agent loading

All output formats and directory structures are dictated by the spec in the *Create skill directory structure* section onward【2†L33-L41】【2†L56-L64】.

### Step 9.5: Security Scanning

Before handoff, the generator runs [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) to detect hidden instructions or invisible Unicode that may have leaked into generated files. This validation step appears in the *Scan the generated skill* section【2†L28-L33】.

### Step 10–11: Cleanup and Optional Publishing

The generator removes temporary work directories, reports completion, and optionally publishes to GitHub. See *Cleanup and report* and *Publish* sections【2†L41-L49】【2†L14-L22】.

## Running the Spec-Driven Generator

### Basic Conversion

Trigger the full pipeline with a single command:

```bash
book-to-skill path/to/book.pdf my-awesome-skill

```

This automatically runs [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) followed by all generator steps in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), outputting to the host-specific directory (e.g., `~/.copilot/skills/my-awesome-skill/`).

### Validating an Existing Skill

Run a single generator step in isolation:

```bash
python -m tools.validate_skill.py SKILL.md

```

This executes Step 9.5 from the spec to check a previously generated skill for security concerns.

### Updating Existing Skills

The generator supports incremental updates through the *Update / Fold-in Workflow*:

```bash
book-to-skill new/chapter1.pdf existing-skill-slug --mode text

```

The generator reads the existing skill's [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), merges new chapter summaries and glossary entries, and updates the master specification.

## Key Implementation Files

| File | Role |
|------|------|
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | The **specification** that drives all generator behavior—step definitions, token budgets, output formats. |
| [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) | Documents the two-half architecture and the generator's orchestration responsibilities. |
| [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) | Thin shim launching the deterministic extractor; invoked by the generator. |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | Implements Step 9.5 security validation. |
| [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) | Advisory scanner run before skill finalization. |

## Why Spec-Driven Design Matters

The **spec-driven generator** architecture provides three critical advantages:

- **Determinism** — The same [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) produces consistent outputs across runs
- **Portability** — Any host agent that parses markdown can execute the workflow
- **Maintainability** — Business logic lives in the spec, not hardcoded in the generator implementation

This design keeps the conversion reliable while preserving flexibility through user-configurable variables (`BOOK_TYPE`, `DEPTH`, skill name, destination host).

## Summary

- The **spec-driven generator** is the second half of `book-to-skill`, transforming extracted text into structured Agent Skills
- It reads and executes the numbered steps defined in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) with user input at key decision points
- The generator manages content type detection, token budgeting, file hierarchy creation, security scanning, and optional publishing
- Separation from the deterministic Python extractor keeps the system both reliable and language-agnostic
- Key files include [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (specification), [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) (extraction shim), and [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) (security validation)

## Frequently Asked Questions

### What makes the generator "spec-driven"?

The generator executes a fixed workflow defined entirely in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), a markdown file containing numbered steps, token budget rules, and output format specifications. This externalized configuration means the same generator implementation can produce different skill structures just by modifying the spec, without code changes.

### How does the spec-driven generator handle different book types?

The generator asks users to classify content as **technical** or **text-heavy** during Step 0–1.5, storing this as `BOOK_TYPE`. This variable influences later decisions about extraction parameters, summary depth, and token allocation—allowing the same spec to adapt to different content categories.

### Can I run the spec-driven generator without the extractor?

No—the generator depends on [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) output ([`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json)) as its starting input. However, you can re-run the generator on existing extractions or invoke individual validation steps like [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) without triggering full re-extraction.

### Where is the spec-driven generator's security scanning implemented?

Security scanning appears in Step 9.5 of [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), implemented by [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py). This step runs automatically before skill finalization to detect hidden instructions, invisible Unicode, or other potentially harmful content that may have propagated from source documents into generated skill files.