The skills guide. Claude Code first, but the ideas carry across tools.
A skill is one file that runs a whole method.
No app to install. No code to wire up. A skill is a folder with one file inside it. You say the trigger, it fires, and the model runs a tested process instead of winging it. Here is what skills are, where you put them, and how to set them up right.
01 · The basics
What Is A Skill?
Packaged know-how that sits quiet until you say the right thing, then fires with a full method behind it.
1
file to define a skill (SKILL.md)
2
ways to run them (desktop + CLI)
5+
tools read the same skill
3
levels it loads in
A skill is packaged know-how. It sits quiet until you say the right thing, then it fires with a full method behind it. Think of it as a recipe card the model picks up the moment your request matches what is written on the front.
You ask for something
"vet this skill", "research that"
Trigger spotted
the right skill recognises it
Skill fires
full method, not a guess
Result
done the same way every time
One file does the work
A skill is a folder named after the skill, with a file called SKILL.md inside. The top of that file says what it does and when to use it. The rest is the method. That is the whole thing.
Why it beats just asking
Ask a plain question and the model improvises every time. A skill carries a tested process, so the output is the same no matter who runs it or when. That is the gap between "the AI had a go" and "the AI ran our process."
Skills load in layers, so they stay cheap. The model first sees only the name and the one-line description. It reads the full method just when the skill fires. It opens any extra files only if the method points at them. More on that shape in the structure section below.
02 · Not just Claude Code
One File, Many Tools
SKILL.md is an open standard. Write a skill once and a growing list of tools can read it.
Skills are not locked to Claude Code. SKILL.md is an open standard, so the same skill file is read by a growing list of tools. Write a skill once, and it works in more than one place.
Claude Code + Claude apps
The desktop app, claude.ai, and the Claude Code CLI all read skills. This is where we live, and what this guide is built around.
Codex
Codex reads the same SKILL.md format. The file is portable. Only the folder it looks in is different.
Antigravity
Google's agentic IDE picks up skills the same way: name and description first, then the full file when it is needed.
OpenClaw
Our own background assistant pattern reads skills too, so a skill you write can run in a persistent agent.
Hermes
The Hermes agent ecosystem uses SKILL.md skills as well. The standard keeps spreading.
Same file, different home
The portable bit is the SKILL.md file. The folder each tool looks in changes. Claude uses .claude/skills/. Others often use .agents/skills/.
From here on, this guide is Claude Code first. The ideas carry over to the other tools, but the paths and steps below are written for Claude.
03 · Two surfaces
Two Ways To Run A Skill
Two places you set skills up in Claude, and they do not talk to each other. Most people use both.
There are two places you set up skills in Claude, and they do not talk to each other. Pick the one that matches how you work. Most people use both, for different jobs.
The desktop app + claude.ai
Manage skills in a settings panel. Toggle Anthropic's built-in ones on, or upload your own as a zip. Best for everyday work where you do not want to touch the file system.
Claude Code (the CLI)
Skills are just folders in your project or your home directory. Version them with your code, share them with the team, edit them in your editor. Best for builds and serious work.
Heads up: the two surfaces keep separate skills
A skill you upload to the desktop app does not show up in Claude Code, and a skill in .claude/skills/ does not show up in the app. Same idea, separate stores. If you want a skill in both, you put it in both.
Enjoying the guide?
Enter your details to unlock the remaining insights. We'll also send you the complete guide as a reference.
04 · The desktop app
Install A Skill In The Desktop App
The Claude desktop app and claude.ai share one skills panel. Here are the steps, in order.
The Claude desktop app (Mac and Windows) and claude.ai share the same skills panel. Here are the places you set them up, in order.
Turn on code execution first. Go to Settings > Capabilities and switch on "Code execution and file creation". Skills will not run without it. On Team or Enterprise, an owner turns it on under Organization settings > Skills.
Open the skills panel. Go to Customize > Skills. This lists Anthropic's built-in skills and any of your own.
Switch on a built-in skill. Anthropic ships skills for Excel, Word, PowerPoint and PDF. Flip them on. They run on their own when you make those files. Nothing else to do.
Upload your own. Hit "+", choose "Upload a skill", and pick a .zip. Zip the skill folder so SKILL.md sits at the top of the zip, not buried in a sub-folder.
Two limits worth knowing
Per person, not per team. A custom skill you upload is yours. Teammates upload their own. There is no shared library across the org in the app. And it stays in the app. A skill uploaded here does not reach the API or Claude Code. If you build for both, keep a copy in each.
05 · Claude Code
Install A Skill In Claude Code
No upload button. A skill is just a folder on disk. Drop it in the right place and Claude finds it.
In the CLI there is no upload button. A skill is just a folder on disk. Drop it in the right place and Claude finds it. There are two homes.
# Global. Every project on your machine sees it. ~/.claude/skills/ └── deep-research/ └── SKILL.md # Project only. Lives with the repo, ships with the team. your-project/.claude/skills/ └── deploy/ └── SKILL.md
The rule is simple
Make a folder named after the skill. Put a SKILL.md inside it. That is a working skill. The folder name becomes the command, so a folder called deploy/ gives you /deploy.
When names clash, the closest wins
If the same skill name lives in more than one place, the order is enterprise, then your global folder, then the project. Your own copy beats a bundled one. So you can always override a default.
Global vs project: which to pick
Put a skill in ~/.claude/skills/ when it is yours and you want it everywhere, like a research or voice skill. Put it in .claude/skills/ inside a project when it belongs to that project and should travel with the code, like a deploy step or a project check. The team gets it on the next pull.
06 · The shape
The Floor, And The Full Shape
A skill can be one file or many. Start with the floor. Grow into the full shape when the method gets big.
A skill can be two things or many things. Start with the floor. Grow into the full shape when the method gets big.
Preferred: the floor
A folder named after the skill, with a SKILL.md inside. Two things. The top of the file is the front matter (the name and description). Below it is the method.
my-skill/ └── SKILL.md # that's a working skill
--- name: voice-analyser description: Build a tone-of-voice doc from 3 writing samples. Use when someone wants to capture a brand voice. Triggers on "tone of voice", "voice guide". --- Voice Analyser Step 1. Ask for three samples: a post, an article, an email. Step 2. ...the method goes here.
The description is the most important line in the whole file. It is what the model reads to decide when to fire the skill. Say what it does and when to use it. Vague description, and the skill never fires at the right time.
Best: room to grow
When the method gets long, split it. Add folders next to SKILL.md. The skill reads them only when it needs them, so the main file stays short.
my-skill/ ├── SKILL.md # the method, kept short ├── references/ # docs, schemas, examples (read on demand) ├── scripts/ # code it runs (only the output enters chat) └── assets/ # templates and files it drops in
Why split it up
The model loads a skill in three levels. First the name and description, always on and tiny. Then the SKILL.md body, only when the skill fires. Then the extra files, only when the method points at them. So a skill can carry a lot of detail without slowing every chat down.
Real examples from our stack
voice-analyser ships a SKILL.md plus a references/ folder of templates. deep-research adds modes/, references/ and a scripts/ folder with real Python. Same pattern, more parts.
Small print on the front matter
name: lowercase letters, numbers and hyphens, up to 64 characters. It cannot contain the words "claude" or "anthropic". description: up to about 1024 characters, with the triggers packed in. And SKILL.md is uppercase, every time, so the skill stays portable across tools and operating systems.
07 · Two we lean on
Skills That Manage Skills
One helps you write good skills. One guards the front door so a bad skill never gets in.
Two skills do a lot of the heavy lifting in our setup. One helps you write good skills. One guards the front door so a bad skill never gets in.
skill-creator
Anthropic's own skill for building skills. It walks you from idea to a finished SKILL.md, then goes further: it runs evals, benchmarks how well the skill performs, and tunes the description so the skill fires at the right time. The fastest way to author a skill that actually works, not just one that looks right.
github.com/anthropics/skills · skill-creatorskill-vetting
Our front door for any skill coming in from outside. A downloaded skill is untrusted code that runs inside your agents, so it has to earn its place. It runs three gates, in order. First a security scan for prompt injection, data theft, hidden payloads and secret grabbing. Then a score out of 100: adopt, pilot, merge, or bin. Then it decides where the skill goes, if anywhere, and updates our records.
github.com/ai-orchestrators · skill-vettingThe rule that ties them together: nothing from outside touches a live setup until it has passed vetting. Build with skill-creator. Let anything external in only through skill-vetting. You can read the full open standard in Anthropic's skills repo and the Agent Skills docs.
08 · Where to look
Where To Find Skills
Find beats build most days. Check for a proven skill before you write one from scratch.
Find beats build most days. Before you write a skill from scratch, check if a proven one already exists. Grab it, then bend the triggers and steps to fit your work. Far faster than starting from a blank file.
Start with ours
We publish a set of ready-to-use skills, scrubbed clean and free to grab: the voice tools, md-architect, prompt-optimiser, meeting-review, email-triage and more. This is the first place to look.
Our skills on GitHub# grab one straight into your skills folder git clone https://github.com/ai-orchestrators/md-architect.git \ ~/.claude/skills/md-architect
Then the open directory
skills.sh
A package manager and leaderboard for skills from across the web. It ranks them by total installs, so you can see what is popular and well-used before you trust it. Browse, then install in one line.
find-skills
A skill that searches skills.sh for you, right from the terminal. Tell it what you need. It checks the leaderboard, runs the search, weighs each result by install count and source, then offers to install the good one.
# the Skills CLI, the way find-skills drives it npx skills find "pr review" # search the directory npx skills add owner/repo@skill -g # install one globally npx skills check # check for updates
One rule before you install anything
A downloaded skill is code that runs inside your agents. Pick skills with plenty of installs from a name you know. Treat anything with a handful of installs and no track record with care. That is exactly what skill-vetting from the last section is for: it scans any outside skill for anything nasty before it ever touches a live setup.
09 · Your turn
See Your Whole AI Setup In One Place
A handful of skills is easy to track in your head. A real setup is not. You need a map.
A handful of skills is easy to track in your head. A real setup is not. Once you have skills, agents, connectors and jobs running on a clock, you need a map. Otherwise you forget what you have and build the same thing twice.
Build your own AI Stack
A small project that scans your whole setup, lists every skill, agent, connector and automation, and renders it on a dashboard you can actually read. It keeps itself fresh on a schedule. This is how we keep ours straight.
Why it matters
You cannot improve what you cannot see. A stack you can scan is one you can prune, reuse and grow on purpose, instead of letting it sprawl. The guide walks you through building it from scratch.
The whole guide in five lines
- A skill is a folder named after the skill, with a SKILL.md inside.
- Run them in the desktop app (toggle and upload) or in Claude Code (folders on disk).
- The description is what makes a skill fire at the right time. Write it well.
- Build with skill-creator. Let anything external in only through skill-vetting.
- The same SKILL.md works across Claude, Antigravity, Codex, OpenClaw and Hermes.
That is skills, end to end
One file, a tested method, fired on cue. Set up a few, see them in one place, and your AI stops starting from scratch every time. Build with skill-creator, vet anything from outside, and track the lot in your own stack. Now go build one.
Part of the AI Operating System handbook.