The short answer
A Skill is a folder with a SKILL.md file inside. The file opens with a short header that holds a name and a description, and the instructions come after it. Your agent keeps only the name and description in mind until a request matches, then reads the rest. The same folder works in Claude Code, Codex, and Cursor.
Why Skills exist
You’ve probably done this
You keep a 40-line prompt for launch pages. It spells out the layout, the sections, and the checks at phone width. You paste it in every time, skip a line once, and the page comes out different. Then a teammate asks for “that prompt” and you send them last month’s copy.
A Skill turns that prompt into a folder your agent finds on its own. Take Meridian Marketing Landing: once it’s installed, the agent already knows the graph-paper hero, the feature grid, and the pricing toggle. You bring your product facts and nothing else.
Most Claude Skills examples follow the same pattern: a fixed method for one kind of output. Notion Style OG Image makes a 16:9 share image, and other Skills on Skillry build slide decks, résumé sites, and short videos.
| Pasted prompt | Skill | |
|---|---|---|
| What you explain | Layout, sections, style, and checks, every time | Just your content |
| From run to run | Drifts a little each time | Follows the same steps |
| Sharing | Dig it out of your chat history | Install the same folder |
What’s inside a SKILL.md file?
A Skill needs one file, SKILL.md, and can carry optional folders for reference docs, scripts, and templates. The file has two parts: a short header between --- lines, then plain instructions written for the agent.
launch-page/
├── SKILL.md required
├── references/ optional: docs read when needed
├── scripts/ optional: code the agent can run
└── assets/ optional: templates and files---
name: launch-page
description: Build a product launch page with a hero, a feature
grid, and a pricing toggle. Use when asked for a launch page.
---
1. Ask for the product name, audience, and three features.
2. Build the hero, the feature grid, and the pricing section.
3. Check the page at phone width before you finish.name
Up to 64 characters, using lowercase letters, numbers, and hyphens. It must match the folder name.
description
Up to 1,024 characters. Say what the Skill does and when to use it; the agent relies on that second half to pick it.
Optional
license, compatibility, metadata, allowed-tools
These limits come from the open Agent Skills specification. Claude Code is more relaxed: you can leave out name and it falls back to the folder name.
How does an agent decide which Skill to use?
It compares your request with each Skill’s description. To keep that cheap, it loads every Skill in three stages:
- 1At startup, it reads the name and description of every installed Skill. Nothing else.
- 2When your request matches a description, or you call the Skill by name, it loads the full
SKILL.md. - 3While it works, it opens files in
references/or runsscripts/only when the instructions tell it to.
This is why you can install dozens of Skills without slowing your agent down. Until a Skill is needed, it takes up about one sentence of context.
| Agent | Call a Skill by name |
|---|---|
| Claude Code | /skill-name |
| Codex | $skill-name, or pick it from /skills |
| Cursor | /skill-name, or @skill-name to attach it |
Automatic picking is only as good as the description. Triggering shows how to write one that gets chosen. Until then, calling the Skill by name always works.
Which agents can use Skills?
Most of the agents you’ve heard of. Anthropic created the format for Claude and published it as an open standard on December 18, 2025. The agentskills.io site now lists dozens of tools that read it, including Claude Code, ChatGPT and Codex, Cursor, VS Code, GitHub Copilot, and Gemini CLI.
| Agent | Personal folder |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.agents/skills/ (also reads the older ~/.codex/skills/) |
| Cursor | ~/.cursor/skills/ or ~/.agents/skills/ |
A Skill in your personal folder is available in every project on your computer. Project folders and every other place an agent looks are listed in Skill locations.
Skill or prompt: which should you use?
Make it a Skill when you’ll repeat the task and want the same quality each time. For a one-off, a prompt is enough.
You’ll do this again
- It needs examples, scripts, or a checklist
- You want the same result every time
- Other people need it too
It’s a one-off
- A few sentences cover it
- You’re still working out what you want
- Nothing in it is worth reusing
Most of the time you use both. The prompt says what you want today, and the Skill says how to do it well. Skills vs prompts goes deeper.
What to check before you install a Skill
A Skill can run scripts on your computer, so give every new one a quick read first.
A five-minute check
- Read
SKILL.mdand note what it’s allowed to change. - Read everything in
scripts/. Those scripts run on your machine. - Check Dependencies and Outside costs on the Skill page.
- Keep passwords and API keys out of Skill files and out of the chat.
The full list is in Safety. When you’re ready to try one, Getting started walks you through your first install.
Common questions
What are Claude Skills?
It’s what most people call Agent Skills when they use them in Claude or Claude Code. The format is the same: a folder with a SKILL.md file. That same folder also works in Codex and Cursor.
How does Claude know which Skill to use?
It compares your request with each Skill’s description and loads the one that fits. Typing /skill-name skips the guesswork.
Can I use Claude Skills for free?
A Skill is just files, so a free one costs nothing. You still need an agent that supports Skills, such as Claude Code, Codex, or Cursor, on whatever plan that product requires. Skillry has free Skills too, such as Dot Avatar Maker.
Is a Skill the same as an MCP server?
No. A Skill teaches the agent a method, while an MCP server connects it to outside data and tools. You’ll often use them together. See Skills vs MCP.
Sources
Did this guide help?