Fix: SKILL.md must start with YAML frontmatter (---)

A minimal SKILL.md that works everywhere

Put --- on the very first line, then key: value pairs, then a closing ---. The Markdown instructions go after it. This file uses only the two required fields, so the Agent Skills spec, Claude Code, claude.ai uploads, Cursor and Codex all accept it. More starting files: SKILL.md templates and examples. Not sure where to save the file? See where Claude skills are stored.

---
name: code-review
description: Review code changes for bugs, security risks and missing tests. Use when the user asks for a review of a diff or pull request.
---

# Code review

1. Read the changed files and nearby tests.
2. Report problems that change behavior, most serious first.

The portable fields (Agent Skills spec)

The Agent Skills specification defines six frontmatter fields. Use only these if the skill must run in more than one tool or be uploaded to claude.ai.

Valid names from the spec: pdf-processing, data-analysis, code-review. Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive hyphens).

The spec also recommends keeping SKILL.md under 500 lines and the instructions under 5,000 tokens; only name and description (about 100 tokens) load at startup. Keep file references one level deep from SKILL.md.

Check a folder against the spec with the skills-ref reference library:

skills-ref validate ./my-skill

How Claude Code reads frontmatter

Claude Code is more lenient than the spec. Per the Claude Code skills docs:

• Every field is optional. Only description is recommended; without it, Claude uses the first non-empty line of the Markdown. name defaults to the folder name.
• Frontmatter is read only when the opening --- is the first line of the file. Otherwise the whole file, markers included, is treated as instructions.
• If the YAML doesn't parse, the skill still loads with no fields set: /skill-name works, but Claude can't match your description. Run claude --debug to see the parse error.
• A field name must match exactly, hyphens included. An unknown field is ignored without an error.
• Field names are lowercase and hyphenated, except when_to_use.
• Booleans accept yes, no, on, off, 1 and 0 in any case, as well as true and false, from v2.1.218.
• In a personal or project skill, name only sets the label in skill listings; the command you type comes from the folder name. In a plugin skill, name sets the last part of the command, such as /my-plugin:fancy.
• Command files in .claude/commands/ accept the same fields except name and paths. See Claude Code skills vs slash commands.

Claude Code frontmatter fields

Every field Claude Code documents, with what it's for. All are optional.

Who can invoke a skill: invocation control

Two Claude Code fields decide whether you, Claude, or both can start a skill, and what sits in context.

disable-model-invocation: true also stops the skill being preloaded into subagents and, from v2.1.196, stops it running when a scheduled task fires with it as the prompt. Cursor supports the same field. Codex has no frontmatter field for this: set policy.allow_implicit_invocation: false in agents/openai.yaml instead.

Description length and the skill listing budget

Claude Code puts every skill's name and description in a listing so Claude knows what exists. The combined description and when_to_use text is cut at 1,536 characters per skill, so put the main use case first. The cap is configurable with the skillListingMaxDescChars setting.

• The whole listing gets 1% of the model's context window. Raise it with skillListingBudgetFraction (for example 0.02) or set a fixed character count with SLASH_COMMAND_TOOL_CHAR_BUDGET.
• When the listing is over budget, the skills you invoke least lose their descriptions first. Names always stay.
• /doctor estimates the listing's cost; /skill-doctor finds skills worth turning off.
• Codex caps its initial skills list at 2% of the context window, or 8,000 characters when the window is unknown, and shortens descriptions first.

Frontmatter for claude.ai uploads and the Skills API

claude.ai skill uploads, the Skills API and package_skill.py from anthropics/skills accept only the six spec fields: name, description, license, compatibility, metadata and allowed-tools. Any other field is a hard error, not a warning. The same applies when you enable a personal Claude Code skill for your claude.ai account (for Cowork, cloud sessions or routines), because that uploads it.

The Claude Help Center lists these other upload failures: the ZIP is too large, the folder name doesn't match the skill name, SKILL.md is missing, or the name or description has invalid characters.

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Cursor frontmatter

Cursor's skill format (Cursor docs) requires name (lowercase letters, numbers and hyphens, matching the parent folder) and description. Optional fields: paths (comma-separated string or list; the legacy globs field still works as a fallback), disable-model-invocation, icon and color (for Custom Modes; color is one of default, green, cyan, blue, purple, magenta, orange, yellow, red or brand), and metadata.

Cursor also reads skills from .claude/skills/ and .agents/skills/, so AIPM installs made with --target claude or --target codex work in Cursor. More: how to install Cursor skills.

Codex frontmatter and agents/openai.yaml

Codex requires name and description in SKILL.md (Codex docs). Display settings, invocation policy and tool dependencies go in an optional agents/openai.yaml next to it, not in frontmatter.

allow_implicit_invocation defaults to true. With false, Codex won't pick the skill on its own, but $skill still works. See Claude Code skills vs Codex skills for other differences.

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

One table: which fields work where

Each cell comes from that tool's own docs, checked 25 September 2026. "Not documented" means the tool's docs don't list the field, so don't rely on it there. For which tools read which files at all, see the AI agent file support table.

The safe rule: if a skill must run in several tools, or be uploaded to claude.ai, use only the six spec fields. Keep Claude Code-only fields in a copy that stays in .claude/skills/.

Frontmatter errors and how to fix them

Match the symptom, then apply the fix.

The exact messages "must be a YAML mapping" and "missing frontmatter" aren't in the Claude Code, Cursor or Codex docs we checked, so this page doesn't say which tool prints them. A YAML mapping is simply a set of key: value pairs.

General YAML rules apply too: indent with spaces, never tabs, and quote a value that contains : or #, or that starts with [, { or *.

Complete examples

Three copy-ready files. The first is safe everywhere; the other two use Claude Code-only fields, so don't upload them to claude.ai as they are.

---
name: release-notes
description: Write release notes from merged pull requests. Use when the user asks for release notes, a changelog entry or upgrade notes.
license: MIT
metadata:
  owner: platform-team
---

---
name: fix-issue
description: Fix a GitHub issue end to end and open a pull request.
when_to_use: Use when the user gives an issue number and asks for a fix.
argument-hint: "[issue-number]"
disable-model-invocation: true
allowed-tools: Bash(gh *) Read Grep
paths: "src/**/*.ts"
---

Fix issue $ARGUMENTS: read it with gh, find the cause, add a test, then fix it.

---
name: deep-research
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly and summarize findings with file references.

Publish a skill with AIPM

AIPM documents name and description as required for every skill you publish. AIPM installs a skill into a folder named after the package's short name (@team/code-review → .claude/skills/code-review/ with --target claude, .agents/skills/code-review/ with --target codex), so set name to that short name to keep the spec and Cursor happy. AIPM copies SKILL.md as published and doesn't rewrite frontmatter for each tool.

Check the frontmatter yourself before you run aipm publish validate. Next steps are in the publishing guide; starting files are on the templates page; a full walkthrough is in how to create an Agent Skill; to get the skill to teammates, see how to share Claude skills with your team.

npm install -g @aipm-registry/cli
aipm skill init --name @team/code-review --template code-review
cd code-review
# add frontmatter (name, description) to the generated SKILL.md if it isn't there, then:
aipm publish add .
aipm publish validate

What fields are required in SKILL.md frontmatter?

name and description. The Agent Skills spec, Cursor and Codex require both, and AIPM documents both as required. Claude Code alone treats every field as optional: it recommends description, and name defaults to the folder name.

How long can a skill description be?

Up to 1,024 characters in the Agent Skills spec. Claude Code also cuts the combined description and when_to_use text at 1,536 characters in its skill listing.

What characters are allowed in a skill name?

Lowercase letters, numbers and hyphens, 1–64 characters, with no leading, trailing or double hyphens. The name must match the skill's folder.

Why does claude.ai say "Unexpected key(s) in SKILL.md frontmatter"?

Uploads and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools. Remove Claude Code-only fields such as argument-hint or when_to_use.

Does allowed-tools restrict which tools a skill can use?

No. In Claude Code it pre-approves the listed tools for the turn that invokes the skill. To remove tools, use disallowed-tools.

How do I stop Claude from triggering a skill automatically?

Set disable-model-invocation: true. You can still run it yourself with /skill-name.

Where does Codex put skill settings like implicit invocation?

In an optional agents/openai.yaml file next to SKILL.md: set policy.allow_implicit_invocation to false. $skill still works.