A SKILL.md file starts with a YAML block between two --- lines, and that block decides whether Claude ever loads your skill at all. The claude skill frontmatter fields you write there get read into the system prompt at startup, before Claude has seen a single line of your instructions. Get them wrong and the skill sits on disk, invisible. Get them right and Claude picks it up the moment a matching request lands.
The open Agent Skills standard only cares about two fields. Everything else is a Claude Code convenience or a tuning knob you will almost never touch. This reference walks all of them, marks each one required or optional, and gives you the limits that actually get enforced.
The two fields that matter: claude skill frontmatter fields the standard requires
name and description are the core of the Agent Skills format, and the Anthropic skills repo confirms these are the only two the standard treats as required.
name is the skill's identifier. The authoring best-practices guide sets hard rules on it: maximum 64 characters, lowercase letters, numbers, and hyphens only, no XML tags, and no reserved words, which means anthropic and claude are both banned. So pdf-processing is fine while claude-pdf-helper gets rejected outright. Anthropic recommends gerund form, verb plus -ing, so processing-pdfs over pdf-tool. I read that as a convention rather than a hard rule, since noun phrases like pdf-processing pass validation without complaint.
description is the field that gets your skill chosen, and it is the one most people underwrite. Maximum 1024 characters, must be non-empty, no XML tags. Write it in third person, always. The description gets injected straight into the system prompt, and Anthropic's guide warns that first or second person ("I can help you..." or "You can use this to...") causes discovery problems. Pack two things into it: what the skill does, and when to use it, with the trigger words a user would actually type. "Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, or .xlsx files" beats "Helps with documents" every time.
Two character limits to remember, then: 64 for name, 1024 for description.
A minimal valid frontmatter block
Here is the smallest thing that counts as a real Agent Skill across Claude Code, the Claude apps, Codex, Cursor, and Gemini CLI.
---
name: summarizing-prs
description: Summarizes a pull request and flags risky changes. Use when the user asks what a PR does, wants a review, or mentions a diff.
---
# Summarizing PRs
Read the diff, list the substantive changes in three bullets, then flag anything risky.
Two fields, a heading, a few lines of instruction, and you have a shippable skill. If the description is the part you keep rewriting, the longer playbook is in how to write a SKILL.md description, and a fuller starter file lives in the SKILL.md template.
The Claude Code extensions
Here is where the docs diverge, and it trips people up. In Claude Code specifically, name is optional. Leave it out and Claude Code falls back to the directory name, which is also what you type after / to invoke the skill. The frontmatter name only sets the display label in skill listings. So a folder .claude/skills/deploy-staging/ gives you /deploy-staging whether or not you write a name line. A plugin-root SKILL.md is the exception, because there name does set the command, since there is no skill directory to borrow from.
I think that optional-versus-required split is the single most confusing thing about skill frontmatter, and the safe move is to ignore it. Always write both name and description, follow the 64-character lowercase rules, and your skill stays valid everywhere.
Beyond those two, Claude Code adds a stack of optional fields. None belong to the open standard. All of them default to sensible behavior if you omit them.
disable-model-invocation, set to true, stops Claude from loading the skill on its own, and you keep manual /name invocation. That is what you want for anything with side effects, a deploy or a commit or a send-message skill, where you would rather Claude not decide the moment is right.
user-invocable, set to false, runs the other way. It hides the skill from the / menu so only Claude can reach it. Good for background-knowledge skills that explain how some legacy system works but make no sense as a command to type.
allowed-tools pre-approves tools while the skill is active, so Claude runs them without stopping to ask. It accepts a space- or comma-separated string or a YAML list, and it grants permissions rather than taking them away. The allowed-tools field has its own quirks worth reading if you lean on it. Its mirror, disallowed-tools, pulls tools out of the pool entirely until your next message.
The rest are situational. when_to_use appends extra trigger context to the description and shares its character cap. argument-hint and arguments handle autocomplete hints and named positional arguments for $name substitution. model and effort override the model and reasoning level while the skill runs. context: fork runs the skill in an isolated subagent, with agent choosing which type. paths limits auto-activation to files matching glob patterns, hooks scopes lifecycle hooks to the skill, and shell picks bash or powershell for inline command injection.
None of those are required, though. You can write a hundred working skills and never once touch paths or effort.
What to actually do
Write name and description on every skill, obey the 64 and 1024 character limits, keep name lowercase and free of claude or anthropic, and put the trigger words in the description. That covers correctness across every tool that reads the format. Reach for the Claude Code extensions only when you have a concrete reason: disable-model-invocation for side-effect skills, allowed-tools to cut permission prompts, context: fork for isolation.
If you would rather answer a few interview questions than memorize a field table, Knack builds the whole SKILL.md, valid frontmatter included, from a short conversation. Either way, those first two fields are what decide whether your skill ever gets seen.