SKILL.md Quality Rules Explained: Why Structure Beats Summaries

SKILL.md quality rules prioritize extracting named frameworks, exact formulations, and anti-patterns over chapter-by-chapter summaries, ensuring generated skills deliver actionable, compact knowledge for agent consumption.

The SKILL.md file serves as the core manifest that defines how a book-to-skill skill is organized and consumed by agent hosts like Copilot CLI, Amp, and Claude Code. According to the virgiliojr94/book-to-skill repository source code, eight enforceable quality rules govern what makes a skill production-ready. These rules are codified in the "Quality Rules" section of SKILL.md【/cache/repos/github.com/virgiliojr94/book-to-skill/master/SKILL.md#quality-rules】 and validated by tools/validate_skill.py.

The Eight Quality Rules for SKILL.md

Rule 1: Extract Structure, Not Summaries

Capture named frameworks, exact formulations, and anti-patterns. Avoid chapter recaps.

This guarantees the skill delivers reusable mental models and concrete rules instead of a prose overview. Agents need actionable scaffolds, not narrative retellings.

Rule 2: Preserve the Author's Precision

Keep exact naming. "The 5 Whys" stays exactly that—no paraphrasing to "asking why repeatedly."

Maintaining fidelity to the source author's intent allows downstream agents to reference canonical terms without ambiguity.

Rule 3: Density Over Completeness

A ~1,000-token summary beats a 10,000-token excerpt.

This keeps the skill lightweight. Agents load only what they need, reducing token cost and inference latency.

Rule 4: Practitioner Voice

Write "Use X when Y" rather than "The book explains X."

This frames knowledge as actionable guidance suitable for direct use in tooling or code generation workflows.

Rule 5: Front-Load SKILL.md

Most important content appears in the first ~5,000 tokens. Compaction trims the end.

The skill's entry point must contain the core frameworks that agents request most frequently.

Rule 6: Chapter Files Are On-Demand

Chapter files are not counted against the skill budget until loaded.

This allows large books to be split into many chapters without inflating the initial token load. The architectural split between SKILL.md (manifest) and chapter files (deep content) is documented in docs/architecture.md.

Rule 7: Never Copy Raw Book Text

Always synthesize, summarize, and extract signal.

This avoids copyright infringement and keeps the skill focused on distilled knowledge. The book_to_skill/sanitize.py module enforces this through automated sanitization routines.

Rule 8: Topic Index Is Critical

The index drives agent navigation to the correct chapter file.

This provides a fast lookup table so the agent can fetch the exact chapter needed for a query, rather than scanning full content.

How Quality Rules Are Enforced

The repository implements automated validation through tools/validate_skill.py. This script checks compliance against the quality rules and file structure before any skill is marked production-ready.

Supporting enforcement modules include:

• book_to_skill/utils.py — Helper utilities for content processing
• book_to_skill/sanitize.py — Sanitization logic to strip raw text and satisfy Rule 7

Correct SKILL.md Structure: Code Examples

Required Front-Matter Format

---
name: my-skill
description: "Knowledge base from \"Effective Python\" by Brett Slatkin. Use when applying Python best-practice frameworks, studying the book, or referencing its concepts."
---

The description must follow the practitioner voice: specify when to use the skill, not what the book contains.

Framework Entry Respecting Exact Phrasing (Rule 2)

## Core Frameworks & Mental Models

- **The 5 Whys**: Use when you need to uncover root causes by repeatedly asking "Why?" (up to five times).  
  *Why it works*: Each iteration forces deeper inspection, reducing surface-level explanations.

Note the preserved capitalization and exact phrasing of the framework name.

Chapter File Following On-Demand Design (Rule 6)

# Chapter 3: Managing Resources

## Core Idea

Efficient resource management prevents bottlenecks and improves scalability.

## Frameworks Introduced

- **Resource Pooling**: Reuse objects instead of creating new ones for each request.
  - When to use: High-frequency, short-lived operations.
  - How: Maintain a pool of pre-initialised objects; acquire/release on demand.

## Worked Example *(DEPTH=study)*

```python
pool = Queue(maxsize=10)
for _ in range(10):
    pool.put(Socket())

def get_socket():
    return pool.get()

Key Takeaways

1. Reduce allocation overhead.
2. Avoid resource leaks with deterministic release.

## Where These Rules Originate

The quality rules shape the entire generation pipeline, specifically Steps 7-9 in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md). They represent the **architectural contract** between the extractor (what pulls from books) and the generator (what produces agent-ready skills).

Key files defining this contract:

| File | Role |
|------|------|
| [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) | Central manifest containing quality rules, core frameworks, and indices |
| [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py) | Automated validator checking compliance with quality rules and file structure |
| [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) | High-level description of extractor-generator split and [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) placement |
| [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) & [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) | Helper modules enforcing sanitization to satisfy Rule 7 |

## Summary

- **Structure over summaries** — Frameworks and anti-patterns, not chapter recaps
- **Exact phrasing preserved** — Author precision enables canonical agent references
- **Token economy enforced** — ~1K dense beats 10K verbose; front-load to 5K window
- **Practitioner voice required** — "Use X when Y" syntax for direct tooling integration
- **On-demand architecture** — Chapter files load lazily, index drives navigation
- **Zero raw text** — Synthesis only, enforced by [`sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/sanitize.py)
- **Automated validation** — [`validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/validate_skill.py) gates production readiness

## Frequently Asked Questions

### What happens if SKILL.md exceeds the 5,000-token front-load limit?

Compaction algorithms trim content from the end. Critical frameworks must appear in the first ~5,000 tokens or risk being dropped from the agent's initial context window. This design constraint forces authors to prioritize their most valuable content.

### How does the topic index differ from a table of contents?

The topic index in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) is a **lookup-optimized structure** that maps concepts to specific chapter files. Unlike a linear table of contents, it enables agents to jump directly to relevant content without loading intervening material. The index is consumed programmatically, not read sequentially.

### Why is raw book text prohibited under Rule 7?

Raw text carries copyright risk and dilutes signal density. The [`book_to_skill/sanitize.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/sanitize.py) module automatically detects and strips unmodified excerpts. Synthesis also forces extraction of actionable structure—the core value proposition of the book-to-skill pipeline.

### Which agent hosts consume these SKILL.md files?

The repository targets **Copilot CLI**, **Amp**, **Claude Code**, and similar agent runtimes. Each loads [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) as a system prompt supplement or retrieval context. The quality rules ensure compatibility across these diverse consumption patterns.

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