SKILL.md format: the header fields each agent reads
SKILL.md header fields side by side for the Agent Skills spec, Claude Code, Cursor, Codex, OpenCode and Copilot: what travels between them and what does not.
- For
- People writing or moving a SKILL.md between agents
- Written for
- Claude CodeCodexCursorGitHub CopilotGemini CLIOpenCodeAny agent that reads SKILL.md folders
- Time
- 8 min read · updated Nov 21, 2026
The short answer
A SKILL.md starts with a short header between two --- lines. The open Agent Skills spec requires two fields, name and description, and lists license, compatibility, metadata and an experimental allowed-tools as optional. Each agent reads those and adds its own: Claude Code has the most, Cursor adds paths, Codex keeps its extras in a separate agents/openai.yaml file, and Copilot documents license and allowed-tools. Write name and description and the file works in all of them.
If you search for SKILL.md, you are usually either writing one or carrying one from one agent to another and wondering why a field was ignored or rejected. The answer is that the header has a shared core and a different set of extras in each agent. This page puts the six sources next to each other. It reads the spec and each agent’s own documentation on 21 November 2026. We did not install a skill in each agent to test it, so every row is what that page says, with a link at the bottom.
What each place requires, and what it adds
Read down the second column and you can see why name and description are the safe pair: every place lists both, and four of the six require them. Claude Code and OpenCode do not, but both use them when they are there.
The name field
The cheap habit that satisfies all of them: lowercase letters, numbers and single hyphens, up to 64 characters, identical to the folder name. Where skills live lists the folder each agent reads.
The description field
Under 1,024 characters satisfies the spec and sits under Claude Code’s cut. How to word it so the skill triggers when it should is a separate job: Write a description that makes a skill trigger.
Stopping a skill from running on its own
This is the place the agents differ most, because the spec defines no field for it. Each agent added its own.
Codex is the one that moves the setting out of SKILL.md. Its optional agents/openai.yaml file has three sections: interface for how the skill shows in the ChatGPT desktop app, policy for invocation, and dependencies for tools it needs. The file is optional, so a skill with only the shared header is complete in Codex.
A header that works everywhere
Start from the shared core. name and description are in every source above, and license is in the spec and in the Claude Code, OpenCode and Copilot pages, so nothing here is specific to one tool:
Then add an agent’s own field only when you want what it does there. Two facts from Claude Code’s docs help you decide:
- Claude Code ignores a field it does not recognize without reporting an error. So a Cursor
iconorcolorin the header is harmless there. - The opposite is not true in Anthropic’s upload paths. The docs say claude.ai uploads and the Skills API accept only
name,description,license,compatibility,metadataandallowed-tools, and fail on anything else with “Unexpected key(s) in SKILL.md frontmatter”. A Claude Code field such ascontext: forkin a skill you plan to upload is an error.
Whatever you add, the spec’s advice for the body applies everywhere: keep SKILL.md under 500 lines and move long reference material into files the skill points to, since an agent loads the whole file once it picks the skill. How to create a Claude skill walks through the folder and the steps, and skills-ref validate ./my-skill from the spec’s reference library checks the header against the spec.
What Lookbk’s own skills use
We counted the header of every skill package in our repository on 21 November 2026: 274 of them. Every one has a name identical to its folder name and a description. 55 also carry license: MIT. None uses any other field, so the header carries nothing that belongs to a single agent. The skill below is one of them; its page shows what it renders.
For the install route for each agent, see Install a skill in any agent; the per-agent pages for Cursor and Codex cover each one’s folders and settings.
Common questions
- What is a SKILL.md file?
- The one required file in a skill folder. It begins with a header between two
---lines, with at least anameand adescription, and the body below it holds the instructions. The agent reads only the header until a request matches the skill, then loads the rest. - What fields does SKILL.md need?
- The open spec requires
nameanddescription. Cursor, Codex and GitHub Copilot document both as required. Claude Code and OpenCode treat all fields as optional, but both read them when they are present, so write both. - Is SKILL.md the same in Claude Code, Codex and Cursor?
- The core is the same:
name,descriptionand the Markdown body. The extras differ. Claude Code adds fields such ascontextandmodel, Cursor addspaths, and Codex puts its invocation setting in a separateagents/openai.yamlfile instead of the header. - How do I stop a skill from running automatically?
- In Claude Code, Cursor and OpenCode, add
disable-model-invocation: trueto the header. OpenCode also acceptsmetadata.opencode/autoinvoke: false. In Codex, setpolicy.allow_implicit_invocation: falseinagents/openai.yaml. GitHub Copilot’s page documents no equivalent field. - Does the name have to match the folder?
- The spec and Cursor say it must. GitHub Copilot says it typically does. In OpenCode the ID comes from the path, and the page says V2 does not enforce a match. Keeping the two identical avoids the question everywhere.
- Can I use the same SKILL.md in claude.ai and Claude Code?
- Yes if the header uses only the fields claude.ai accepts:
name,description,license,compatibility,metadataandallowed-tools. Claude Code’s own extra fields cause an upload error in claude.ai and the Skills API.
Sources
What this guide says about other companies’ tools comes from their own documentation, checked on Nov 21, 2026.
Did this guide help?
Read next
All guidesWrite a description that makes a skill trigger
How an agent picks a skill, what to put in its description, and how to test that it triggers when it should and stays quiet when it shouldn’t.
How to create a Claude skill, step by step
Create a Claude skill from an empty folder: write SKILL.md, add scripts, check it triggers, then share it and make it work in Codex and Cursor too.
Where skills live: folders for every agent
The folders Claude Code, Codex, Cursor and other agents read skills from, which copy wins when two share a name, and what cloud agents can see.
Cursor agent skills: add a skill from GitHub, step by step
How to get a skill from a GitHub repository into Cursor: the folders it loads, the plugin route in its docs, Cloud Agents and the frontmatter.
See a skill’s result before you install it.
Every skill page shows what it makes, what it needs and which agents can run it.
