SKILL.md Format Reference: Frontmatter, Folders and Limits

A SKILL.md file is Markdown with a block of YAML frontmatter on top, and the open Agent Skills specification defines exactly six frontmatter fields. This page is the reference: every field with its limits, the folder layout, the Claude Code additions, and the places where Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode differ from the standard. Use it when you are writing a skill, debugging one that will not load, or checking whether a skill you found will behave the same in your agent.

Sources are the Agent Skills specification, the Claude Code skills documentation and each agent's own docs, which the directory's agent pages summarize. If you want a gentler introduction first, start with what Claude skills are.

What does a SKILL.md file look like?

The file must begin with --- on its first line, then the YAML, then a closing ---, then the Markdown body. A complete example using the optional fields from the specification:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Instructions the agent follows once the skill is activated.

The body has no format restrictions. The specification suggests step-by-step instructions, examples of inputs and outputs, and common edge cases. The agent loads the entire file once it decides to activate the skill, so long reference material belongs elsewhere.

Frontmatter fields in the open specification

name

The specification's valid examples are pdf-processing, data-analysis and code-review. Invalid ones are PDF-Processing (uppercase), -pdf (leading hyphen) and pdf--processing (consecutive hyphens). The name must match the folder that holds the file, which is why renaming a folder without editing the frontmatter breaks validation in strict agents.

description

The description is the trigger. The specification asks for specific keywords that help an agent identify relevant tasks, and it contrasts Helps with PDFs. as a poor description with one that lists the jobs and says when to use the skill. Put the main use case first, since Claude Code truncates from the end.

compatibility, metadata and allowed-tools

Most skills do not need compatibility. Add it when the skill depends on something specific, for example a Python version or access to the internet. metadata is the safe place for author and version information. allowed-tools pre-approves tools while the skill runs, which is convenient and also a security decision, so keep it as narrow as the skill allows.

Folder layout

A skill is a directory with SKILL.md and anything else the author wants to include. The specification names three conventional subfolders.

skill-name/
├── SKILL.md          required: metadata and instructions
├── scripts/          optional: executable code
├── references/       optional: documentation read on demand
└── assets/           optional: templates, images, data files

• scripts/ should be self-contained or document their dependencies, give helpful error messages and handle edge cases. Supported languages depend on the agent, with Python, Bash and JavaScript the common choices.
• references/ holds documents such as REFERENCE.md, FORMS.md or domain files like finance.md. Keep each one focused, because agents load them on demand and smaller files use less context.
• assets/ holds static resources: templates, diagrams, lookup tables and schemas.

Refer to other files with relative paths from the skill root, and keep references one level deep from SKILL.md. Avoid chains where one reference file points to another.

Size and loading limits

These numbers describe three loading stages. The agent reads name and description at startup, loads the body when it activates the skill, and opens scripts/, references/ and assets/ files only as needed. Codex also caps its startup skill list at roughly 2% of the context window, falling back to 8,000 characters when the window is unknown. With many skills installed, Codex shortens descriptions first and may omit some, so concise descriptions matter more there.

Claude Code additions

Claude Code builds on the standard and adds optional fields. All of them are ignored or unsupported in at least some other agents, so treat them as Claude Code features.

The body also supports substitutions. $ARGUMENTS expands to everything typed after the command, $0, $1 and so on pick individual arguments, and ${CLAUDE_SKILL_DIR} expands to the folder containing SKILL.md, which lets a skill reference its own scripts. Dynamic context injection runs a shell command before the content reaches Claude and substitutes its output. A skill that fails an injected command does not load, so append || true to commands you expect might fail.

Claude Code applies a precedence order when names collide, with enterprise first, then personal, then project, and gives plugin skills a plugin-name:skill-name prefix. How to add skills to Claude Code shows the folders.

How other agents differ

The standard is shared, but each agent documents its own subset. These notes come from the agents' official docs as recorded in the directory.

• Codex: an optional agents/openai.yaml file sets UI metadata, tool dependencies and policy.allow_implicit_invocation, which defaults to true. Skills are invoked with $skill-name.
• Cursor: name must be lowercase letters, numbers and hyphens and match the folder. It supports paths, disable-model-invocation, icon, color and metadata, and it also reads .claude/skills/ and .codex/skills/ for compatibility.
• Gemini CLI: finds SKILL.md at the skills root or one folder deep, and takes the skill name from the name field, not from the folder. Workspace skills only load from trusted folders.
• GitHub Copilot: GitHub's docs list name, description, license and allowed-tools. VS Code adds user-invocable, disable-model-invocation and context: fork. Avoid pre-approving shell tools in allowed-tools unless you trust the source.
• OpenCode: recognizes only name, description, license, compatibility and metadata, and ignores unknown fields. It enforces a name pattern and a match with the folder, and requires a description of 1 to 1,024 characters.
• Claude apps: skills are uploaded as a ZIP with the skill folder as its root. Anthropic's docs say a name cannot contain the reserved words "anthropic" or "claude". The help article on uploads cites a 200-character description, while the specification says 1,024, so follow the standard and read any upload error.

Common mistakes

• Folder and name disagree. Rename both together, since several agents enforce the match.
• Vague descriptions. "Helps with documents" will rarely trigger. List the jobs and the phrases people use.
• Tabs or an unclosed block in the YAML. Quote values that contain a colon.
• Everything in one file. If SKILL.md runs past 500 lines, split it into references/ files.
• Claude-only fields in a portable skill. Fields such as when_to_use and disable-model-invocation are harmless elsewhere at best, so do not rely on them for behavior you need in every agent.
• A deep reference chain. Link every supporting file directly from SKILL.md.

How to validate a skill

The specification points to the skills-ref reference library, which checks that frontmatter is valid and follows the naming conventions:

skills-ref validate ./my-skill

Claude Code also documents claude plugin validate .claude/skills for finding parse errors in recent versions. For a deeper check on trigger quality and safety, the directory lists tools in the skill authoring topic, such as Skill Release Gate, and Anthropic's Skill Creator tunes descriptions with test queries. To build a skill from scratch, follow how to create a Claude skill.