Claude Code Skills Explained: Create, Install and Use Them

Claude Code skills are why one teammate's Claude writes release notes in the house format while yours writes them like a press release. A skill is a folder with one SKILL.md file that teaches Claude a specific job, and Claude loads it only when your request calls for it. The official reference is long, and the GitHub lists run to hundreds of skills with no on-ramp.

This is the short path: what a skill is, how to create one, how to install other people's, how to run them, and how to fix one that never fires. Every command below was checked against Anthropic's documentation in October 2026, and there are two skills you can copy as they are.

Key takeaways

• A skill is a folder with a SKILL.md file: YAML frontmatter that says what it does and when to use it, then markdown instructions. Every frontmatter field is optional, and description is the one that matters.
• Skills load on demand. Claude sees each skill's name and description up front; the body loads only when the skill is used.
• Where the folder lives sets the scope: personal (~/.claude/skills/), project (.claude/skills/), plugin, or deployed by your organization. Personal beats project when names clash.
• Run a skill by typing /skill-name, or let Claude pick it from your wording. Plugin skills run as /plugin-name:skill-name.
• Custom slash commands were merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.
• Install other people's skills through a plugin marketplace with /plugin install name@marketplace, and read what the plugin adds before you accept it.
• A skill says HOW to do the work. It carries none of your current facts, which is where most generic output comes from.

What is a Claude skill?

Mechanically, a skill is a directory containing SKILL.md. The file has two parts: YAML frontmatter between --- markers that tells Claude what the skill does and when to use it, and markdown instructions Claude follows once the skill runs. Optional files (reference docs, examples, scripts) sit next to it in the same folder.

The design idea is progressive disclosure. Claude Code keeps a listing of every skill's name and description in context so Claude knows what exists. The body loads only when the skill is used, so a skill packed with reference material costs almost nothing until you need it. That is the practical difference from CLAUDE.md, which loads into every session.

It also gives you a test for what goes where. Rules Claude needs on every turn go in CLAUDE.md; procedures go in skills. A set of steps you keep pasting into chat, or a CLAUDE.md section that has grown into a numbered checklist, is a skill waiting to be extracted. Open your CLAUDE.md and mark every block that reads like "when you do X, follow these steps": each one is a candidate.

If you want a second opinion on the file while you do that, a free CLAUDE.md checker that scores it out of 100 and suggests line-by-line fixes runs in your browser with no upload.

Skills are not exclusive to the terminal. Claude Code skills follow the open Agent Skills standard, and the same format works in the Claude apps and the API. Claude Code adds extras on top: control over who can invoke a skill, running a skill in a subagent, and injecting live shell output into it. A skill that uses those extras will not upload to claude.ai unchanged (details below).

A skill is also different from a prompt and from a plugin. A prompt is one-off text you type. A plugin is a packaging layer that can carry skills plus agents, hooks and MCP servers. A skill sits in between: reusable instructions that load when relevant.

Where skills live (and who can use them)

The folder you save a skill into decides who gets it.

On Windows, ~/.claude resolves to %USERPROFILE%\.claude.

When two skills share a name, enterprise beats personal and personal beats project, so your personal deploy runs instead of the repo's deploy. A skill also beats a .claude/commands/ file with the same name. Plugin skills are namespaced, so they never collide with yours. In a monorepo, Claude Code loads project skills from every directory between where you started and the repo root, and picks up a subfolder's skills the first time it reads or edits a file there.

One trap if you work across surfaces: cloud and Cowork sessions do not read ~/.claude/skills/. They load the skills enabled on your claude.ai account, so a skill that only exists on your laptop comes back as not found there. The full scope rules are in Anthropic's Claude Code skills documentation.

How to create a skill, step by step

Here is a complete personal skill you can copy. It summarizes your uncommitted changes and flags anything risky.

Step 1. Make the folder. The folder name becomes the command.

mkdir -p ~/.claude/skills/summarize-changes

Step 2. Write SKILL.md at ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
allowed-tools: Bash(git diff *)
---

Current changes:

!`git diff HEAD`

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

The ! line is dynamic context injection: Claude Code runs the command before Claude sees the skill and pastes the output in its place, so Claude reads your real diff instead of guessing. Two details decide whether it works. Injected commands never stop to ask permission, so anything that would need approval aborts the invocation unless allowed-tools pre-approves it, which is what the Bash(git diff *) line does. And a command that exits with an error aborts the whole skill; git diff HEAD fails in a repo with no commits yet, so append || true wherever a failure is normal.

Step 3. Run it. In any git repo, type /summarize-changes, or just ask "what did I change?". Claude Code watches your skill folders, so new and edited skills work in the current session. If you created a brand-new top-level skills directory mid-session, run /reload-skills instead of restarting.

Rules that keep skills healthy:

• Only SKILL.md is required. Put long reference material in sibling files and say in SKILL.md when to read each one.
• Keep SKILL.md under 500 lines. Past that, split detail into supporting files.
• SKILL.md must sit directly inside the named folder. A path like ~/.claude/skills/summarize-changes/v2/SKILL.md is the most common reason a skill never appears.
• Frontmatter is only read when the opening --- is the very first line of the file.

What to write inside the instructions is its own craft, and our guide to Claude skills best practices covers which lines earn their place in a SKILL.md and which quietly rot it.

Frontmatter fields worth knowing

Every field is optional and Claude Code ignores ones it does not recognize. These are the ones you will actually use:

Outside Claude Code the rules are stricter. A skill uploaded to claude.ai or sent through the Skills API may only use name, description, license, compatibility, metadata and allowed-tools; any other key is a hard error.

Here is a second skill to copy, this time manual-only and with arguments. Save it as .claude/skills/release-notes/SKILL.md in your repo:

---
description: Drafts release notes for a new version from the git log. Use only when the user asks for release notes.
disable-model-invocation: true
argument-hint: "[previous-tag] [new-version]"
allowed-tools: Bash(git log *)
---

Write release notes for $1, covering every commit since $0.

1. Run git log $0..HEAD --oneline and read every commit.
2. Group the user-facing changes under Added, Changed and Fixed.
3. Skip merge commits, version bumps and internal refactors.
4. Write one plain sentence per change, starting with a verb.
5. End with a list of anything that looks like a breaking change.

Run it with /release-notes v1.4.0 v1.5.0. Arguments are 0-based, so $0 is the first value and $1 the second; $ARGUMENTS holds everything you typed after the name. Because of disable-model-invocation: true, Claude will never decide on its own to write release notes mid-conversation.

How to invoke a skill

There are two ways to run a skill, and you will use both.

Automatic. Ask something that matches the skill's description and Claude loads it. With the first example, "what did I change?" triggers summarize-changes because the description names that intent.

Direct. Type /skill-name at the start of a message, with any arguments after it. You can stack up to six skills at the start of one message, and the text after them goes to each as its arguments. A name mentioned mid-sentence, as in "go ahead and /deploy", only gives Claude permission to use the skill; it does not run it.

Older .claude/commands/ files run the same way, because custom commands were merged into skills, and how slash commands, skills and subagents differ covers when to write which.

The description is not documentation. It is the trigger. A vague line like "helps with code" almost never fires; a specific, keyword-rich line fires reliably.

Claude decides whether to load a skill by matching your request against that one line, so write it the way you would actually ask:

• Weak: description: Helps with git.
• Strong: description: Summarizes uncommitted changes and flags risky edits. Use when the user asks what changed, wants a commit message, or asks to review their diff.

Volume matters too. The skill listing gets a budget of about 1% of the model's context window. Install enough skills and Claude Code starts dropping descriptions, beginning with the skills you use least, which strips the very keywords Claude matches on.

Once a skill loads, its content stays in the conversation, but Claude Code does not re-read the file on later turns. After the conversation is compacted, only the first 5,000 tokens of each recently invoked skill are kept, so put the most important instructions near the top of SKILL.md.

How to add skills to Claude Code

There are three ways to get skills someone else wrote.

1. Copy a folder. Any skill on GitHub is just a folder. Copy it into ~/.claude/skills/ or a project's .claude/skills/ and it is available straight away. Read the SKILL.md first: any ! line runs a shell command on your machine.

2. Install a plugin from a marketplace. This is how most shared skills ship. Anthropic's official marketplace, claude-plugins-official, is added for you the first time you start an interactive session, so this works with no setup:

/plugin install skill-creator@claude-plugins-official

In a session that command opens the plugin's details instead of installing blindly. You see what it will add (skills, agents, hooks, MCP servers), and for official plugins an estimate of its context cost. Then you pick a scope: just you in every project, everyone in this repo, or just you in this repo. A plugin can run hooks and MCP servers, so read that pane before you accept.

Any other marketplace has to be added once first. Anthropic's public example skills, which include the Word, Excel, PowerPoint and PDF skills, install like this:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

The same two lines work for our free Claude skills marketplace, where every skill page shows the raw SKILL.md you can read before installing: /plugin marketplace add mkhalid1/locul-skills, then /plugin install locul-seo@locul for the SEO bundle. None of those skills has been measured against a control yet, and each one says so.

After an install, type / and look for the plugin's skills as /<plugin>:<skill>. From your shell, claude plugin install <name>@<marketplace> --scope project does the same thing without opening a session. The full flow, including updates and removal, is in Anthropic's guide to installing and managing plugins. Which skills deserve a slot at all is a separate question, and our list of the best Claude skills worth installing groups them by the job they do.

3. Sync them from claude.ai. Skills you enable on your claude.ai account load in Claude Code when you sign in with the same account (Claude Code v2.1.273 or later). They appear under "claude.ai sync" in /skills. The sync is one-way, does not happen when Claude Code runs on an API key or a cloud provider such as Amazon Bedrock, and can be switched off with syncClaudeAiSkills: false in your settings.

Manage, share and fix skills

Three commands cover day-to-day management:

• /skills lists every skill you have. Type to filter, press t to sort by token count, and press Space or Enter to cycle a skill between on, name-only, user-invocable-only and off.
• /skill-doctor (v2.1.252 or later) shows what each skill costs in context and how often it gets used, so you can find the dead weight.
• /context includes a Skills row showing how much of your window the listing takes.

To share a skill with your team, commit it to the repo's .claude/skills/. To share it beyond the repo, put it in a plugin. To push it to everyone in an organization, deploy it through managed settings.

When a skill misbehaves, the cause is almost always on this list:

Skills vs plugins vs Memory Packs

These three get conflated constantly. They solve different problems.

Skills and plugins sit on the same axis at different scales: what to do, and how to distribute it. Memory Packs sit on a different axis, and it is the one most setups are missing. A skill can be flawless at telling Claude how to write a launch email, and the email will still sound like nobody, because the skill does not know your positioning, the objection you keep hearing on sales calls, or the opinion you formed last week. A Memory Pack is the "your facts" half of the pair: real context you inject into your brain so the same skill produces your output instead of a generic one.

The part nobody tells you: skills go stale too. Here is the failure that shows up a month after you fall for skills. You write one that references your current stack, your naming conventions or your pricing. It works. Then you migrate a library, rename a service or change a price, and the skill keeps confidently applying the old rule. A skill is static text. The moment your reality moves, it is quietly wrong, and you are back to updating it by hand.

The fix is to keep each layer doing one job. Skills hold the durable how: the steps, the format, the checks. Anything that changes (versions, names, prices, decisions) belongs in a memory layer that updates itself, which the skill reads at run time instead of hard-coding.

That current-facts layer is what Locul is built to be. It is a local-first desktop app that builds a second brain from what you already produce (local files, PDFs, dictation, Notion and your LinkedIn profile), keeps it current on its own, and serves it to Claude Code over MCP. When a fact changes, the old version is marked superseded and the new one becomes active, without you editing anything. You can connect Locul to Claude Code over MCP without editing any config by hand: Locul adds its MCP server to Claude Code's user config for you, so your skills pull today's facts instead of last quarter's. Most people install a pile of skills, get a burst of improvement, then plateau, because they fixed the how and never touched the what.

FAQ

What is a skill in Claude Code?

A skill is a folder containing a SKILL.md file that teaches Claude how to do a specific kind of task. The file has YAML frontmatter describing what the skill does and when to use it, and markdown instructions for what to do. Claude loads the full skill only when your request matches its description, or when you type /skill-name.

Are Claude skills only for Claude Code?

No. Skills also work in the Claude apps on the Free, Pro, Max, Team and Enterprise plans. Turn on "Code execution and file creation" under Settings > Capabilities, then toggle skills under Customize > Skills; to add your own, zip the skill folder and choose +, then Create skill, then Upload a skill there. Anthropic's article on how to use skills in Claude has the current steps. On the API, skills are in beta for users of the code execution tool. claude.ai and the API accept fewer frontmatter fields than Claude Code, so a skill using context: fork or disable-model-invocation will not upload unchanged.

How do I create a Claude skill?

Make a folder such as ~/.claude/skills/my-skill/, then add a SKILL.md inside it with a description in the frontmatter and your instructions below. That is the minimum. Claude Code picks it up in the current session, and /my-skill runs it.

How do I use or trigger a skill?

Two ways. Ask something that matches the skill's description and Claude loads it automatically, or type /skill-name at the start of a message to run it directly. Plugin skills run as /plugin-name:skill-name. If automatic loading is unreliable, the description is almost always the problem.

How do I add skills to Claude Code?

Copy a skill folder into ~/.claude/skills/ or your project's .claude/skills/, or install a plugin: /plugin install <plugin>@<marketplace>, adding the marketplace first with /plugin marketplace add owner/repo if it is not Anthropic's official one. Skills enabled on your claude.ai account also sync into Claude Code when you sign in with the same account.

Where are Claude Code skills stored?

Personal skills live at ~/.claude/skills/, project skills at .claude/skills/ inside a repo (commit them to share), and plugin skills inside the plugin's skills/ folder. Organizations can also deploy skills through managed settings. On Windows, ~/.claude resolves to %USERPROFILE%\.claude. Run /skills to see everything that is loaded.

Is a skill the same as a slash command or a plugin?

A skill and a custom slash command are now the same thing: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and the skill wins if both exist. A plugin is different: it is a distribution package that can bundle several skills plus agents, hooks or MCP servers so you can install and update them together.

Will my skills go out of date?

The instructions will not, but any facts baked into them will. If a skill references your stack, naming or pricing, it keeps applying the old values after you change them. Keep the durable "how" in skills and keep the changeable "what is true now" in a memory layer that updates itself, so you are not hand-editing skills every time your reality moves.