Skill Format (SKILL.md)

Every BookForge skill is a SKILL.md file — a Markdown document with YAML frontmatter that agents read and follow. The format is an open standard that works across 10+ agent platforms including Claude Code, Codex CLI, Cursor, Windsurf, and others.

File Structure

A skill package looks like this:

architecture-tradeoff-analysis/
├── SKILL.md                          # The main skill file
├── scripts/
│   └── tradeoff-matrix.py            # Reusable automations
├── references/
│   └── quality-attributes.md         # Deep-dive material
└── assets/
    └── decision-template.md          # Templates the skill uses

Frontmatter

The frontmatter controls how and when the skill is triggered. The description field is the most important — it is what the agent reads to decide whether this skill applies to the current task.

---
name: architecture-tradeoff-analysis
description: >
  Analyze architecture decisions by mapping quality attributes
  against architecture characteristics, scoring tradeoffs,
  and producing a ranked recommendation with documented
  reasoning.
model: claude-sonnet-4-20250514
context: 16000
allowed-tools:
  - Read
  - Write
  - Bash
---

Key fields:

A critical distinction: the description in frontmatter controls triggering (when the skill activates). The When to Use section in the body controls execution (what context to gather before starting).

Body Structure

The body follows a consistent structure:

When to Use

Describes the situations where this skill applies. Helps the agent confirm it picked the right skill and gather necessary context before starting.

Checklist

A pre-flight checklist of inputs the agent should have before executing. Things like "Do you have the list of quality attributes?" or "Is there an existing architecture diagram?"

Process

The step-by-step procedure. Each step includes what to do and why it matters:

## Process

### Step 1: Identify Candidate Architecture Styles

List 2-4 architecture styles that could satisfy the primary requirements.

**Why:** Starting with too many options leads to analysis paralysis.
Starting with too few risks missing a better fit. 2-4 keeps the
analysis tractable while covering meaningful alternatives.

### Step 2: Map Quality Attributes

For each candidate, score it against the system's quality attributes
(performance, scalability, maintainability, etc.) on a 1-5 scale.

**Why:** Explicit scoring prevents the team from anchoring on the
first option discussed. Numbers force honest comparison.

The WHY reasoning is not decoration. It enables agents to handle edge cases that the step-by-step instructions don't explicitly cover. An agent that understands why a step exists can adapt when circumstances change.

Key Principles

Domain knowledge that informs the process — rules of thumb, common pitfalls, things the book's author learned from experience.

Examples

2-3 concrete examples in Scenario/Trigger/Process/Output format:

### Example: Migrating a Monolith to Microservices

**Scenario:** A team is evaluating whether to decompose a monolithic
e-commerce platform into microservices.

**Trigger:** "We need to decide on the architecture for the next
version of our platform."

**Process:** Applied Steps 1-4 with candidates: modular monolith,
microservices, service-based architecture.

**Output:** Recommended service-based architecture. Microservices
scored highest on independent deployability but lowest on operational
complexity. The team's current ops maturity made service-based the
better near-term choice.

Progressive Disclosure

Skills use a layered structure to stay readable:

• SKILL.md body — under 500 lines. Contains everything an agent needs for the standard case.
• references/ — deep-dive material for edge cases, background theory, extended examples. The body links to these when relevant.
• scripts/ — reusable automations the skill can invoke. Scoring calculators, template generators, analysis tools.
• assets/ — templates, diagrams, and other static files the skill references.

This keeps the main file focused while making detailed knowledge available when needed.

Generalization

BookForge skills use domain-standard terminology, not author-specific jargon. A skill distilled from "Fundamentals of Software Architecture" won't reference "Richards and Ford's coupling model" — it will reference "afferent and efferent coupling" using the terms any software architect would recognize.

This makes skills useful for anyone working in the domain, not just readers of the source book.

Further Reading

• Contributing — how to submit skills to the library
• How It Works — the pipeline that generates skills