# How book-to-skill Structures the Generated Agent Skill: A Complete Directory Layout Guide

> Learn how book-to-skill structures generated agent skills with a clear directory layout including SKILL.md, reference files, and templated chapter summaries for organized skill development.

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

---

**The book-to-skill converter creates a self-contained Agent Skill with a strict directory layout anchored by [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), three supporting reference files, and templated chapter summaries organized under a `chapters/` subdirectory.**

The `book-to-skill` project transforms source books into importable **Agent Skills** that AI assistants can consume directly. According to the `virgiliojr94/book-to-skill` source code, the converter enforces a predictable, hierarchical structure designed for machine readability, token-budget compliance, and host-agnostic portability.

## Top-Level Skill Folder Structure

When the conversion workflow reaches **Step 6** — *Create skill directory structure* — it creates a root directory under the host-specific skill home (`$SKILLS_HOME/<skill_name>`)【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L33-L38】.

The resulting layout always follows this pattern:

```

<skill_root>/
│   SKILL.md                # Master descriptor (≤ 4,000 tokens)

│   glossary.md             # Alphabetized term definitions

│   patterns.md             # Concrete techniques and design patterns

│   cheatsheet.md           # Decision tables and quick-reference rules

└── chapters/
        ch01-<slug>.md      # Chapter 1 summary

        ch02-<slug>.md      # Chapter 2 summary

        …

```

This structure separates **discovery content** (root-level index files) from **deep content** (chapter summaries), letting agents load only what they need.

## SKILL.md: The Master Descriptor

The root [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) serves as the skill's entry point and must stay within **4,000 tokens** (Step 9)【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L57-L70】【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L94-L100】.

Its required sections include:

- **Front-matter** — skill name, version, source book metadata
- **Usage Guide** — how to invoke the skill in an agent context
- **Core Frameworks & Mental Models** — condensed knowledge graph
- **Chapter Index** — navigable table linking to each `chapters/*.md` file
- **Topic Index** — cross-reference by concept rather than chapter sequence
- **Supporting Files** — links to [`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 Chapter Index uses a standard markdown table format:

```markdown
| # | Title | Key Frameworks |

|---|-------|----------------|
| [ch01](chapters/ch01-intro.md) | Introduction | Framework A, Principle B |
| [ch02](chapters/ch02-deep-dive.md) | Deep Dive | Technique X |

```

## Chapter Files and the Templating System

Each chapter file in `chapters/` follows a strict template defined in **Step 7**【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L63-L84】. A fully populated chapter ([`ch03-design-patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/ch03-design-patterns.md)) contains these sections:

```markdown

# Chapter 3: Design Patterns

## Core Idea

One sentence that captures the chapter's main takeaway.

## Frameworks Introduced

- **Factory Method**: when you need to instantiate objects without specifying concrete classes.
  - When to use: configuration-heavy systems, plugin architectures
  - How: define Creator interface with factory_method() returning Product

## Key Concepts

- **Abstraction** — hiding implementation details (Ch 3)

## Mental Models

- Think of a factory as a *recipe* that produces objects.

## Anti-patterns

- **God Object** — a class that knows too much; leads to tight coupling.

## Code Examples

```python
class Product:
    pass

class ConcreteProductA(Product):
    pass

class Creator:
    def factory_method(self) -> Product:
        return ConcreteProductA()

```

## Worked Example

A step-by-step walkthrough of applying Factory Method to build a plugin system.

## Key Takeaways

1. Prefer composition over inheritance for extensibility
2. Keep product hierarchies shallow
3. Document the contract, not the implementation

## Connects To

- **Ch 2**: Object fundamentals
- **Design Thinking**: Problem framing techniques

```

The template adapts based on **book type** and **depth setting**:

| Book Type | Sections Omitted | Sections Added |
|-----------|------------------|----------------|
| Text-only (no code) | `Code Examples`, `Reference Tables` | — |
| Technical (with code) | — | `Code Examples` |
| `DEPTH=reference` | `Worked Example` | — |
| `DEPTH=study` | — | `Worked Example`【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L94-L106】 |

## Supporting Reference Files

Three specialized files complete the **Agent Skill structure**, each with strict token budgets:

### glossary.md

Alphabetized list of terms formatted as `**Term** — definition (Ch N)`. Limited to **~1,500 tokens** (Step 8)【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L26-L30】.

Example entry:

```markdown
**Dependency Inversion** — depend on abstractions, not concretions; enables testability and swapping implementations (Ch 5)

```

### patterns.md

Catalog of techniques, algorithms, and design patterns. Each entry includes *When to use* and *How* subsections. Budget: **≤ 2,000 tokens**【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L32-L36】.

### cheatsheet.md

Compact decision support: flowcharts, trade-off matrices, thresholds, rules of thumb. Budget: **~1,200 tokens**【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L38-L48】.

All three files are referenced from [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) in its **Supporting Files** section【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L110-L115】.

## Validation and Security Scanning

Before completion, **Step 9.5** runs [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) to enforce safety constraints【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L28-L32】:

- No prompt-injection patterns in markdown content
- No unsafe authority claims or executable directives
- File sizes within token budgets
- Required sections present in all chapter files

Run the scanner manually:

```bash
python -m tools.scan_generated_skill ~/.copilot/skills/my-skill-slug

```

The scanner's implementation lives at [`/tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main//tools/scan_generated_skill.py) in the repository.

## Practical Usage Examples

### Convert a book to a structured skill

```bash

# Full conversion workflow (Steps 0-9)

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

```

### Inspect generated structure

```bash
tree ~/.copilot/skills/my-skill-slug

```

### Load in GitHub Copilot CLI

```bash
copilot ask "apply the core frameworks from my-skill-slug to my project"

```

## Implementation Files

| File | Purpose |
|------|---------|
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | Blueprint defining directory layout, token limits, and template specifications【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md】 |
| [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) | Security and compliance scanner【/cache/repos/github.com/virgiliojr94/book-to-skill/master/tools/scan_generated_skill.py】 |
| [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) | `create_skill_structure()` and `render_chapter_template()` implementations |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | Host-specific validator (Claude, Copilot, Amp lenses)【/cache/repos/github.com/virgiliojr94/book-to-skill/master/tools/validate_skill.py】 |

## Summary

- **book-to-skill** generates **self-contained directory structures** with four root files plus a `chapters/` subdirectory
- **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** acts as the master index with a **4,000-token hard limit** and standardized navigation tables
- **Chapter files** follow a **rigid template** with contextually omitted sections based on book type and depth setting
- **Three supporting files** ([`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)) provide quick-reference material within strict token budgets
- **[`scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scan_generated_skill.py)** validates security and structural compliance before the skill is considered complete

## Frequently Asked Questions

### What determines the folder name for a generated skill?

The skill name is decided in **Step 5** of the workflow and becomes the directory name under `$SKILLS_HOME/`. The converter slugifies the provided name to ensure filesystem-safe paths【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L33-L38】.

### Can I manually edit files after generation?

Yes, but re-running the scanner is recommended. The [`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py) script checks for token budget violations and unsafe content patterns that manual edits might introduce【/cache/repos/github.com/virgiliojr94/book-to-skill/master/tools/scan_generated_skill.py】.

### How does the skill handle books without code examples?

For text-only books, the template **omits** the `Code Examples` and `Reference Tables` sections automatically. The `Frameworks Introduced` and `Mental Models` sections carry the knowledge transfer instead【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#L94-L106】.