How to Add Skills to Claude Code

If you have typed the same review instructions into Claude Code more than twice, you already have your first skill — you just haven't saved it yet. A skill is a folder with a markdown file inside it. Setup takes a couple of minutes once you know where things go.

This walkthrough covers how to add skills to Claude Code from an empty directory to a skill that fires reliably: folder locations and scopes, the SKILL.md frontmatter that decides when Claude reaches for a skill, both ways to invoke one, and the mistakes that sink most first attempts. It follows the official Claude Code skills documentation.

How to add skills to Claude Code: the short version

A skill is a directory containing a SKILL.md file. Claude reads the instructions in that file when the skill runs. Put it in the right place, give it good frontmatter, and you're done:

1. Pick your scope. ~/.claude/skills/ for personal skills available in every project, or .claude/skills/ inside a repository for skills scoped to that project (and shareable with your team through git).
2. Create a folder. The folder name becomes the skill's name and its slash command: a folder called release-notes runs as /release-notes.
3. Add a SKILL.md file. YAML frontmatter at the top, markdown instructions below.
4. Use it. Claude Code watches the skill directories, so a new or edited skill is picked up in the current session — no restart.

That's the whole mechanism. No registration, no config file, no build step.

Where your skills live

The location decides who gets a skill and where it applies.

A good rule: generic habits go in your home directory; anything a teammate would benefit from goes in the repository. A release procedure that lives only in your ~/.claude/skills/ is invisible to the next person who clones the repo. Project skills get versioned, reviewed, and travel with the codebase.

What goes inside SKILL.md

SKILL.md has two parts: YAML frontmatter that tells Claude when to use the skill, and markdown that says what to do. A working example:

---
name: release-notes
description: Generates release notes from merged PRs since the last tag. Use when the user asks for changelog entries, release summaries, or version notes.
---

# Release notes

1. Run `git tag --sort=-creatordate | head -2` to find the last two tags.
2. Run `git log --merges --oneline <previous-tag>..<latest-tag>`.
3. Group entries under Added, Fixed, and Changed.
4. Keep each bullet under 12 words. No ticket numbers in the final output.

The description does the heavy lifting. Claude reads descriptions — not full bodies — to decide whether a skill fits the task in front of it, so write them like search queries: name the task, the phrases a user would type, and the output. "Helps with code" will almost never fire. "Use when the user asks to review a diff before opening a PR" will.

A few other frontmatter fields are worth knowing:

• disable-model-invocation: true — only you can run the skill, with its slash command. Use it for anything with side effects: deploys, commits, messages to other people.
• user-invocable: false — hides the skill from the / menu so only Claude can load it, for background knowledge rather than an action.
• allowed-tools — pre-approves the tools the skill needs, so it doesn't stop for a permission prompt on every step.
• context: fork — runs the skill in an isolated subagent, which keeps long tool output (a big diff, a review) out of your main conversation.

Skills can also carry supporting files — a reference.md, examples, a scripts/ folder — that SKILL.md links to and Claude reads only when it needs them.

Write the description for a tired engineer at 6pm, not for yourself on a good day. If you can't tell from the description alone when the skill should run, neither can Claude.

Auto-load vs slash command

There are two ways a skill runs.

Automatically. Claude matches your request against skill descriptions and loads the one that fits. Ask for "the changelog for this release" and release-notes runs without a command.

Explicitly. Type /release-notes yourself, optionally with arguments. For anything destructive or expensive, prefer this route and set disable-model-invocation: true — you don't want Claude deciding to deploy because the code "looks ready."

Adding skills without writing them

Not every skill needs to be hand-rolled.

• Bundled skills. Claude Code ships with skills such as /code-review, /debug, /batch, /loop and /doctor. Try them before writing your own.
• Claude.ai sync. If you sign in to Claude Code with your claude.ai account, skills you've added on claude.ai are downloaded into ~/.claude/skills/synced/ when a session starts and checked for changes about every ten minutes. Set syncClaudeAiSkills to false in your user settings to turn it off on a machine.
• Plugins and marketplaces. Plugins bundle skills; install one with /plugin install <plugin>@<marketplace> and its skills run as /plugin-name:skill-name. Community collections install with their own tooling — our best Claude Code skills roundup covers the ones worth a permanent slot. And if you're extending Claude with tools rather than instructions, see the best MCP servers for Claude Code.

Run /skills at any point to see what's installed and where each skill came from.

Keeping skills consistent across machines

Skills are files on disk, and that is also the problem. A laptop, a desktop and a VM each carry their own ~/.claude/skills/. Write a great skill at work and your home machine never sees it.

The usual fixes are a git repository with symlinks, or a dotfiles manager such as GNU Stow or chezmoi. Symlinks cost nothing and break quietly; a dotfiles manager is sturdier but one more thing to maintain. We compare the two approaches in dotfiles manager vs environment sync tool.

This is the gap loadout fills: install a skill once from the dashboard and the agent on each paired machine puts it in place, so every machine you work from runs the same set. See how syncing works.

Treat skills like code: version them, review them, and never assume the copy on your other laptop is current.

Troubleshooting: when a skill doesn't fire

When a skill doesn't run, the cause is almost always one of these:

• A vague description. "Assists with development tasks" matches nothing concrete. Rewrite it around the phrases a user would actually type.
• The wrong path. Each skill needs its own folder: ~/.claude/skills/my-skill/SKILL.md, never ~/.claude/skills/SKILL.md. The folder name is also the command, so it matters twice.
• Frontmatter typos. YAML is unforgiving: spaces not tabs, and the --- markers on their own lines.
• It's hidden on purpose. user-invocable: false removes it from the / menu; disable-model-invocation: true stops Claude from loading it on its own.

Run /skills. If your skill is listed, the files are fine and the description is the problem. If it isn't, check the folder path.

The first skill worth writing

Skip the clever stuff. The skill that earns its keep is the boring one you've already retyped this week. Claude already knows how to write a commit message in general; what it doesn't know is that your team prefixes branches with ticket numbers and squashes on merge. That gap between general knowledge and your actual habits is exactly where a skill pays off.

So: create a folder under ~/.claude/skills/ named after whatever you repeated this week, paste in your real instructions, and write a description that names the trigger. Once you've added a skill or two this way, the habit sticks, because the payoff shows up the same day.

FAQ

Where do I put skills in Claude Code?

Personal skills go in ~/.claude/skills/<name>/SKILL.md; project skills go in .claude/skills/<name>/SKILL.md inside the repository. Each skill needs its own folder.

What does SKILL.md need?

YAML frontmatter at the top — at minimum a description that tells Claude when to use the skill (name defaults to the folder name) — followed by markdown instructions.

How do I invoke a skill in Claude Code?

Claude loads a skill automatically when your request matches its description, or you run it yourself as a slash command named after its folder: release-notes runs as /release-notes.

Do I need to restart Claude Code after adding a skill?

No. Claude Code watches the skill directories and picks up new, edited or removed skills within the current session.

Can skills from claude.ai sync into Claude Code?

Yes, when you sign in with your claude.ai account: they're downloaded into ~/.claude/skills/synced/ and checked for changes about every ten minutes. Set syncClaudeAiSkills to false to turn it off.

How do I keep the same skills on every machine?

Keep them in a git repository and link them into place, use a dotfiles manager, or install them through loadout, which puts the same skills on every machine you pair.