# What Files Are Included in a Generated Agent Skill?

> Discover the seven essential files within a generated agent skill. Understand the runtime manifest, documentation, metadata, and more from the book to skill extractor.

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

---

**A generated agent skill from the `book-to-skill` extractor contains seven core components: [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (runtime manifest), [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md) (human documentation), [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) (extraction statistics), numbered [`chapter-XX.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/chapter-XX.md) files (structured content), an optional `assets/` directory for media, `.gitignore` for repository hygiene, and optionally [`LICENSE.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/LICENSE.md) when copyright permits.**

When the `book-to-skill` pipeline (implemented in `virgiliojr94/book-to-skill`) finishes processing source material, it outputs a standardized skill directory compatible with the Agent-Skills ecosystem. This generated agent skill excludes the original extraction scripts—such as [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) and parser modules—and contains only the synthesized artefacts required by runtime hosts including Claude Code, GitHub Copilot CLI, and Amp.

## Core Files in the Generated Agent Skill Structure

### SKILL.md – The Runtime Manifest

Every generated agent skill requires a [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file at the repository root to declare itself to Agent-Skills hosts. According to the repository's own [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), this manifest specifies the skill name, description, required runtime dependencies, and entry points (e.g., [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md), [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json), and chapter files) that the host uses to initialize the skill.

### README.md – Human Documentation

The [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md) provides consumable documentation for developers browsing the repository. It contains usage examples, installation instructions, and licensing notes that complement the machine-readable [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) manifest.

### metadata.json – Extraction Statistics

The [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) file aggregates extraction metadata including chapter counts, token budgets, and source-type breakdowns. As detailed in [`docs/how-it-works.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/how-it-works.md), this JSON index enables the runtime to perform on-demand chapter selection based on query context and resource constraints.

### chapter-XX.md – Structured Content Files

For each discovered chapter, the extractor generates a [`chapter-XX.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/chapter-XX.md) file (where XX represents the numerical chapter identifier or slug). These files contain structured markdown capturing extracted frameworks, decision rules, anti-patterns, and concise takeaways. Per "Quality Rule #7" documented in the repository README, these chapter files contain **no raw text** copies from the source material—only synthesized, structured knowledge.

### assets/ – Optional Media Directory

When processing PDFs or illustrated documents, the extractor populates an `assets/` directory with images and diagrams referenced by the chapter markdown files. This directory is omitted when the source contains no visual assets.

### Configuration and License Files

- **`.gitignore`**: Prevents accidental committing of large temporary files (such as `/tmp/` artefacts) when the skill is cloned, following patterns from the repository's own `.gitignore`.
- **[`LICENSE.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/LICENSE.md)**: Included only when the source material carries an open license permitting redistribution; otherwise excluded to respect copyright law.

## Directory Structure Example

A complete generated agent skill directory follows this layout:

```bash
$ ls my-book-skill/
README.md       SKILL.md       metadata.json
chapter-01.md   chapter-02.md  assets/
.gitignore      LICENSE.md

```

The skill directory functions as a self-contained Git repository that hosts can clone and load on demand. It contains no extraction pipeline code—only the runtime-ready artefacts.

## Programmatic Access to Generated Skills

Developers can navigate the skill structure using the metadata index to load specific chapters:

```python
import json
import pathlib

skill_root = pathlib.Path("my-book-skill")
metadata = json.loads((skill_root / "metadata.json").read_text())

# Select chapter using the metadata index

chapter_slug = metadata['chapters'][2]['slug']
chapter_path = skill_root / f"chapter-{chapter_slug}.md"
chapter_content = chapter_path.read_text()

print(f"Chapter loaded: {len(chapter_content)} characters")

```

## Summary

- **Seven file types** constitute a generated agent skill: [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md), [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json), numbered chapter files, optional `assets/`, `.gitignore`, and conditional [`LICENSE.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/LICENSE.md).
- **Extraction code exclusion**: The skill directory excludes [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) and parser modules, shipping only synthesized runtime artefacts.
- **Standard compliance**: The layout adheres to the Agent-Skills ecosystem specification, enabling compatibility with Claude Code, GitHub Copilot CLI, and Amp.
- **Copyright safety**: [`LICENSE.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/LICENSE.md) appears only when source licensing permits, and "Quality Rule #7" ensures no raw source text is copied into chapter files.

## Frequently Asked Questions

### Does a generated agent skill include the original book or PDF content?

No. The generated skill contains only synthesized markdown in [`chapter-XX.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/chapter-XX.md) files capturing frameworks, rules, and takeaways. According to "Quality Rule #7" in the repository README, raw text extraction is explicitly avoided to respect copyright and optimize token usage.

### How does the host know which chapter to load?

The host consults [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json), which contains chapter slugs, token budgets, and source-type statistics. This index allows the runtime to make informed decisions about which [`chapter-XX.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/chapter-XX.md) file contains the relevant knowledge for a given query.

### Can I publish a generated skill to GitHub?

Yes. The output is a standard Git repository structure that can be published via `gh repo create` or consumed via `npx skills add`. The included `.gitignore` ensures temporary extraction artefacts do not enter version control.

### Why is SKILL.md required if README.md exists?

[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) serves machine-readable metadata required by the Agent-Skills runtime to initialize the skill, while [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md) targets human readers. The runtime parses [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) to discover entry points and dependencies before loading any chapter content.