Back to Blog

SKILL.md Explained: How to Write Agent Skills Your AI Will Use

November 12, 2026by TypeFire
skill.mdagent skillsclaude code skillscodex skillscursor skillshow to write a skillskill.md exampleai agents markdown

Every AI coding agent now reads the same kind of file for teaching it a new job. It's called SKILL.md, it's plain Markdown with a few lines of YAML on top, and the same file works in Claude Code, Codex, Cursor, GitHub Copilot and Antigravity CLI.

Write it once and every agent you use learns the job. Write a weak description and no agent ever uses it. Both halves are below.

SKILL.md Explained: How to Write Agent Skills Your AI Will Use

The short version

  • A skill is a folder with a SKILL.md inside, plus optional scripts/, references/ and assets/.
  • Two fields are required: name (lowercase, matches the folder) and description (what it does and when to use it).
  • The description is the trigger. Agents read only names and descriptions at startup and load the full file when a task matches.
  • Keep SKILL.md under 500 lines and move long reference material into files it links to.

What is a SKILL.md file?

A SKILL.md is the instructions file of an Agent Skill, a folder that packages one procedure an agent can pick up when it needs it: how your team writes release notes, how to fill in a specific PDF form, how to run your data pipeline.

The format was created by Anthropic and released as an open standard at agentskills.io. That's why one folder works across tools: Codex, Cursor, GitHub Copilot in VS Code and Antigravity CLI all read the same file, and Claude Code extends it with a few extra fields of its own.

The smallest valid skill is a folder with one file:

release-notes/
└── SKILL.md

How an agent loads a skill

Skills are cheap to keep around because an agent doesn't read them all at once. The standard calls this progressive disclosure, and it happens in three steps:

Three steps of a skill loading: names and descriptions at startup, the full SKILL.md when a task matches, reference files only if needed
The agent keeps only short descriptions until a task needs the full skill.
Step What the agent loads When
Discovery The name and description of every skill, about 100 tokens each At startup
Activation The full SKILL.md body (the spec suggests under 5,000 tokens) When a task matches the description
Execution Files the skill points to: references, templates, scripts Only if the task needs them

So you can install fifty skills and the agent carries only fifty short descriptions until one is needed. It also means the description does all the work of getting a skill chosen. More on that below.

The SKILL.md format

A SKILL.md has two parts: YAML frontmatter between --- lines, then Markdown instructions. The frontmatter must start on the very first line of the file.

These are the fields the open standard defines:

Field Required Rules
name Yes 1 to 64 characters. Lowercase letters, numbers and hyphens. No leading, trailing or double hyphens. Must match the folder name.
description Yes 1 to 1,024 characters. What the skill does and when to use it.
license No A license name, or the name of a bundled license file.
compatibility No Up to 500 characters on what the skill needs, such as git, Python or network access.
metadata No Any extra key and value pairs, such as author and version.
allowed-tools No Tools the skill may run without asking. Experimental, and support varies by agent.

Claude Code adds fields on top. The most useful ones:

  • disable-model-invocation: true means Claude never runs the skill by itself, only when you type /skill-name. Use it for anything with side effects, like a deploy.
  • user-invocable: false hides the skill from the / menu, leaving it to Claude to load when relevant.
  • argument-hint shows what to type after the command, for example [version], and $ARGUMENTS in the body receives it.
  • context: fork runs the skill in a separate subagent.
A deploy skill with disable-model-invocation set to true, which runs only when the user types /deploy
A skill with side effects should wait to be called by name.

Claude Code will fill in a missing name from the folder and a missing description from the first line of the body. Other agents won't, so write both every time.

A complete SKILL.md example

Here is a skill that writes customer-facing release notes from the commits since the last tag. The project is a made-up invoicing app called Harbor Ledger.

release-notes/
├── SKILL.md
├── references/
│   └── style.md
└── assets/
    └── template.md

SKILL.md:

---
name: release-notes
description: Writes customer-facing release notes for Harbor Ledger from the commits since the last git tag. Use when the user asks for release notes, a changelog, "what's new", or is preparing a version for release.
metadata:
  author: harbor-ledger-team
  version: "1.2"
---

# Release notes

## Steps

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the commits since it with `git log <tag>..HEAD --oneline`.
3. Drop commits that change nothing a customer can see:
   refactors, tests, CI, dependency bumps.
4. Group what's left under **New**, **Improved** and **Fixed**.
5. Write each line as what the customer can now do, in plain words.
   Never name files, functions or internal ticket numbers.
6. Fill in [the template](assets/template.md) and follow
   [the style guide](references/style.md).

## Example

Commit: `fix(pdf): totals row clipped when invoice has 30+ lines`

Release note: "Long invoices now print their totals row in full."

## Edge cases

- No tag yet: use the first commit and say so.
- Only internal commits: reply that there is nothing to announce.

A few things this example gets right:

  • The description names the trigger words people actually type: release notes, changelog, what's new.
  • The steps are numbered and concrete, with the exact commands.
  • One worked example shows the transformation better than a paragraph of rules.
  • Long material lives in other files, linked one level deep, so it loads only when the agent reaches that step.

Where to put skills in each tool

The folder is the same everywhere. Only the parent directory changes.

Agent In a project For you, across projects
Claude Code .claude/skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md
Codex .agents/skills/<name>/SKILL.md ~/.agents/skills/<name>/SKILL.md
Cursor .cursor/skills/ or .agents/skills/ ~/.cursor/skills/ or ~/.agents/skills/
GitHub Copilot in VS Code .github/skills/<name>/SKILL.md ~/.copilot/skills/<name>/SKILL.md
Antigravity CLI (formerly Gemini CLI) .agents/skills/<name>/SKILL.md ~/.gemini/skills/<name>/SKILL.md

Two shortcuts worth knowing. .agents/skills/ is read by Codex, Cursor and Antigravity CLI, so it's the closest thing to a shared home. And Cursor also loads skills from .claude/skills/ and .codex/skills/, so a team on Claude Code and Cursor can share one folder.

One release-notes skill folder and the project folder each agent reads it from: Claude Code, Codex, Cursor, Copilot in VS Code and Antigravity CLI
One folder, read by every agent that supports the standard.

Project skills get committed with the repo, so the whole team picks them up on the next pull. Personal skills stay on your machine.

To run a skill by hand: type /release-notes in Claude Code, Cursor or Copilot, or $release-notes in Codex. Otherwise the agent picks it when your request matches the description.

How to write a description that triggers

When a skill never runs, the description is almost always the cause. The agent compares your request to every description it holds, so the description has to contain the words you'll use.

A description that rarely fires:

description: Helps with release stuff.

One that fires when it should:

description: Writes customer-facing release notes from the commits since the last git tag. Use when the user asks for release notes, a changelog, "what's new", or is preparing a version for release.
A vague skill description next to one that names release notes, changelog and what's new, matched by the request Draft the changelog for 2.4
The words in the description are what the request gets matched against.

The pattern is two sentences. First, what it does, with the specific nouns (release notes, git tag). Then, when to use it, with the phrases and situations that should trigger it. Codex's own docs put it well: explain exactly when the skill should and should not trigger.

In Claude Code, the description and the optional when_to_use field together are cut off at 1,536 characters in the skill list, so put the main use case first.

SKILL.md vs AGENTS.md vs CLAUDE.md

All three are Markdown files for agents. They do different jobs.

AGENTS.md CLAUDE.md SKILL.md
What it holds How to work in this project The same, for Claude Code One procedure, in depth
When it loads Every session Every Claude Code session Only when a task matches
Read by Codex, Cursor, Copilot and more Claude Code Claude Code, Codex, Cursor, Copilot, Antigravity CLI
Good for Commands, conventions, rules Claude-specific rules Release notes, migrations, reviews, forms

A simple rule: if every task needs it, it goes in AGENTS.md or CLAUDE.md. If one kind of task needs it, make it a skill and keep the always-loaded file short. Our AGENTS.md example and Claude Code memory guide cover the other two in depth.

In Claude Code, the old custom commands in .claude/commands/ now work as skills too. A deploy.md there and a .claude/skills/deploy/SKILL.md both give you /deploy. The skill version adds a folder for supporting files and lets Claude load it on its own.

Tips for skills that work

A release-notes skill folder with SKILL.md, a references folder and an assets folder, and the SKILL.md frontmatter open beside it
SKILL.md stays short and links to files one level down.
  • One job per skill. "Release notes" is a skill. "Everything about releases" is three.
  • Keep SKILL.md under 500 lines. Both the standard and Claude Code recommend it. Past that, split detail into references/.
  • Link files one level deep. SKILL.md links to references/style.md, and that file doesn't send the agent somewhere else.
  • Put fragile steps in scripts. If a step has to be exact, like parsing a file, a script in scripts/ runs the same way every time.
  • Turn off auto-run for side effects. A skill that deploys, sends or deletes should only run when you call it. In Claude Code and Cursor that's disable-model-invocation: true.
  • Validate before sharing. The reference tool runs skills-ref validate ./release-notes and checks the frontmatter and naming rules.

Write and reuse skills faster on a Mac

Skills are Markdown, which is what TypeFire is built around.

Typing the TypeFire abbreviation ;skill in an editor fills in a new SKILL.md with frontmatter and the Steps, Example and Edge cases headings
One abbreviation, and every new skill starts from the same template.
  • Start every skill from a snippet. Save the skeleton above as a TypeFire snippet with the abbreviation ;skill, and typing it in any editor, from VS Code to Cursor, fills in the frontmatter and the Steps, Example and Edge cases headings.
  • Give skills a memory. With TypeFire connected to Claude Code, Codex or Cursor over MCP, a skill can say "Search my TypeFire vault for the last release's notes before writing new ones," and the agent reads them from your own Markdown notes on your Mac.
  • Keep the long material as notes. A style guide or a list of past decisions is easier to maintain as a note you open every week than as a file buried in a dot folder.

Download TypeFire for Mac, free. Or see how it works with Claude Code and other AI apps.

In their words

Loved by people who type all day.

Unprompted reactions from users, in their own words.

Exactly what macOS has been needing: blazing fast, beautifully designed, and it respects your privacy without forcing a subscription.
Physician
I use TypeFire every single day, all day long. I love it.
Works at Apple
The way you've handled the AI integrations is very elegant. A great implementation.
Mac user
TypeFire is the absolute replacement for TextExpander.
Works at Apple
I love your app. Love it. The only one that does what I want it to do.
Mac user
I'm loving the date math. Amazing, love it.
ICU doctor
It instantly imported my 502 snippets. Flawless import.
Moved over from TextExpander
Incredibly lightweight. It has quickly become a go-to tool in my daily workflow.
Physician
Love the app, and your development pace rocks.
Longtime user
This app is AWESOME! And I definitely want to buy the Pro version.
Free user
Fantastic. Thank you for the very fast fix.
EU keyboard user
This app has so much potential. I'm really grateful that I found it.
Mac user

Used by people at

AppleRed HatPalo Alto NetworksHubSpotIndeedSentryFreshworksTrustpilotBumbleFarfetchSaint-GobainfoodpandaMcKinseyAccentureIntuitInstacartRakutenDow JonesHearstRokuxAINuroGitGuardianMeltwaterDevRevWoltAirwallex

Company names are places where our users work. They do not imply endorsement or affiliation.