# How book-to-skill Processes SKILL.md Instructions: A Step-by-Step Guide

> Discover how book-to-skill processes SKILL.md instructions. This guide details the 11-step execution from input validation to GitHub publication. Learn more!

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

---

**book-to-skill handles SKILL.md instructions by treating the document as an executable recipe that guides a host agent through 11 sequential steps—from input validation through security scanning to optional GitHub publication.**

The `book-to-skill` project (virgiliojr94/book-to-skill) transforms books into structured AI skills using a unique two-stage architecture. The **SKILL.md** file sits at the heart of this system, defining exactly how the generator component interprets extracted text and produces the final skill artifacts.

## The Two-Stage Architecture

Understanding how SKILL.md instructions are handled requires grasping the project's split design:

| Component | Language | Responsibility |
|-----------|----------|--------------|
| **Extractor** | Python ([`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py)) | Deterministic text extraction from PDF, EPUB, DOCX; produces [`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) |
| **Generator** | Host-agent driven | Interprets SKILL.md steps to create [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), `chapters/`, [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md), [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md), and [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md) |

As documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md), this separation allows the Python side to remain simple and deterministic while the SKILL.md specification evolves independently for different host agents (Copilot CLI, Amp, Claude, Hermes, etc.).

## How SKILL.md Instructions Drive the Generator

The SKILL.md file in the repository root contains an ordered workflow that the host agent executes. Here is how each instruction set is processed:

### Step 0 — Out-of-Scope Check

The generator first verifies that arguments were supplied. If invoked without parameters, it halts immediately with a usage prompt rather than proceeding with undefined input.

### Step 1 — Input Validation

The specification requires at least one supported file, folder, or glob pattern. This check runs before any extraction begins, preventing wasted compute on invalid paths.

### Step 1.5 — Content Type Identification

The user is prompted to classify the source as **technical** or **text-heavy**. This `BOOK_TYPE` value directly influences later token budgets, with technical books receiving different allocation strategies than narrative works.

### Step 2 — Extraction Orchestration

The generator locates [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), validates the Python environment, and invokes the extractor with the appropriate mode flag. The extraction output lands in a temporary work directory containing the two core artifacts: [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) (sanitized content) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) (structural metadata).

### Step 2.5 — Cost Estimation

Before any generation occurs, the tool reads [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) and presents the user with:

- Estimated token cost for the full conversion
- Complete file list from the extraction
- Opportunity to abort before incurring charges

### Step 3 — Structure Analysis

The generator examines the first ~8,000 characters of [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) to identify:
- Title and author
- Chapter heading patterns
- Core themes and frameworks

This analysis-only phase can be triggered independently with:

```bash
book-to-skill analyze path/to/book.epub

```

### Step 4 — Purpose Selection (Full Conversion Only)

For complete skill generation, the user selects the intended use case:
- Apply frameworks
- Think with mental models
- Reference chapters
- All of the above

This choice sets the `DEPTH` flag (`reference` vs `study`), which combines with `BOOK_TYPE` to determine per-chapter token budgets.

### Step 5 — Skill Name Resolution

The generator either accepts a slug from the command line or proposes names to the user (author-concept or title-based formats). It then selects the appropriate **SKILLS_HOME** root directory based on the detected host agent. This host-neutral approach—deliberately omitting `allowed-tools` from the spec—lets each platform supply its own shell and file-access capabilities.

### Step 6 — Directory Scaffolding

The skill folder structure is created, including the `chapters/` subdirectory that will hold individual chapter summaries.

### Step 7 — Chapter-Wise Generation

For each detected chapter, the generator:
- Reads only the relevant slice of [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) (using `grep`/`sed` for memory-efficient handling of large books)
- Respects the token budget derived from `BOOK_TYPE × DEPTH`
- Writes a markdown summary to `chapters/{slug}.md`

### Step 8 — Supporting Files Generation

Three additional artifacts are built from extracted terms and patterns:
- [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md) — defined terms and concepts
- [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md) — recurring techniques and structures
- [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md) — quick-reference decision rules

Each file has size caps to maintain the skill's lightweight profile.

### Step 9 — Master SKILL.md Assembly

The core skill file is constructed with specific sections:
- Concise description
- **How to Use** section
- Core Frameworks index (~2,000 tokens)
- Chapter index
- Topic index

The file is deliberately capped at ~4,000 tokens; excess content is truncated from the **end** to preserve front-loaded critical information.

### Step 9.5 — Security Scan

Before displaying or publishing, the generator invokes [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) to check for:
- Hidden Unicode characters
- Model-control tags
- Other potentially unsafe artifacts

This advisory scan protects both the user and downstream consumers of the skill.

### Step 10 — Cleanup and Reporting

The temporary work directory is removed, and a success report lists all generated artifacts with final token estimates.

### Step 11 — Optional Publishing

If enabled and visibility checks pass, the skill folder is initialized as a Git repository and pushed to GitHub, making it installable via:

```bash
npx skills add <user>/<repo>

```

## Update and Fold-In Workflow

When the target skill folder already exists (detected by presence of [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)), the generator branches at **Step 5** into an update pathway. It:

- Reads existing skill files
- Merges new chapters without duplicating existing ones
- Updates supporting files with new terms and patterns
- Regenerates the master [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) while preserving previous content

Trigger this with:

```bash
book-to-skill path/to/new/chapter.pdf existing-skill-slug

```

## Design Principles Enforced by SKILL.md

The specification embeds four key constraints that shape every skill:

| Principle | Implementation in SKILL.md |
|-----------|---------------------------|
| **Extract structure, not summaries** | Only named frameworks, decision rules, and anti-patterns are retained; narrative summaries are discarded |
| **On-demand chapters** | SKILL.md stays small; full chapter content loads only when explicitly queried |
| **Front-loaded core content** | Most important frameworks appear first; automatic truncation removes from the end |
| **Host-neutral tooling** | No `allowed-tools` restrictions; each host supplies required capabilities |

## Complete Workflow Example

Running a full conversion executes steps 0 through 10:

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

```

This single command triggers extraction, cost estimation, structure analysis, chapter generation, supporting file creation, security scanning, and cleanup—entirely as specified in the SKILL.md instruction set.

## Key Implementation Files

| File | Role in SKILL.md Processing |
|------|---------------------------|
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | Master specification defining steps 0–11 |
| [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) | Shim launching the deterministic extractor |
| [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) | Python extraction pipeline entry point |
| [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) | Security scanner invoked at Step 9.5 |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | CI validator for host-specific compliance |
| [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) | Pipeline overview and host root selection |

## Summary

- **SKILL.md is executable documentation** — the host agent follows its numbered steps as a runtime script
- **Token budgets are dynamic** — calculated from `BOOK_TYPE × DEPTH` to balance completeness against cost
- **Security is built-in** — mandatory scanning at Step 9.5 checks for hidden threats before publication
- **Updates are first-class** — the same specification handles both greenfield skills and incremental additions
- **Host neutrality enables portability** — the spec avoids tool-lock-in, letting Copilot, Claude, Amp, and Hermes each provide appropriate capabilities

## Frequently Asked Questions

### What happens if I run book-to-skill without arguments?

The generator stops at **Step 0** with a usage prompt. The SKILL.md specification explicitly defines this as an out-of-scope check to prevent execution with undefined input.

### Can I preview what a book contains before generating a full skill?

Yes. The `analyze` subcommand runs through **Step 3** only, returning an extraction report that lists detected frameworks, principles, techniques, and suggested skill names without incurring generation costs.

### How does book-to-skill prevent generated skills from becoming too large?

Three mechanisms enforce size constraints: **dynamic token budgets** based on content type and depth, **per-file caps** on supporting files, and **truncation from the end** of SKILL.md at ~4,000 tokens. The specification prioritizes front-loaded content so truncation removes less critical material.

### Is it safe to publish generated skills to public repositories?

The **Step 9.5** security scan ([`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py)) checks for hidden Unicode, model-control tags, and other unsafe artifacts before any display or publication. However, users should still review generated content, as the scan is advisory rather than exhaustive.