Guide
The SKILL.md format explained: fields, folders and limits
A skill is a folder with a SKILL.md file in it. The file starts with YAML front matter that needs two fields: a name (1 to 64 characters of lowercase letters, numbers and hyphens, matching the folder name) and a description (1 to 1,024 characters saying what the skill does and when to use it). After the front matter come the instructions, in Markdown. The folder may also hold scripts, reference documents and assets the instructions point to. The format is an open standard, and it loads in stages: the name and description always, the instructions when a task matches, the other files only when needed. That is why the description decides whether a skill is ever used, and why the main file should stay under 500 lines.
Short answer
- A folder with SKILL.md, plus optional scripts, references, assets.
- Required fields: name and description.
- Loads in stages: description first, the rest when needed.
- Open standard: works beyond Claude.
The fields
| Field | Required | Rules |
|---|---|---|
| name | Yes | 1 to 64 characters; lowercase letters, numbers, hyphens; no leading, trailing or double hyphen; same as the folder. Claude: no "anthropic" or "claude" |
| description | Yes | 1 to 1,024 characters; what it does and when to use it. Claude: no XML tags; 200 characters for claude.ai uploads, per the Help Center |
| license | No | A licence name or a bundled licence file |
| compatibility | No | Up to 500 characters on what it needs: product, packages, network |
| metadata | No | Any key-value pairs, such as author and version |
| allowed-tools | No | Pre-approved tools, space-separated (experimental) |
From the Agent Skills specification, Claude Docs and the Claude Help Center, read 5 November 2026.
The folder and how it loads
- Metadata, always: the name and description of every installed skill, about 100 tokens each.
- Instructions, when a task matches: the body of SKILL.md. Keep it under 500 lines.
- Resources, only when needed: files in scripts/, references/ and assets/, linked from SKILL.md by relative path, one level deep.
A worked example
Illustration: a made-up business. An agency's weekly client report, as a complete skill folder named weekly-client-report, with its template in assets/:
---
name: weekly-client-report
description: Writes the weekly client report from the account lead's notes: status, results against target, client actions, next week. Use when someone asks for a weekly report or client update.
metadata:
owner: account-leads
version: "1.2"
---
# Weekly client report
1. Status first, in one line: on track, at risk or off track, and why.
2. Results against the targets in the notes. Use only numbers the notes give.
3. What we did: three bullets at most.
4. What the client must do, with a date. If nothing, say so.
5. Next week: three bullets at most.
Use the template in assets/report-template.md.
Before answering, check: every number is from the notes; the client action has a date.The name matches the folder, the description says what and when in the words people type and stays under 200 characters for claude.ai, and the template sits in a file the skill loads only when it runs.
Check yours
- The name matches the folder, in lowercase and hyphens.
- The description says what it does and "Use when" in your team's words.
- The body is steps and rules, not explanations the AI already knows.
- Long material moves to references/, linked from SKILL.md.
- Validate with the specification's skills-ref tool, then test it in a new chat.
Next step: sharing the file once
A folder sent around as a ZIP drifts into copies. The cheapest way to share AI prompts with a small team compares the ways to keep one copy. The description deserves its own care: see how to write a good skill description. If your team's methods are in Gemini Gems, Google turns them into skills in this format from 17 November: moving Gems to skills before the deadline covers the steps.
Skills for this
- AI practiceTurn a prompt into a skillTurns a prompt that works into a skill the whole team can reuse, with a valid name, a when-to-use description, steps, an output template, an example, and checks.
- Operations and adminWeekly client status reportWrites a one-screen weekly client report: status with a reason, what you need from the client, done, next, and metrics against target.
- AI practiceEval set for an AI taskBuilds a 20-to-50-case eval set for an AI task: normal, edge, and adversarial cases, expected results or rubrics, pass criteria, and a re-run routine.
Questions
What is a SKILL.md file?
The file that makes a folder a skill. It starts with YAML front matter holding at least a name and a description, followed by the instructions in Markdown. The folder can also hold scripts, reference documents and assets the instructions point to.
What are the SKILL.md field limits?
In the Agent Skills specification, the name is 1 to 64 characters of lowercase letters, numbers and hyphens, matching the folder name, and the description is 1 to 1,024 characters. Claude's docs add that neither may contain XML tags and the name can't contain "anthropic" or "claude". The Claude Help Center gives 200 characters for the description of a skill uploaded to claude.ai.
Does a SKILL.md work outside Claude?
Yes. The format is an open standard published at agentskills.io, and other tools read it: Gemini, for example, imports skills from other platforms by uploading their SKILL.md files.
AI skill
Have your AI turn a prompt that works into a skill your team can reuse
Put this skill in AI Skill Pod and everyone on your team gets it in their Claude, Cursor or ChatGPT (Pro, Business, Enterprise): one invite link, free to start. Turn a prompt into a skill turns a prompt that works into a valid SKILL.md: a name in lowercase and hyphens, a when-to-use description, numbered steps with your rules, an output template, one example and checks, tested on fresh inputs.
14 days free · No card needed
Sources
- Agent Skills specification — directory with SKILL.md and optional scripts/, references/, assets/; name 1 to 64 characters, lowercase letters, numbers and hyphens, matching the folder; description 1 to 1,024 characters; optional license, compatibility (up to 500 characters), metadata, allowed-tools (experimental); keep SKILL.md under 500 lines; file references one level deep; validate with skills-ref (read 2026-11-05)
- Claude Docs: Skill authoring best practices — name can't contain XML tags or the reserved words anthropic and claude; description up to 1,024 characters, no XML tags, what it does and when to use it (read 2026-11-05)
- Claude Help Center: How to create custom skills — for skills uploaded to claude.ai: name up to 64 characters, description up to 200; upload a ZIP with the folder at its root in Customize > Skills (read 2026-11-05)
- Gemini Apps Help: About the transition from Gems to skills — skills made on other platforms can be imported into Gemini by uploading their SKILL.md files (read 2026-11-05)