# What Are the Output Files Generated by book-to-skill? A Complete Breakdown

> Explore the output files from book-to-skill including SKILL.md, chapter content, glossary, patterns, and cheatsheets. Understand the core specifications generated by this tool.

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

---

**`book-to-skill` generates five core output files: [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (the lightweight core specification), `chapters/*.md` (lazy-loaded content files), [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md) (domain terminology), [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md) (reusable techniques), and [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md) (quick-reference decision rules).**

When you run `book-to-skill` against a source document—typically a Markdown book—it transforms that content into a modular **Skill** artifact set designed for LLM-agent consumption. As implemented in `virgiliojr94/book-to-skill`, this generator follows a specific architecture documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) that prioritizes token efficiency and on-demand loading. This article explains each generated output file, its purpose, and how the components work together.

## SKILL.md: The Core Specification

The **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** file serves as the central artifact that every LLM agent loads first. Located at the repository root or generated alongside your source, this file contains:

- A high-level **mental-model** structured in steps (0–10)
- A **compact index** of the entire skill
- A deliberately small footprint (kept under ~5 KB) to fit within token limits for every major LLM

Because [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) remains lightweight, agents can ingest the complete specification without truncation. The heavier content lives elsewhere and loads only when referenced.

## chapters/*.md: Lazy-Loaded Content

The **`chapters/`** directory contains individual Markdown files holding the bulk of your source material. These files are **generated at run-time** and follow a critical design pattern: **lazy loading**.

- The agent only fetches the specific chapter relevant to a user's query
- Token usage stays minimal during initial skill activation
- Content scales independently without bloating the core specification

This directory structure enables `book-to-skill` to handle large source books without exceeding context window constraints.

## glossary.md: Domain Terminology Reference

The **[`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md)** file functions as a specialized dictionary containing domain-specific terms referenced throughout the skill. Rather than embedding definitions inline—which would inflate [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)—the skill links to this external reference.

Agents resolve jargon on demand, keeping the core file clean while maintaining precise terminology when needed.

## patterns.md: Reusable Technique Catalog

The **[`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md)** file catalogs **reusable techniques and design patterns** extracted from the source material. This artifact allows agents to:

- Surface established solutions when appropriate
- Reference proven approaches without regenerating explanations
- Maintain consistency across skill invocations

Patterns exist as standalone, reusable knowledge blocks that agents can cite or elaborate based on context.

## cheatsheet.md: Quick Decision Reference

The **[`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md)** file contains **decision-rules, trade-off trees, and quick-reference "tells"** that help agents make fast, informed choices. Unlike narrative content, this artifact prioritizes:

- Speed: Rapid lookup for common decisions
- Clarity: Structured formats (tables, trees, rules)
- Actionability: Direct guidance without elaboration

## How the Output Architecture Works Together

The design rationale for these five output files appears explicitly in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) (lines 45–48), which describes this set as the canonical **generated output**. Together, they achieve three architectural goals:

1. **Token efficiency** — [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) stays tiny; heavier chapters remain off-disk until needed
2. **Modular knowledge** — each auxiliary file updates independently without full skill rebuilds
3. **Compliance and auditability** — validation tools inspect each artifact against host-specific rules

## Generating and Validating Output Files

Run the generator from the CLI entry point in [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py):

```python

# Generate a skill from a Markdown book

import subprocess, pathlib

book_path = pathlib.Path("my_book.md")
subprocess.run(["python", "-m", "book_to_skill", str(book_path)])

# After generation you will find:

#   SKILL.md

#   chapters/<chapter>.md

#   glossary.md, patterns.md, cheatsheet.md

```

The CLI forces UTF-8 output encoding before invoking the generator, ensuring consistent file encoding across platforms.

Validate your generated skill against host-specific requirements (Claude, Copilot, or Amp):

```bash

# Validate for a specific host

python tools/validate_skill.py --lens claude SKILL.md

```

The [`validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/validate_skill.py) tool (lines 2–13) enforces rules that vary by target platform.

Scan any generated skill directory for structural issues:

```bash

# Report missing or malformed output files

python tools/scan_generated_skill.py path/to/generated_skill

```

The [`scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scan_generated_skill.py) validator (lines 17–24) checks directory completeness and file integrity.

## Summary

- **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** — compact core specification with mental-model steps and index, kept under 5 KB
- **`chapters/*.md`** — individually loadable content files generated at run-time for lazy access
- **[`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md)** — domain terminology reference to resolve jargon without core file bloat
- **[`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md)** — catalog of reusable techniques and design patterns from the source
- **[`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md)** — structured decision-rules and quick-reference material for rapid agent choices

These five output files, defined in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and validated by [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) and [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py), form the complete artifact set that `book-to-skill` produces from any source document.

## Frequently Asked Questions

### What is the maximum recommended size for SKILL.md?

The `book-to-skill` generator intentionally keeps [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) under **5 KB**. This constraint ensures the core specification fits comfortably within token limits for every major LLM, including models with restricted context windows. Larger content belongs in `chapters/*.md` files that load on demand.

### Can I update glossary.md or patterns.md without regenerating the entire skill?

**Yes.** The modular architecture allows each auxiliary file—[`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)—to be updated independently. You do not need to rebuild [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) or regenerate chapter files when modifying these supplementary artifacts. This design supports iterative refinement without full regeneration costs.

### How does book-to-skill enforce host-specific rules for different LLM platforms?

The repository includes [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py), which accepts a `--lens` argument (claude, copilot, or amp) to apply platform-specific validation rules. This tool checks that generated artifacts meet the requirements of the target host, such as file size limits, required sections, or prohibited content patterns.

### Why doesn't book-to-skill include all content directly in SKILL.md?

Including all content in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) would violate the **token efficiency** principle that drives the architecture. By separating content into lazy-loaded `chapters/*.md` files and reference artifacts ([`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), [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md)), the skill minimizes initial token consumption. Agents load only what they need, when they need it—critical for large source documents and limited context windows.