The short answer
A Skill is a folder that holds a SKILL.md file. The file starts with a brief header carrying two fields, a name and a description, with the instructions below it. The agent keeps only those two fields in view until a request fits, then reads everything. Claude Code, Codex and Cursor all read the same folder.
What problem do Skills solve?
Sound familiar?
You reuse a long prompt whenever you need a marketing page: the sections in order, the style, how it must look on a phone. You paste it each time, trim a paragraph once, and the layout shifts. A colleague asks for it, and the copy you find is weeks old.
A Skill stores that prompt as a folder the agent finds by itself. Take SaaS Product Site: once installed, the agent already knows the working app preview, the pricing toggle and the rest of the layout. You supply only the facts about your product.
Most examples work this way: one settled method for one type of result. Soft Geometry OG produces a 16:9 social card, and other Skills on The Frontier Brief make slide decks, full websites and short video clips.
| Prompt you paste | Skill | |
|---|---|---|
| What you have to spell out | Structure, style and checks, on every run | Only your own material |
| Run after run | Shifts slightly each time | Repeats the same method |
| Passing it on | Hunt for it in old chats | Hand over the same folder |
What does a SKILL.md file contain?
The only required file is SKILL.md; folders of reference notes, scripts and templates are optional. The file has two pieces: a brief header fenced by --- lines, then plain instructions aimed at the agent.
product-site/
├── SKILL.md the one file you must have
├── references/ extra notes, opened only when useful
├── scripts/ programs the agent may run
└── assets/ templates, images and other files---
name: product-site
description: Builds a marketing site for a software product, with
an app preview and a pricing toggle. Use it whenever someone
wants a product or landing site.
---
1. Collect the product name, who it is for, and its main features.
2. Lay out the preview, the feature sections and the pricing block.
3. Open the result at phone width and fix anything that breaks.name
At most 64 characters: lowercase letters, digits and hyphens. It has to be identical to the folder name.
description
At most 1,024 characters. Say what it does and when it applies; the agent leans on that second part when choosing.
Optional
license, compatibility, metadata, allowed-tools
The open Agent Skills specification sets these limits. Claude Code is looser about them: if you omit name, it uses the folder name instead.
How does the agent pick a Skill?
It weighs your request against each description. To stay light, loading happens in three steps:
- 1When the session starts, it reads only the name and description of each installed Skill.
- 2When a request fits a description, or you name the Skill, it pulls in the complete
SKILL.md. - 3During the work, it opens
references/files or runsscripts/if the steps call for that.
That is why a large collection of Skills does not make your agent slower. A Skill nobody has asked for costs roughly a sentence of context.
| Agent | Run a Skill by its name |
|---|---|
| Claude Code | /skill-name |
| Codex | Type $skill-name, or select it from the /skills list |
| Cursor | /skill-name, or attach it with @skill-name |
The agent chooses only as well as the description allows. Triggering explains how to write one that gets picked; meanwhile, naming the Skill directly never fails.
Which agents support Skills?
Nearly every well-known one. Anthropic designed the format for Claude and opened it up as a public standard, published December 18, 2025. The agentskills.io list now counts dozens of tools, from Gemini CLI, GitHub Copilot and VS Code to Cursor, Codex with ChatGPT, and Claude Code.
| Agent | Folder in your home directory |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.agents/skills/ (the older ~/.codex/skills/ is still read) |
| Cursor | ~/.cursor/skills/ or ~/.agents/skills/ |
Every project on that computer can use a Skill in your home folder. Project folders and the other places agents search are in Skill locations.
Should this be a Skill or a prompt?
Make a Skill when the job will come back and should meet the same standard each time. A one-time job needs nothing more than a prompt.
The job will come back
- It needs a checklist, scripts or worked examples
- You want a steady result on every run
- Colleagues will use it as well
It happens once
- Two or three sentences explain it
- You have not settled what you want yet
- None of it is worth keeping
Usually you combine them: the prompt carries today's request, the Skill carries the method. Skills vs prompts goes further.
What should you check before installing a Skill?
Skills can run scripts on your machine, so read any new one before you use it.
Five minutes of checks
- Open
SKILL.mdand see what it is permitted to touch. - Look through every file in
scripts/, since that code runs on your own computer. - On the Skill page, read the Dependencies and Outside costs rows.
- Never put passwords or API keys in a Skill's files or in the conversation.
Safety has the full checklist. When you want to try one, Getting started walks through a first install from start to finish.
Common questions
What does the name Claude Skills mean?
People say Claude Skills when they mean Agent Skills used with Claude or Claude Code. Same format: a folder with a SKILL.md file, which Codex and Cursor read too.
How does Claude choose the right Skill?
It holds your request up against every Skill's description and loads whichever one matches. If you type /skill-name, there is nothing left to guess.
Are Claude Skills free to use?
A Skill is only files, and a free one has no price tag. You do need an agent with Skill support (Claude Code, Cursor, Codex and others) on whatever plan that product asks for. The Frontier Brief offers free Skills as well, for example Editorial Storefront.
Is a Skill just another name for an MCP server?
No. A Skill gives the agent a way of working, and an MCP server gives it a connection to outside tools and data. Plenty of workflows use one of each. Read Skills vs MCP for the details.
Sources
Did this guide help?
