Short answer: a SKILL.md file is a Markdown file of instructions with a short header, and the folder around it is a skill. The header gives the skill a name and a description. An agent reads every skill's description when it starts, and reads the full instructions only when a task matches. The format began at Anthropic and is now an open standard, Agent Skills, that Claude Code, Codex, GitHub Copilot, OpenCode and many other agents read.
This guide covers the format, every field, where each agent looks for skills, and when a skill is the right tool instead of CLAUDE.md or AGENTS.md. It's all from the official docs, checked on October 27, 2026. (I build Morphy, and we publish free Claude skills for short videos; both come up near the end.)
The smallest SKILL.md
---
name: weekly-recap
description: Writes a short weekly recap of what changed in this repository. Use when the user asks for a recap, a summary of the week, or release notes.
---
1. Read the git log for the last 7 days.
2. Group the changes into Features, Fixes and Other.
3. Write one line per change, in plain language, newest first.Save it as weekly-recap/SKILL.md in a folder your agent reads (see where to put it), and that's a working skill. The part between the --- lines is YAML frontmatter; everything after it is ordinary Markdown.
How agents use it
Agents load skills in three steps, which is why you can keep dozens of them around:
- At startup, only each skill's
nameanddescription, about 100 tokens each. - When a task matches the description, the whole
SKILL.md. - Only if the instructions call for them, the other files in the folder: references, templates, scripts.
So the description does most of the work. If it doesn't say when to use the skill, the agent won't reach for it.
The folder
weekly-recap/
├── SKILL.md required: the header and instructions
├── scripts/ optional: code the agent can run
├── references/ optional: longer docs, read when needed
└── assets/ optional: templates, images, dataPoint to the other files from SKILL.md with relative links (See [the style guide](references/style.md)), one level deep. The standard recommends keeping SKILL.md itself under 500 lines (under about 5,000 tokens) and moving long material into those files.
The frontmatter fields
The open standard has six fields:
| Field | Required | Rules |
|---|---|---|
name | Yes | Up to 64 characters: lowercase letters, numbers and hyphens, not at the start or end, never two in a row. Must match the folder's name. |
description | Yes | Up to 1,024 characters. What the skill does and when to use it, with the words people actually say. |
license | No | A license name, or the name of a license file in the folder. |
compatibility | No | Up to 500 characters on what it needs: a product, tools like git or docker, internet access. Most skills don't need it. |
metadata | No | Your own keys and values, like author and version. |
allowed-tools | No | Tools the skill may use without asking, like Bash(git:*) Read. Experimental: support varies. |
A good description says both parts. The standard's own example: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction." Its example of a poor one: "Helps with PDFs."
To check a skill against the rules, the standard's skills-ref tool runs skills-ref validate ./my-skill.
Claude Code's extra fields
Claude Code reads the six fields above and adds its own. The ones you'll use most:
| Field | What it does |
|---|---|
when_to_use | More trigger phrases, added to the description. Together they're cut off at 1,536 characters in the list Claude sees. |
disable-model-invocation: true | Only you can start it, with /name. For anything with side effects, like /deploy. |
user-invocable: false | Only Claude can use it: background knowledge that isn't a command. |
argument-hint, arguments | What you type after /name, and named values like $issue in the instructions. |
allowed-tools, disallowed-tools | Tools Claude may use without asking, or may not use, while the skill runs. |
model, effort | Run the skill on another model or effort level. |
context: fork | Run it in its own subagent, so it doesn't fill your conversation. |
paths | Only load it automatically when working on matching files, like src/api/**. |
Claude Code also lets the body run a command before Claude reads it: a line like !`git diff HEAD` is replaced with that command's output.
These extras work only in Claude Code. A skill uploaded to claude.ai or the Skills API may use only the standard's six fields; any other one fails with an error like Unexpected key(s) in SKILL.md frontmatter: argument-hint.
Where to put SKILL.md
Each agent reads its own folders, and some read each other's:
| Agent | In a project | For you, in every project |
|---|---|---|
| Claude Code | .claude/skills/<name>/ | ~/.claude/skills/<name>/ |
| Codex | .agents/skills/<name>/ | ~/.agents/skills/<name>/ |
| GitHub Copilot | .github/skills/, .claude/skills/ or .agents/skills/ | ~/.copilot/skills/ or ~/.agents/skills/ |
| OpenCode | .opencode/skills/, .claude/skills/ or .agents/skills/ | ~/.config/opencode/skills/, ~/.claude/skills/ or ~/.agents/skills/ |
So a skill in .claude/skills/ works in Claude Code, Copilot and OpenCode, and one in .agents/skills/ in Codex, Copilot and OpenCode. For all four, keep it in one and copy or link it into the other. Commit the project folder and everyone on the repository gets the skill.
Running a skill: in Claude Code, type /weekly-recap or just ask for a recap. In Codex, type $weekly-recap, pick it from /skills, or let Codex choose it from the description.
Three examples
Knowledge Claude applies while it works. No steps, just conventions:
---
name: api-conventions
description: API design patterns for this codebase. Use when writing or changing API endpoints.
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validationA task only you start. disable-model-invocation keeps Claude from deciding to deploy on its own, and $ARGUMENTS is whatever you type after /deploy:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeededA skill with live context (Claude Code only). The command runs first, so Claude reads your real changes:
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks.SKILL.md vs AGENTS.md vs CLAUDE.md
| SKILL.md | AGENTS.md | CLAUDE.md | |
|---|---|---|---|
| What it's for | One task or area of knowledge | Instructions for a whole project | Instructions for a whole project, for Claude Code |
| When it's read | Only when a task matches (or you call it) | At the start of every session | At the start of every session |
| Read by | Claude Code, Codex, Copilot, OpenCode and more | Codex, Cursor, Copilot, Zed and others, 25+ tools in all | Claude Code |
| How many | As many as you like, one per folder | One per folder | One per folder |
Put facts in AGENTS.md or CLAUDE.md ("we use pnpm", "tests live in tests/"), and procedures in skills. Anthropic's rule of thumb: make a skill when you keep pasting the same instructions or checklist into chat, or when part of CLAUDE.md has grown into a procedure rather than a fact. A skill costs almost nothing until it's used; everything in CLAUDE.md is read every time.
Claude Code now reads AGENTS.md too, when a project has no CLAUDE.md (since version 2.1.277). If you have both, it reads only CLAUDE.md unless you import AGENTS.md into it with a line that says @AGENTS.md.
Before you install someone else's skill
A skill is instructions plus, often, scripts your agent will run with your permissions. Read the SKILL.md and anything in scripts/ before you add it, the way you'd read a shell script from the internet. And don't pay for one: most skills are a page of Markdown, and plenty are free. Here's why you should never pay for a Claude skill.
Skills in Morphy
Morphy has skills of its own, in Settings → Skills: a name, a one-line description and instructions, stored as Markdown files. Type / in a chat's empty box and pick /skills to attach one; it goes along with that message, whichever AI the chat runs on. Import… brings in .md files you already have, and since Morphy 0.1.27, Settings → Community → Playground → Skills has skills other people shared. See Skills.
We also publish Library.md, free Claude skills for short videos: 16 formats, each one SKILL.md your agent follows from the script to the finished video, in Claude Code, Codex or Morphy. The story behind them is in how I make my AI reels.
Questions
What is a SKILL.md file? The instructions file at the heart of an Agent Skill: YAML frontmatter with a name and description, then Markdown instructions. Agents load it when a task matches its description.
Is SKILL.md only for Claude? No. It started at Anthropic and is now an open standard, read by Codex, GitHub Copilot, OpenCode and many other agents.
Where do I put SKILL.md? In a folder named after the skill, inside .claude/skills/ for Claude Code or .agents/skills/ for Codex, in your project or your home folder. See the table above.
Does the name have to match the folder? In the standard, yes. Claude Code is more forgiving: without a name, it uses the folder's name.
How long can a SKILL.md be? Keep it under 500 lines and move long reference material into separate files the skill links to.
What's the difference between skills and slash commands in Claude Code? They've been merged. A file in .claude/commands/deploy.md and a skill in .claude/skills/deploy/SKILL.md both make /deploy; skills add a folder for extra files and can load by themselves.
Related guides
- Never pay for a Claude skill
- Library.md: free Claude skills for short videos
- How to run multiple Claude Code agents at once
- Claude Code worktrees
References
- Agent Skills: overview, specification
- Anthropic: skills in Claude Code, CLAUDE.md and AGENTS.md
- OpenAI: Codex skills
- GitHub: about agent skills
- OpenCode: skills
- AGENTS.md: agents.md
- Morphy: Skills
