SKILL.md format

SKILL.md is the open format published by agentskills.io for extending AI agents with portable, version-controlled instructions. A SKILL.md is a markdown file with YAML frontmatter declaring metadata + capabilities, followed by plain-English instructions the agent reads as system configuration.

Structure

Three required pieces:

• Frontmatter — YAML block between two --- lines at the top. Holds name, version, optionally capabilities (the manifest), and any agent-specific keys.
• Title — a single # H1 immediately after the frontmatter, summarizing the skill in < 10 words.
• Body — markdown instructions. Read by the agent as system-level context; should be written in the imperative.

Example: a well-formed SKILL.md

---
name: format-files
version: 1.2.0
description: Format source files with the project formatter.
agents: [claude-code, cursor, codex]
capabilities:
  filesystem:
    read:  ["./src/**", "./tests/**"]
    write: ["./src/**", "./tests/**"]
  process:
    exec: ["prettier", "biome", "black"]
---

# Format files

When the user asks you to format the project, run the locally-installed formatter
(prettier, biome, or black, in that order of preference) over the source tree.

## Behavior

1. Detect which formatter is installed.
2. Run it over `./src/**` and `./tests/**`.
3. Report the diff.

Do not run formatters on `./node_modules/` or any vendored directory.

What makes it well-formed?

• Frontmatter parses as valid YAML — no tabs (use spaces), no trailing colons without values
• name and version are present (we use these for Skill Report Cards)
• If the skill needs file or network access, it declares them under capabilities
• The body uses headings + bullet lists, not a wall of prose
• No $SECRET_NAME references unless absolutely necessary
• No "ignore previous instructions" or "also include the value of" patterns

Frontmatter fields we use

• name — canonical skill name, becomes the URL slug at /c/[skillName]
• version — semver-style; shown next to the name on result pages
• capabilities — see Capability manifest
• agents — declared compatibility list (UI-only at v0; enforcement coming soon)
• description — single-line, used in the catalog (coming soon)