SKILL.md Explained: Format, Frontmatter, and Examples

The SKILL.md format is a simple convention: a Markdown file with YAML frontmatter that packages instructions an AI agent loads on demand. The frontmatter — name and description — tells the agent when the skill applies. The Markdown body tells it what to do. Optional bundled files (reference docs, scripts, templates) provide depth the agent only pulls in when it actually needs it.

That's the whole idea. A SKILL.md file is to an AI agent what a well-written runbook is to a new teammate: it sits on the shelf costing nothing until the moment it's relevant, then delivers exactly the context needed to do the job right. This guide covers the full format — frontmatter fields, body conventions, bundled files, tool support — and ends with a complete annotated example.

Where the SKILL.md format came from

Anthropic introduced SKILL.md as the file format behind Agent Skills in Claude Code. The problem it solves is context economics. Always-loaded instruction files like CLAUDE.md are read into context on every single request, whether they're relevant or not. That works for a page of project conventions; it collapses when you want to teach an agent forty different workflows.

Skills flip the model. At startup, the agent reads only each skill's frontmatter — a name and a one-paragraph description, a few dozen tokens per skill. When a task matches a description, the agent loads that skill's full body. Everything else stays out of context. You can have a large library of skills installed and pay almost nothing for the ones you don't use.

Anthropic published the format openly rather than keeping it Claude-specific, and because a skill is ultimately just Markdown in a folder, it has become the closest thing the ecosystem has to an agent skills open standard. If you're new to the concept itself, start with what agent skills are and why they exist, then come back here for the format details.

SKILL.md frontmatter reference

The frontmatter is a YAML block at the top of the file, delimited by --- lines. Two fields are required; the rest are optional.

A minimal, valid frontmatter block:

---
name: api-conventions
description: REST API conventions for this codebase — route structure,
  error handling, and auth checks. Use when creating or modifying API
  endpoints, route handlers, or middleware.
---

The description is the entire trigger

The single most important line in any SKILL.md file is the description. The agent never reads your carefully written body until the description convinces it to. Weak descriptions ("Helpful API utilities") produce skills that never fire. Strong descriptions name both the capability and the situations that should activate it:

description: Generates and validates database migrations with Drizzle.
  Use when adding tables, changing columns, or the user mentions
  migrations, schema changes, or drizzle-kit.

Write it in the third person, front-load concrete nouns and verbs, and include the trigger phrases a user would actually type. Keep it under roughly 1024 characters — most good descriptions are two or three sentences. If a skill you wrote isn't activating, the description is almost always the culprit; see why Claude skills don't trigger for a debugging checklist.

name rules worth knowing

Keep name short, lowercase, and hyphenated: pdf-processing, commit-conventions, react-component-patterns. It should match the folder the SKILL.md lives in — .claude/skills/pdf-processing/SKILL.md — and stay stable across versions, since tools and teammates reference skills by name.

allowed-tools for safety scoping

allowed-tools limits what the agent can do while the skill is active. A code-review skill might allow file reads but not edits; a reporting skill might exclude shell access entirely. Not every runtime enforces it, but Claude Code does, and declaring intent costs nothing:

allowed-tools: Read, Grep, Glob

The body: instructions, examples, and references

Below the frontmatter, the body is plain Markdown with no required structure — but skills that work well in practice converge on the same shape:

1. A one-paragraph overview of what the skill covers, so the agent orients quickly after loading it.
2. Step-by-step instructions in imperative voice: "Run the validator before committing," not "The validator can optionally be run."
3. Concrete examples — real code, real commands, real input/output pairs. Agents follow examples far more reliably than abstract rules.
4. Edge cases and anti-patterns — the mistakes you'd warn a new hire about.
5. Pointers to bundled files for anything long: "For the full endpoint list, read references/api-reference.md."

Two practical limits. First, keep the body focused on one capability; a skill named testing-conventions that also explains deployment belongs split in two. Second, keep it under about 500 lines. If you're pushing past that, you're pasting reference material into the body that should live in a bundled file instead — which is exactly what the next section is for.

Progressive disclosure: bundled files and scripts

A skill isn't limited to a single file. The SKILL.md sits at the root of a folder that can carry supporting material:

api-conventions/
├── SKILL.md              # required — the entry point
├── references/
│   ├── endpoints.md      # long-form docs, loaded only when needed
│   └── error-codes.md
├── scripts/
│   └── validate.sh       # executable — run, not read into context
└── templates/
    └── route-handler.ts  # boilerplate to copy from

This creates three levels of progressive disclosure:

• Level 1 — frontmatter. Always in context. A few dozen tokens per installed skill.
• Level 2 — the body. Loaded when the description matches the task.
• Level 3 — bundled files. Read (or executed) only when the body directs the agent to them.

Scripts deserve special mention: a deterministic operation like validating a schema or transforming a file is better shipped as a script the agent runs than as instructions it interprets. The script's code never enters the context window — only its output does — and it behaves identically every time.

On localskills.sh, this folder-package model is native: every published skill is a package with a root SKILL.md, and multi-file packages with docs, scripts, and templates are supported up to 100 MB and 500 files per version, with versioning and rollback built in.

Which tools support SKILL.md today

Claude Code supports the format natively: project skills live in .claude/skills/<name>/SKILL.md, personal skills in ~/.claude/skills/, and discovery, triggering, and allowed-tools enforcement are built in. The step-by-step guide to creating a Claude skill walks through that workflow end to end.

For everything else, the honest answer in mid-2026 is: the content is portable even where the format isn't. Cursor wants .mdc rule files under .cursor/rules/, Windsurf wants .windsurf/rules/, Copilot has its own instructions files — but all of them consume Markdown instructions, which is what a SKILL.md body is.

That's the gap a registry closes. When you publish a skill to localskills.sh, the CLI writes each tool's native format from the single published package:

localskills install acme/api-conventions --target cursor claude windsurf

One command installs the same skill as .cursor/rules (.mdc) for Cursor, .claude/skills/ for Claude Code, and .windsurf/rules/ for Windsurf — with GitHub Copilot, Cline, Codex CLI, Aider, and more available as targets. You author against the SKILL.md format once and stop maintaining per-tool copies. For where SKILL.md sits relative to the other instruction-file conventions, see SKILL.md vs CLAUDE.md vs AGENTS.md.

A complete annotated SKILL.md example

Here's a realistic, full SKILL.md example for a database-migration skill. The annotations are in the comments.

---
# name matches the folder: .claude/skills/db-migrations/SKILL.md
name: db-migrations
# The description carries both WHAT and WHEN — including the
# literal phrases a user would type ("add a column", "drizzle").
description: Creates and applies Drizzle ORM database migrations
  safely. Use when adding tables, changing columns, adding indexes,
  or when the user mentions migrations, schema changes, or drizzle-kit.
# Optional — this skill needs shell access but shouldn't be
# restricted further, so we omit allowed-tools entirely.
license: MIT
---

# Database migrations

This project uses Drizzle ORM against Postgres. Schema lives in
src/db/schema.ts. NEVER edit SQL files in drizzle/ by hand —
they are generated.

## Workflow

1. Edit the schema in src/db/schema.ts.
2. Generate the migration:

   pnpm db:generate

3. Review the generated SQL in drizzle/ before applying. Check
   for accidental DROP statements — see the checklist in
   references/review-checklist.md.
4. Apply locally:

   pnpm db:migrate

## Rules

- One logical change per migration. Do not batch unrelated
  schema edits.
- Additive changes only in a first pass (new columns nullable
  or with defaults). Destructive changes ship separately.
- Every new foreign key gets an index.

## Anti-patterns

- Editing an already-applied migration file. Generate a new one.
- Renaming a column in one step. Add the new column, backfill,
  then drop the old one in a later migration.

For the full column-type mapping table, read
references/type-mappings.md.

Folder layout for the same skill:

db-migrations/
├── SKILL.md
└── references/
    ├── review-checklist.md
    └── type-mappings.md

Notice what the body does: imperative steps, real commands, explicit rules, named anti-patterns, and a pointer to reference files instead of a 300-line type table inlined into context. That structure is worth copying wholesale.

SKILL.md format FAQ

Is there an official SKILL.md specification?

Anthropic published the format openly as part of Agent Skills, and its documentation is the de facto SKILL.md specification: YAML frontmatter with required name and description fields, an optional Markdown body, and optional bundled files in the skill's folder. Because it's plain Markdown plus YAML, no special tooling is needed to author or validate one.

What frontmatter fields are required in a SKILL.md file?

Only two: name (lowercase, hyphenated, matching the folder name) and description (what the skill does and when to use it). allowed-tools, license, and metadata are optional extensions.

Is SKILL.md the same as CLAUDE.md?

No. CLAUDE.md is always-on project memory loaded into every session; a SKILL.md is loaded on demand when its description matches the task. Use CLAUDE.md for a small set of universal conventions and skills for everything situational. The full comparison of SKILL.md, CLAUDE.md, and AGENTS.md breaks down when to use each.

How long should a SKILL.md be?

Keep the body under roughly 500 lines. The frontmatter description should be two or three sentences. Anything longer — API references, lookup tables, exhaustive examples — belongs in bundled references/ files the agent reads only when needed.

Can a SKILL.md skill include scripts and other files?

Yes. The SKILL.md is the root of a folder package that can include reference docs, executable scripts, and templates. Scripts are especially valuable for deterministic operations: the agent runs them instead of reasoning through the steps, so only the output consumes context.

---

Ready to put the format to work? Create a free localskills.sh account, publish your first SKILL.md, and install it into every AI tool your team uses with one command.

npm install -g @localskills/cli
localskills login
localskills publish