Back to Blog

Claude Skills Explained: What They Are and How to Write One

November 13, 2026by TypeFire
claude skillsclaude code skillsagent skillsskill.mdhow to write a claude skillclaude skills vs claude.md

Ask Claude to do the same job twice and you explain it twice: how your team writes release notes, which columns the report needs, what the form wants in box 7. A skill is how you explain it once.

A Claude skill is a folder that teaches Claude one job. Claude keeps a short list of the skills it has, and opens the right one when you ask for that job.

Claude Skills Explained: What They Are and How to Write One

The short version

  • A skill is a folder with a SKILL.md file inside: a name, a description, then instructions in plain Markdown.
  • Claude reads descriptions first. The full skill loads only when your request matches, so fifty skills cost almost nothing until one is used.
  • The description is the trigger. A vague one means the skill never runs.
  • Rules go in CLAUDE.md, jobs go in skills. One is always loaded, the other only when needed.

What is a Claude skill?

A skill is a folder named after one job, with a file called SKILL.md inside it. The file starts with two settings, a name and a description, and continues with the instructions Claude should follow.

A release-notes skill folder with SKILL.md, a references folder and an assets folder, and the SKILL.md name and description open beside it
A skill is a folder. SKILL.md is the only file it must have.

A skill can also carry what the job needs: a script that has to run the same way every time, a style guide, a template. Claude opens those only if the instructions point to them.

Anthropic created the format and published it as an open standard at agentskills.io, which is why a skill written for Claude also works in Codex, Cursor and GitHub Copilot.

How Claude decides to use a skill

Claude does not read every skill in full. That would fill its memory before you typed a word. It loads them 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
Descriptions at the start, the full skill on a match, extra files only if needed.
  1. At the start, Claude reads the name and description of each skill, a line or two apiece.
  2. When you ask for something, it matches your words against those descriptions and loads the skill that fits.
  3. While it works, it opens the skill's extra files only if the instructions send it there.

You can also skip the matching and call a skill yourself. In Claude Code, type / and the skill's name.

A complete skill, start to finish

Here is a skill that writes customer-facing release notes. Save it as SKILL.md in a folder called release-notes.

---
name: release-notes
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.
---

# Release notes

## Steps

1. List the commits since the last tag.
2. Group them under New, Improved and Fixed.
3. Rewrite each line for a customer, in plain words.
4. Leave out refactors and test fixes.

## Example

- New: Export an invoice as a PDF from the invoice menu.
- Fixed: Totals no longer round twice on multi-currency invoices.

You can start from this one and change it in your browser with the free SKILL.md template, then download the file.

Two rules for the settings at the top:

  • name is lowercase letters, numbers and hyphens, and matches the folder name.
  • description says what the skill does and when to use it, in the words a person would type.

Where Claude skills go

In Claude Code, a skill's folder goes in one of two places:

Where Who it is for
.claude/skills/release-notes/SKILL.md in the project Everyone who works on that project
~/.claude/skills/release-notes/SKILL.md in your home folder You, on every project

In the Claude apps, skills are added in settings, and they need code execution turned on.

The same folder works in other agents. Only the parent directory changes.

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
Write the skill once. Each agent reads it from its own folder.

Our SKILL.md guide has the full table of folders for every tool.

Claude skills vs CLAUDE.md

Both are Markdown files Claude reads, and people mix them up. The difference is when each one loads.

CLAUDE.md and AGENTS.md load in every session as rules, while a release-notes skill loads only when a request matches and other skills wait unloaded
Rules are always loaded. A skill waits until its job comes up.
CLAUDE.md A skill
Holds Rules for the whole project One job, in depth
Loads Every session Only when a request matches
Good for Commands, conventions, things to ask first Release notes, a report, a migration check
Cost Paid on every request, so keep it short Almost nothing until it is used

A simple test: if every task needs it, it belongs in CLAUDE.md. If one kind of task needs it, make it a skill.

How to write a skill Claude will use

  • Write the description for the request. Include the words you will type: "release notes", "changelog", "what's new".
  • One job per skill. "Release notes" is a skill. "Everything about releases" is three.
  • Show one example. A finished sample of the output teaches the format faster than a paragraph about it.
  • List the edge cases. What to do when there is no tag yet, or the export is empty.
  • Keep it short. Move a long style guide into a file beside SKILL.md and link to it.
  • Make risky skills wait for you. For a skill that deploys or deletes, set disable-model-invocation: true in Claude Code so it runs only when you call it.

See your skills the way you review them

A skill is written for Claude and reviewed by you, and a wall of YAML and symbols is hard to review.

A project folder in the TypeFire sidebar with CLAUDE.md, AGENTS.md, SKILL.md and Cursor rules labeled and listed first, and CLAUDE.md open formatted in a tab
TypeFire 7 lists a project's agent files first and shows each one formatted.

TypeFire 7 for Mac opens a project folder and lists its skills, CLAUDE.md and AGENTS.md first, formatted: the name and description as a small table, the steps as a list. When Claude rewrites a file, the open tab follows. It only reads the folder, so nothing in your project changes unless you edit a file yourself. See AI agent files on the Mac.

Download TypeFire for Mac, free. Or start a skill in your browser with the SKILL.md template.

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.