What Files Are Included in a Generated Agent Skill?

A generated agent skill from the book-to-skill extractor contains seven core components: SKILL.md (runtime manifest), README.md (human documentation), metadata.json (extraction statistics), numbered chapter-XX.md files (structured content), an optional assets/ directory for media, .gitignore for repository hygiene, and optionally 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 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 file at the repository root to declare itself to Agent-Skills hosts. According to the repository's own SKILL.md, this manifest specifies the skill name, description, required runtime dependencies, and entry points (e.g., README.md, metadata.json, and chapter files) that the host uses to initialize the skill.

README.md – Human Documentation

The 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 manifest.

metadata.json – Extraction Statistics

The metadata.json file aggregates extraction metadata including chapter counts, token budgets, and source-type breakdowns. As detailed in 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 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: 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:

$ 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:

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, README.md, metadata.json, numbered chapter files, optional assets/, .gitignore, and conditional LICENSE.md.
• Extraction code exclusion: The skill directory excludes 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 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 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, which contains chapter slugs, token budgets, and source-type statistics. This index allows the runtime to make informed decisions about which 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 serves machine-readable metadata required by the Agent-Skills runtime to initialize the skill, while README.md targets human readers. The runtime parses SKILL.md to discover entry points and dependencies before loading any chapter content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}