How to Install and Use Agent Skills in Claude Code (SKILL.md Explained)

A step-by-step guide to agent skills in Claude Code: what SKILL.md does, where skills live, how to write one, and how to fix skills that won’t load.

Reviewed by Mindloop Editorial on . Every link in the Sources section at the end was re-checked that day.

Flat illustration of a folder holding a SKILL.md document plugging into a terminal window

If you keep pasting the same instructions into Claude Code, a skill can hold them for you. This guide shows what an agent skill is, where the files go, and how to write and test a small one. It also covers installing skills from plugin marketplaces and the mistakes that stop a skill from loading.

Watch on Mindloop Experience: Set Up Claude Code Like a Pro: Skills, MCP Servers & Plugins

Everything below was checked against Anthropic’s official docs in November 2026. Claude Code changes often, so the linked docs are the final word.

What an agent skill is

A skill is a folder with a file called SKILL.md inside it. The file has two parts. At the top is YAML frontmatter between --- markers, holding a name and a description. Below that are plain Markdown instructions that Claude follows when the skill runs.

A skill folder can also hold extra files, such as reference notes, templates or scripts.

Skills load in stages, which Anthropic calls progressive disclosure. At startup, Claude loads only each skill’s name and description. The full instructions load when the skill is triggered, and bundled files load only if Claude opens them. So you can install many skills without filling the context window.

What you need

  • Claude Code installed and signed in
  • A terminal and a text editor
  • A git project to test with (the example skill writes commit messages)

Step 1: Pick where the skill lives

Where you save a skill decides which sessions can see it. The two locations you will use most are:

  • Personal: ~/.claude/skills/<skill-name>/SKILL.md. Available in all your projects on this machine.
  • Project: .claude/skills/<skill-name>/SKILL.md inside a repository. Available in sessions in that repo. Commit it and your team gets it too.

There are also enterprise, nested and plugin locations. If a personal and a project skill share a name, the personal one wins.

One catch: personal skills in ~/.claude/skills/ are not read by cloud sessions or Cowork. For those, the docs say to enable the skill on your claude.ai account or commit it to the repository.

Step 2: Create the folder

We will build a personal skill called commit-message.

Terminal
mkdir -p ~/.claude/skills/commit-message

Expected result: the command prints nothing. The empty folder now exists.

Step 3: Write SKILL.md

Create ~/.claude/skills/commit-message/SKILL.md and paste this in. The filename must be exactly SKILL.md.

Code
---
name: commit-message
description: Writes a clear git commit message from the staged changes. Use when the user asks for a commit message, wants to commit their work, or asks how to describe their changes.
---

# Commit message writer

1. Run `git diff --staged` to see what is staged.
2. If nothing is staged, say so and stop.
3. Write a subject line in the imperative mood, under 72 characters.
4. Leave one blank line, then add a short body that explains why the change was made.
5. Show the message in a code block. Do not run `git commit` unless the user asks.

A few notes on the frontmatter:

  • name becomes the command you type. If you leave it out, Claude Code uses the folder name.
  • description is what Claude reads to decide whether to use the skill. Say what the skill does first, then when to use it.
  • The opening --- must be the very first line of the file. Otherwise Claude Code treats the whole file as plain content.

Claude Code accepts more fields, such as disable-model-invocation and allowed-tools. But claude.ai uploads and the Skills API accept only six: name, description, license, compatibility, metadata and allowed-tools. Sticking to name and description keeps your skill portable.

Step 4: Test it

Stage a small change in any git project, then start Claude Code.

Terminal
git add .
claude

You can trigger the skill two ways. First, ask in plain words and let Claude pick it up from the description:

Code
Can you write a commit message for what I've staged?

Or call it directly by name:

Code
/commit-message

Expected result: Claude runs git diff --staged and replies with a subject line and short body in a code block.

You do not need to restart after editing. Claude Code watches ~/.claude/skills/ and the project’s .claude/skills/, and picks up changes in the current session.

Step 5: Add supporting files (optional)

As a skill grows, move detail out of SKILL.md. The docs suggest keeping it under 500 lines. A layout might look like this:

Code
commit-message/
├── SKILL.md
├── examples.md
└── scripts/
    └── check-length.sh

Link the extra files from SKILL.md so Claude knows when to open them. Scripts are run, not loaded into context.

Step 6: Install skills from a plugin marketplace

You do not have to write every skill yourself. In Claude Code, skills can come bundled in plugins, and plugins come from marketplaces. Anthropic’s official marketplace, claude-plugins-official, is added for you the first time you start an interactive session.

Anthropic’s public skills repository on GitHub can also be added as a marketplace. Its README gives these commands:

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

In a session, /plugin install opens the plugin panel so you can review the plugin and choose a scope before it installs. Plugin skills are namespaced, so a skill named review in a plugin called my-plugin runs as /my-plugin:review.

Skills vs MCP servers vs CLAUDE.md

CLAUDE.md holds standing facts and rules that load in every session, such as “use pnpm” or “tests live in tests/“. Keep it short, because it is always in context.

Skills hold procedures and reference material that matter only some of the time. Anthropic’s advice is to make a skill when a section of CLAUDE.md has grown into a procedure, or when you keep pasting the same checklist into chat.

MCP servers connect Claude to outside tools and data, such as a database, an issue tracker or a design app. A skill can tell Claude how to use those tools well, but it does not provide the connection.

Skills outside Claude Code

The same format works across Claude’s products. According to Anthropic’s overview, custom skills can be created in Claude Code, uploaded through the Claude API, or added in claude.ai settings. Skills uploaded to claude.ai must be uploaded separately to the API.

A note on security

A skill is not just text. It can include scripts, and it can steer Claude to run commands and call tools. Anthropic’s guidance is to use skills only from trusted sources, meaning ones you wrote or got from Anthropic. If you try one from elsewhere, read every file first, including scripts, and look for unexpected network calls or file access.

Common errors and fixes

Claude never uses the skill on its own

The usual cause is a vague description. “Helps with git” gives Claude little to match. Write what the skill does and the phrases people would actually say. You can also ask Claude “What skills are available?” to check that it loaded, and use /skill-name to run it directly.

The skill does not appear at all

Check the path and the case. It must be ~/.claude/skills/<skill-name>/SKILL.md, with the file inside its own folder, not loose in skills/. The docs also list characters a name cannot hold, such as <, > or a leading or trailing space.

The frontmatter is broken

If the YAML does not parse, Claude Code still loads the body but with empty metadata. /skill-name still works, but Claude cannot match your description. Start Claude Code with claude --debug to see the error, or run claude plugin validate ~/.claude/skills to find bad files.

Name format rules

For claude.ai and the API, name must use only lowercase letters, numbers and hyphens, be 64 characters or fewer, and must not contain the words anthropic or claude. The description can be up to 1,024 characters. Also avoid naming a folder synced, which Claude Code reserves for skills downloaded from claude.ai.

Changes are not picked up

Edits to existing skills load without a restart. But if you created a top-level skills directory that did not exist when the session started, run /reload-skills. For new plugins, run /reload-plugins or restart Claude Code.

The skill fires too often

Make the description more specific. If you only ever want to run it by hand, add disable-model-invocation: true to the frontmatter.

Wrapping up

A skill is a folder, a SKILL.md file and a good description. Start with one task you repeat every week, write the steps down, and test it with a plain request and with /skill-name. Review anything you install before you trust it.

Sources and official docs

Links last checked on 15 November 2026.

Written by Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on AI and technology, software and the business of tech, for anyone who likes to know how things actually work.

Meet the editorial team

Responses

Write a response

More from Mindloop Experience

See all from Mindloop Experience

You can clap up to 50 times.