skill.md is plain Markdown with two parts: a small metadata header and a
structured body. The header makes the skill discoverable and installable; the body
is what your agent reads.
Metadata header
The header is YAML frontmatter describing the skill at a glance:Structured body
Below the header is the content your agent consumes — organized into the sections that matter for the source type. The exact headings depend on the mode, but the goal is constant: everything the agent needs, nothing it doesn’t.Overview
Overview
A short orientation: what the source is, who it’s for, and the core mental model.
Key concepts
Key concepts
The vocabulary and ideas an agent must hold to reason about the source correctly.
Reference
Reference
The concrete details — endpoints, components, tokens, or APIs — depending on mode.
Examples
Examples
Representative snippets that show real usage, not just signatures.
Gotchas
Gotchas
Edge cases, limits, and footguns worth flagging before the agent hits them.
Designed for agents
Token-aware
Distilled rather than dumped, so it fits a context window with room to spare.
Self-contained
One file your agent can read start to finish without fetching anything else.