Skip to content
Founding Lifetime: every Pro skillfirst 100 members · $169 onceUpgrade
Lookbk
Sign In

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

SKILL.md header fields, by source
SourceRequiredOptional fields it lists
Agent Skills specname, descriptionlicense, compatibility (up to 500 characters), metadata, allowed-tools (experimental)
Claude CodeNone. description is recommendedwhen_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell. It accepts license, compatibility and metadata but does not act on them
Cursorname, descriptionpaths, disable-model-invocation, icon, color, metadata. The older globs still works in place of paths
Codexname, descriptionNone in the header. Extra settings go in an optional agents/openai.yaml file
OpenCodeNone. “All frontmatter is optional at runtime”metadata.opencode/autoinvoke, disable-model-invocation. It accepts license and compatibility but does not interpret them
GitHub Copilotname, descriptionlicense, allowed-tools. The page documents no other field

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

What each source says about `name`
SourceRule
Agent Skills spec1 to 64 characters: lowercase letters, numbers and hyphens. It must not start or end with a hyphen, must not contain two hyphens in a row, and must match the parent directory name.
Claude CodeOptional; defaults to the directory name and becomes the / command. The page gives no length limit, and refuses names containing characters such as <, > or control characters.
CursorLowercase letters, numbers and hyphens, and it must match the parent folder name.
CodexThe page gives no naming rule. It does say Codex does not merge skills that share a name.
OpenCodeA display name that defaults to the ID taken from the path. For portable skills it advises a lowercase kebab-case ID of 1 to 64 characters that matches the directory, and says V2 does not enforce the pattern, the length or the match.
GitHub CopilotLowercase, with hyphens in place of spaces; typically the same as the skill’s directory name.

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

What each source says about `description`
SourceRule
Agent Skills spec1 to 1,024 characters. It should say what the skill does and when to use it, with keywords that help an agent pick it.
Claude CodeWith when_to_use, it is cut at 1,536 characters in the skill listing, so put the main use first. If you leave it out, Claude Code uses the first non-empty line of the body.
CursorSays what the skill does and when to use it; the agent uses it to decide relevance. No length is given.
CodexCodex uses it to decide when to invoke the skill on its own; the docs advise concise descriptions with clear scope and boundaries.
OpenCodeThe summary shown to the model. A skill with no description is not advertised to it. The page says V2 does not enforce a maximum length.
GitHub CopilotExplains what the skill does and when Copilot should use it. The page gives no length.

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.

Make a skill manual-only
AgentHowWhat still works
Claude Codedisable-model-invocation: true in the headerYou can still run it yourself; Claude will not load it automatically
Cursordisable-model-invocation: true in the headerIt is included only when you type /skill-name
OpenCodedisable-model-invocation: true, or metadata.opencode/autoinvoke: false; the second wins if both are setThe skill stays registered and can still be loaded by its ID
Codexpolicy.allow_implicit_invocation: false in agents/openai.yaml, not in the headerWriting $skill-name in your prompt still runs it
GitHub CopilotThe page documents no such fieldallowed-tools controls which tools run without a confirmation prompt, which is a different thing

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:

release-notes-card/SKILL.md
---
name: release-notes-card
description: Make a 1200 x 630 PNG card from release notes, with the version and three highlights set as real text. Use when someone asks for a changelog card, release graphic or update image.
license: MIT
---

# Release Notes Card

Steps for the agent go here.

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 icon or color in 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, metadata and allowed-tools, and fail on anything else with “Unexpected key(s) in SKILL.md frontmatter”. A Claude Code field such as context: fork in 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.

Editorial OG Card: an example of what it makes
Free
image
Editorial OG CardClaude CodeCodexCursor+3 more agents

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 a name and a description, 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 name and description. 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, description and the Markdown body. The extras differ. Claude Code adds fields such as context and model, Cursor adds paths, and Codex puts its invocation setting in a separate agents/openai.yaml file instead of the header.
How do I stop a skill from running automatically?
In Claude Code, Cursor and OpenCode, add disable-model-invocation: true to the header. OpenCode also accepts metadata.opencode/autoinvoke: false. In Codex, set policy.allow_implicit_invocation: false in agents/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, metadata and allowed-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?

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.