What are Claude Code skills?
Claude Code skills are folders with a file called SKILL.md inside, which Claude Code loads when your request matches or you run yourself with a slash, like /release-notes. The file starts with a short header that gives the skill a name and a description, followed by instructions written in plain Markdown. The folder can also hold scripts, templates or reference files the instructions point to.
Skills follow the open Agent Skills format, so the same folder works in Claude Code and in Codex. You don't have to remember to use them: the agent decides when a skill fits.
Think of a skill as a short onboarding note for one job. It tells Claude the steps your team follows, the format you want back, and what to do when something is missing. Claude already knows how to write a commit message; a skill tells it how you write them.
How does Claude Code use a skill?
- At the start of a session, Claude Code reads only the name and description of each installed skill. That keeps them cheap to have around.
- When your request matches a description, Claude loads that skill's full instructions and follows them.
- You can also run a skill yourself by typing a slash and its name, like
/release-notes.
Because the description decides when a skill is picked, it is the most important line in the file. See how to write a SKILL.md for what makes a good one.
This staged loading is why you can keep many skills installed. Until a skill is used, it costs only its name and description in Claude's context. Once Claude loads a skill, its instructions stay in the conversation for the rest of the session, so keep them focused. The Claude Code docs recommend keeping SKILL.md under 500 lines and moving detailed reference material into separate files.
Where do Claude Code skills live?
- Personal skills, available in every project:
~/.claude/skills/<name>/SKILL.md - Project skills, shared with everyone who works in the repo:
.claude/skills/<name>/SKILL.mdinside the project
The folder name and the name in the file must match.
A few other places can supply skills too:
- Plugins you install from a marketplace bring their own skills, named like
/plugin-name:skill-name. - Nested folders: a
.claude/skills/folder inside a subfolder of your repo loads once Claude starts working with files in that subfolder. Useful in monorepos. - Your Claude account: if you sign in with your Claude account, recent versions of Claude Code download the skills you turned on in the Claude app into
~/.claude/skills/synced/. The Claude Skills guide covers skills in the Claude app and the API.
Claude Code notices new and edited skills in these folders without a restart. Run /skills to see what's installed, or ask Claude "What skills are available?".
A small example
---
name: release-notes
description: Draft release notes from merged pull requests, grouped as New,
Improved and Fixed. Use when the user asks for release notes or a changelog.
---
# Release notes
1. List the pull requests merged since the last tag.
2. Group them as New, Improved and Fixed.
3. Write one plain line per change, from the user's point of view.
4. Skip internal changes like refactors and dependency bumps.
Save it as ~/.claude/skills/release-notes/SKILL.md and Claude Code will pick it up in your next session.
Notice what the example does well. The description names the task and the words people actually say ("release notes", "changelog"). The steps are numbered. And it says what to leave out, which is often what makes output feel right. For more finished files like this, see Claude skills examples.
Run a skill yourself
Typing /release-notes runs the skill straight away. Anything you type after the name is passed to the skill as arguments, and the skill can use them with placeholders such as $ARGUMENTS for everything you typed, or $0 and $1 for single words:
---
name: fix-issue
description: Fix a GitHub issue by number. Use when the user asks to fix,
resolve or work on an issue.
---
Fix GitHub issue $ARGUMENTS. Read the issue with gh issue view, find the
cause, make the smallest change that fixes it, and add a test.
Now /fix-issue 482 fills in the issue number. If a skill has no placeholder, Claude Code adds what you typed to the end of the instructions instead.
Control who runs a skill
By default, both you and Claude can run any skill. Two optional header fields change that:
| Field | Effect | Good for |
|---|---|---|
disable-model-invocation: true |
Only you can run it, with /name |
Deploys, migrations, anything with side effects |
user-invocable: false |
Hidden from the / menu; only Claude uses it |
Background knowledge, like a style guide |
These are Claude Code features. Other agents ignore them, so adding them doesn't break the skill elsewhere. Old custom commands in .claude/commands/ keep working too: Claude Code merged them into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.
Install skills from GitHub
Skills are just folders, so you can copy one into ~/.claude/skills/ by hand. The faster way is the open source skills command, which installs skills straight from a GitHub repo into the right folder for your agents:
# pick skills from a repo
npx skills add https://github.com/<owner>/<repo>.git
# install every skill in it, for all your projects
npx skills add https://github.com/<owner>/<repo>.git --all -g
Point it at a public repo of skills, or at your own private repo. Private repos work as long as your Git can already reach them, for example when you're signed in to GitHub on your computer.
Without -g, skills install into the current project, which is handy when a skill only makes sense for one codebase. The command needs Node.js 22.20 or later. Many collections are also published as Claude Code plugins, which you install with /plugin instead; the best Claude Code skills list gives the right command for each. Whichever way you install, read a skill's files first. A skill can tell Claude to run scripts, so treat it like any other code you add to your machine.
When a skill doesn't trigger
If Claude ignores a skill you expected it to use:
- Check it loaded with
/skills. - Add the words you actually typed to the description. If you say "changelog" but the description only says "release notes", Claude may not connect them.
- Check the header. If the YAML is broken, the skill still loads but without its description, so Claude can't match it. Starting Claude Code with
claude --debugshows the error. - Run it directly with
/nameto confirm the instructions work.
If a skill fires when you don't want it, make the description narrower or add disable-model-invocation: true.
Skills or prompts?
- A prompt is text you paste into a chat yourself, every time. Good for one-off tasks and for tools without skills, like the ChatGPT app.
- A skill is a prompt your agent keeps on hand and uses on its own when the task fits. Good for anything you repeat: code reviews, release notes, commit messages, a house writing style.
A good rule: once you've pasted the same prompt three times, it should be a skill. The free SKILL.md generator turns any prompt into one in a few seconds.
Keeping skills organized
Skills scattered across projects and machines are easy to lose. Kipt keeps your prompts and skills together in a private GitHub repo you own. Paste a prompt to save it, press ⌘K to find it, and turn the ones you reuse into a SKILL.md in one click. Every skill in your library then installs with a single npx skills add command, on any computer.