SkillsPicker

Home / Guides

SKILL.md format

A skill is a folder. The one file it must hold is SKILL.md: YAML front matter between --- lines, followed by Markdown instructions. The Agent Skills spec sets the rules, and Claude Code, Codex, and other agents read the same file.

This guide covers the required fields, the optional ones, the folder layout, size limits, and the extra fields each agent reads. Facts come from the spec and vendor docs, read on October 23, 2026.

Folder layout

my-skill/
  SKILL.md        required: front matter + instructions
  scripts/        optional: code the agent can run
  references/     optional: docs the agent reads when needed
  assets/         optional: templates, images, data files

Codex adds one more optional file, agents/openai.yaml, for display name, icon, and tool dependencies.

Required fields

Field Rules from the spec
name 1 to 64 characters. Lowercase letters, numbers, and hyphens. No hyphen at the start or end. No double hyphens. Must match the folder name.
description 1 to 1,024 characters. Say what the skill does and when to use it. Include the words a user would type.

The spec gives a good description: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction." And a poor one: "Helps with PDFs."

Claude Code is looser. Its docs say all fields are optional in Claude Code, name defaults to the folder name, and description defaults to the first line of the body. Write both anyway, so the skill works in every agent.

Optional fields in the spec

Field Use
license License name, or the name of a bundled license file
compatibility Up to 500 characters on what the skill needs: product, packages, network
metadata Key-value pairs, such as author and version
allowed-tools Tools the skill may use without asking. Marked experimental

A template you can copy

---
name: release-checklist
description: Runs our release steps for a web app. Use when the user asks to cut a release, tag a version, or ship to production.
license: MIT
metadata:
  author: your-team
  version: "1.0"
---

# Release checklist

## Steps
1. Run the test suite. Stop if any test fails.
2. Update CHANGELOG.md with the changes since the last tag.
3. Bump the version in package.json.
4. Tag the commit and push the tag.

## Rules
- Do not skip step 1.
- Ask before you push to main.

## More detail
See [the deploy notes](references/deploy.md).

Size limits and loading

The spec says agents load skills in three steps:

  1. Name and description, about 100 tokens, load at startup for every skill.
  2. The SKILL.md body loads when the agent picks the skill. The spec suggests under 5,000 tokens and under 500 lines.
  3. Files in scripts/, references/, assets/ load when a task needs them.

Move long reference material into references/. Keep links one level deep from SKILL.md, with relative paths.

In Claude Code, the description and when_to_use text share a cap of 1,536 characters in the skill listing. Put the main use case first.

Extra fields in Claude Code

The Claude Code docs list fields beyond the spec. A few you will use:

The body can hold a line like !`git diff HEAD`. Claude Code runs the command and puts its output in the skill before Claude reads it. The docs call this dynamic context injection. It does not work on claude.ai or the API.

If you upload a skill to claude.ai or use the Skills API, the docs say the six spec fields pass and no others. Any other field fails the upload with an "Unexpected key(s)" error.

How to create a skill

  1. Make a folder named for the skill, such as ~/.claude/skills/release-checklist/ for Claude Code or .agents/skills/release-checklist/ for Codex.
  2. Add SKILL.md with name, description, and your steps.
  3. Check it with the spec's validator: skills-ref validate ./release-checklist.
  4. Test it. In Claude Code, type /release-checklist. In Codex, type $release-checklist. Next, ask a question that matches the description and see if the agent picks it.

Both vendors ship a skill that writes skills. Codex has $skill-creator. Claude Code docs describe running evals with skill-creator.

Before you write one, check what exists

Public repos hold tens of thousands of SKILL.md files under open licenses. SkillsPicker indexes them and matches them to your stack. The free scan shows the match count and 2 picks (or the full list free when we have few skills for your stack), so you can see if someone has written yours. Browse by stack, such as React or Go.

FAQ

What is the SKILL.md format? A Markdown file with YAML front matter. name and description are required by the spec. The body holds instructions with no fixed structure.

Does the folder name have to match the name field? Yes, under the Agent Skills spec. Claude Code uses the folder name when name is missing.

How long can a SKILL.md file be? The spec suggests under 500 lines and under 5,000 tokens for the body. Put the rest in references/.

Does the same SKILL.md work in Claude Code and Codex? Yes, if you stick to the spec fields. Fields for Claude Code alone do not carry over to other agents.

Checked 2026-10-23. Prices and policies change. Confirm on the source before you buy.

Sources

More guides