# Understanding the Structure of a SKILL.md File in Claude Skills

> Discover the structure of a SKILL.md file in Claude Skills. Learn how the YAML header and progressive disclosure body provide comprehensive agent instructions concisely.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: deep-dive
- Published: 2026-02-16

---

**A SKILL.md file consists of a required YAML front-matter header followed by a human-readable body that uses progressive disclosure to keep the file under 100 lines while providing comprehensive agent instructions.**

The `Jeffallan/claude-skills` repository defines a standardized format for creating reusable Claude skills. Each skill is encapsulated in a [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file located at `skills/<skill-name>/SKILL.md`, following a strict two-part architecture that separates machine-readable metadata from human-readable instructions.

## YAML Front Matter: The Required Metadata Header

Every SKILL.md file must begin with a YAML block that defines the skill's identity and routing information. This front matter enables the Claude agent to discover, validate, and invoke the correct skill based on conversation context.

The required fields include:

- **`name`**: A hyphen-only identifier used for routing (e.g., `react-expert`)
- **`description`**: Trigger-only wording explaining when to use the skill (maximum 1024 characters)
- **`license`**: Always set to `MIT` for this repository
- **`metadata`**: A nested object containing project-specific data:
  - `author`: GitHub profile URL of the creator
  - `version`: Semantic version in quotes (e.g., `"1.0.0"`)
  - `domain`: High-level category (e.g., `frontend`, `backend`)
  - `triggers`: Comma-separated keywords for routing (e.g., `React, JSX, hooks`)
  - `role`: Skill level designation (`specialist`, `expert`, etc.)
  - `scope`: Type of work (`implementation`, `review`, etc.)
  - `output-format`: Expected deliverable (`code`, `document`, etc.)
  - `related-skills`: Other complementary skills (e.g., `fullstack-guardian, playwright-expert`)

The complete front-matter specification is governed by the project's configuration file at **[`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** in the repository root.

## Human-Readable Body: The Progressive Disclosure Content

Following the YAML block, the body of a SKILL.md file implements a **progressive-disclosure** architecture that keeps the primary file lightweight (approximately 70-80 lines) while providing comprehensive guidance. The body uses standard Markdown with specific mandatory sections.

### Role Definition and Trigger Conditions

The body opens with an H1 title (`# Skill Title`) followed by a **Role Definition** section that establishes the persona the agent should adopt. This is followed by **When to Use This Skill**, which provides concrete scenarios as bullet points that align with the YAML `description` trigger.

### The Five-Step Core Workflow

Every SKILL.md must include exactly **five ordered steps** in the **Core Workflow** section:

1. **Analyze** — Evaluate the request and context
2. **Design** — Choose appropriate patterns and architecture
3. **Implement** — Write the actual code or content
4. **Optimize** — Refactor for performance and readability
5. **Test** — Verify correctness and edge cases

This standardized workflow ensures consistent agent behavior across all skills in the repository.

### Reference Guide for Tier 2 Documentation

The **Reference Guide** section uses a markdown table with three columns: **Topic**, **Reference**, and **Load When**. This maps technical subjects to separate reference files stored in `skills/<skill>/references/`, implementing lazy-loading of deeper documentation (100-600 lines) only when needed.

### Constraints: MUST DO and MUST NOT DO

The **Constraints** section contains two mandatory subsections:

- **MUST DO** — Best practices and required actions
- **MUST NOT DO** — Anti-patterns and prohibited approaches

These enforce strict quality standards and prevent common implementation errors.

### Output Templates and Knowledge Reference

The final sections define **Output Templates** (structured deliverables like component files or test suites) and **Knowledge Reference** (a comma-separated list of technologies, libraries, and concepts the skill commands).

## Reference Files: Tier 2 Deep Documentation

The progressive-disclosure architecture relies on **Tier 2** reference files located at `skills/<skill>/references/<topic>.md`. These files contain the deep technical content (100-600 lines) referenced in the **Reference Guide** table. The agent only loads these files when the "Load When" condition is met, keeping the primary SKILL.md file lightweight and scannable.

## Complete SKILL.md Skeleton Example

The following skeleton demonstrates the complete structure, combining the YAML front matter with all required body sections:

```yaml
---
name: my-skill
description: Use when you need to … (trigger-only wording)
license: MIT
metadata:
  author: https://github.com/your-handle
  version: "1.0.0"
  domain: backend
  triggers: keyword1, keyword2
  role: specialist
  scope: implementation
  output-format: code
  related-skills: another-skill
---

# My Skill

## Role Definition

You are a … specialist with … years of experience.

## When to Use This Skill

- Situation 1
- Situation 2

## Core Workflow

1. **Analyze** …
2. **Design** …
3. **Implement** …
4. **Optimize** …
5. **Test** …

## Reference Guide

| Topic | Reference | Load When |
|-------|-----------|-----------|
| Example | `references/example.md` | condition |

## Constraints

### MUST DO

- Rule 1
- Rule 2

### MUST NOT DO

- Anti-rule 1
- Anti-rule 2

## Output Templates

1. File A
2. File B
3. Short explanation

## Knowledge Reference

Technology 1, Library 2, Pattern 3

```

This skeleton mirrors real-world implementations such as **[react-expert SKILL.md](https://github.com/Jeffallan/claude-skills/blob/main/skills/react-expert/SKILL.md)** and **[python-pro SKILL.md](https://github.com/Jeffallan/claude-skills/blob/main/skills/python-pro/SKILL.md)**.

## Key Files in the Claude Skills Repository

Understanding the structure of a SKILL.md file requires familiarity with the supporting files that define, validate, and extend it:

| File | Purpose |
|------|---------|
| **`skills/<skill>/SKILL.md`** (e.g., [`skills/react-expert/SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/skills/react-expert/SKILL.md)) | The primary skill definition implementing the two-part YAML + body structure. |
| **[`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** | The project configuration file that governs front-matter rules, progressive-disclosure architecture, and validation standards. |
| **[`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py)** | The validation script that enforces SKILL.md structure programmatically, checking YAML syntax, required sections, and naming conventions. |
| **`skills/<skill>/references/*.md`** | Tier 2 documentation files containing deep technical content (100-600 lines) referenced by the **Reference Guide** table. |

## Summary

- A **SKILL.md** file combines **YAML front matter** with a **Markdown body** to define Claude skills in the `Jeffallan/claude-skills` repository.
- The **YAML header** contains required metadata fields including `name`, `description` (≤1024 chars), `license`, and a detailed `metadata` object with routing information.
- The **body** implements **progressive disclosure** with mandatory sections: Role Definition, When to Use This Skill, a five-step Core Workflow, Reference Guide, Constraints (MUST DO/MUST NOT DO), Output Templates, and Knowledge Reference.
- **Tier 2 reference files** in `skills/<skill>/references/` contain deep technical content loaded on-demand via the Reference Guide table.
- The **[`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py)** script and **[`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** specification enforce structural compliance across all skills.

## Frequently Asked Questions

### What is the maximum length for a SKILL.md description field?

The `description` field in the YAML front matter must not exceed **1024 characters**. This field serves as the trigger-only wording that tells the Claude agent when to invoke the skill, so it should be concise and context-specific rather than comprehensive.

### How does the progressive disclosure architecture work in Claude skills?

Progressive disclosure keeps the primary **SKILL.md** file lightweight (approximately 80-100 lines) by placing deep technical content (100-600 lines) in separate **Tier 2** reference files under `skills/<skill>/references/`. The **Reference Guide** table in the main SKILL.md maps topics to these files with "Load When" conditions, ensuring the agent only retrieves detailed documentation when specific technical contexts arise.

### What validation checks are performed on SKILL.md files?

The **[`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py)** script enforces structural compliance by validating YAML syntax, checking for required front-matter fields (`name`, `description`, `license`, `metadata`), verifying that the body contains mandatory sections (Core Workflow with five steps, Constraints with MUST DO/MUST NOT DO), and ensuring file naming conventions and directory structures match the skill name.

### Can a skill reference documentation from other skills?

Yes, the **`related-skills`** field in the YAML metadata allows a skill to declare complementary skills (e.g., `related-skills: fullstack-guardian, playwright-expert`). While the **Reference Guide** typically points to files within the skill's own `references/` directory, the agent can use the `related-skills` metadata to understand ecosystem relationships and potentially load contextual information from associated skill definitions when appropriate.