What 765 SKILL.md Files Actually Contain
Before arguing about what a SKILL.md should contain, it helps to know what they do contain.
We extracted every second-level heading from all 765 SKILL.md files (828 ## Overview sections because a few files repeat it):
| Heading | Count |
|---|---|
## Overview | 828 |
## Source | 765 |
## Quick Start | 162 |
## Instructions | 148 |
## When to Use | 130 |
## Core Workflow | 128 |
## Data Sources | 125 |
## Skill Contract | 119 |
## References | 74 |
## Patterns | 69 |
## Related Skills | 69 |
## Reference Guide | 67 |
## Constraints | 66 |
## Pitfalls | 58 |
## Output Templates | 56 |
## Prerequisites | 51 |
## Output | 50 |
## When to Use This Skill | 48 |
The universal two
## Source appears in all 765 files — our importer adds it, so it is not an authoring choice. ## Overview appears in 828 sections across 765 files, which means a handful of files open with more than one.
Everything below those two is an author's decision, and the drop-off is steep: the third-most-common heading appears in 21% of files.
The clusters are author clusters
Several headings are effectively one catalogue's signature:
## Skill Contract— 119 occurrences, all 119 from the same author.## Data Sources— 125 occurrences, 118 from that same author and 7 from one other.
This is the pattern we keep finding: a heading that looks like an ecosystem convention is often one publisher's template. If you sampled ten files from that catalogue, you would conclude "skill contracts are standard". You would be describing one person's style.
What the diversity means
Beyond the clusters, the corpus is genuinely heterogeneous. There are at least four common shapes for describing the same thing:
- Instructions (148) vs Core Workflow (128) vs Quick Start (162) — three names for "what to do".
- Output (50) vs Output Templates (56) — two names for "what you get".
- Constraints (66) vs Pitfalls (58) — two names for "where this goes wrong".
An agent reading one skill at a time does not care. A reader comparing fifty does, because there is no fixed place to look.
The practical takeaway
If you are writing a SKILL.md today, the safest structure is the one a router can parse without reading the whole file:
- Frontmatter with a description that names what, when, and when-not.
## When to Use— including the negative space.- A workflow section with numbered steps.
## Output— what the user sees.- Boundaries and failure handling.
Every one of those headings exists in the corpus with a nontrivial share. None of them is universal. That gap is the room available to a skill that wants to be easier to read than the average.