Guide

Claude Code Skills: What They Are, How to Build One, and How to Fix One

15 min read·
Claude Code Skills: What They Are, How to Build One, and How to Fix One

Claude Code skills are folders with a SKILL.md file: a short description, then instructions, plus optional scripts or reference files. Claude always sees each skill's description, and loads the rest only when your task matches or you type /skill-name. Personal skills live in ~/.claude/skills/, and project skills in the repo's .claude/skills/.

Questions this page answers

  • What is a Claude Code skill, and what does it cost to have one installed?
  • When should something be a skill instead of CLAUDE.md, a subagent or an MCP server?
  • What goes in a SKILL.md file?
  • How do I create, store and install a skill?
  • How do I share skills with my team?
  • Why isn't my skill triggering?

Writing skills so Claude Code can make more than code?

Bento publishes a skill that lets Claude Code use your Bento workspace: its files and the text, image and video AI in your plan, under one login. Start a workspace and one subscription covers your whole team at no extra cost per person. See Bento's plans.

Checked against Anthropic's Claude Code docs on November 5, 2026.

Updated November 2026: Skill edits now load without a restart, custom commands have merged into skills, claude.ai skills sync into the terminal, and descriptions share a fixed budget. The advice to package repeatable work as skills still stands.

What are Claude Code skills, and how do they load?

A skill is a set of instructions Claude reads only when it needs them. Anthropic's own rule of thumb: make one when you keep pasting the same instructions or checklist into chat, or when part of your CLAUDE.md has turned into a procedure rather than a fact.

Loading happens in three steps:

WhatWhen it's in Claude's contextRough cost (Anthropic's estimate)
Name and descriptionEvery session, from the startAbout 100 tokens per skill
The SKILL.md bodyWhen the task matches, or you type /skill-name. It then stays for the rest of the conversationUsually under 5,000 tokens
Scripts and reference filesOnly when the body tells Claude to open or run themOnly what's read, or a script's output

A token is roughly three-quarters of a word. It's the unit Claude's memory for a conversation is measured in. The estimates come from Anthropic's Agent Skills overview for developers.

Claude Code adds a limit of its own. Each skill's description is cut at 1,536 characters, and all the descriptions together get a budget of 1% of the model's context window. Go over it and the skills you use least lose their descriptions first. Claude then can't match them to your request.

How a Claude Code skill loads: the description is always present, the body loads when the task matches, and scripts or files load only if the body points to them.

Do I need a skill, or something else?

Use a skill for a procedure Claude should follow only some of the time. Facts that apply to every session go in CLAUDE.md, access to outside systems needs an MCP server, and big independent jobs go to a subagent.

You want Claude to…UseWhy
Always know a fact ("we use pnpm", "tests live in /spec")CLAUDE.mdIt loads every session. See how CLAUDE.md memory works
Follow a procedure when it's relevant (review a PR, write release notes)A skillOnly the description loads until it's needed
Run a fixed action when you say so (/deploy)A skill with disable-model-invocation: trueOld .claude/commands/ files still work, but they're now the same thing
Reach a live system (GitHub, a database, Slack)An MCP serverA skill can't log in to anything by itself. Set up an MCP server
Do a big piece of work in its own clean contextA subagentIt doesn't fill your main conversation

They combine. A PR-review skill can tell Claude which GitHub tools to call through MCP, and plugins bundle skills, agents and MCP servers into one install. For the longer comparison, see skills vs MCP, with a worked example.

What goes in a SKILL.md file?

Two parts: a short header (called frontmatter) between --- lines, then plain Markdown instructions. Every header field is optional in Claude Code, but write a description: it's what Claude matches your request against.

---
name: release-notes
description: Drafts release notes from merged PRs. Use when the user asks for release notes, a changelog, or "what shipped".
---

1. List merged PRs since the last tag.
2. Group them as Added, Changed, Fixed.
3. One line each, in words a customer would use.
4. Put breaking changes first.

The --- must be the very first line of the file. Otherwise Claude Code treats the whole file as instructions.

The fields worth knowing:

FieldWhat it does
nameThe command you type. Defaults to the folder name
descriptionWhat the skill does and when to use it. Put the trigger first
when_to_useExtra trigger phrases. Shares the 1,536-character cap with description
disable-model-invocationtrue means only you can run it. Use it for anything with side effects
user-invocablefalse hides it from the / menu, so only Claude uses it
allowed-toolsTools Claude may use without asking, for the turn the skill runs. It doesn't restrict anything
disallowed-toolsTools removed while the skill is active. This is the one that restricts
pathsFile patterns. The skill auto-loads only when Claude works on matching files

Anthropic's skills documentation lists the rest, such as model, context: fork and hooks.

Uploading to claude.ai or the API is stricter. There, name and description are required. A name can be up to 64 characters (lowercase, numbers, hyphens) and a description up to 1,024. Only six fields are accepted: name, description, license, compatibility, metadata and allowed-tools. Any other key fails the upload. Write to those six and the same file works everywhere.

Keep SKILL.md under 500 lines. Move long reference material into separate files and say in the body when to read each one.

How do I create a Claude Code skill?

Make a folder, write the description, write the steps, then test it both ways. Most of the work is the description.

  1. Make the folder. mkdir -p ~/.claude/skills/commit-message for a personal skill. Use .claude/skills/commit-message inside a repo to share it with the project.

  2. Write the description first. Give the skill one job. Say what it does, then when to use it, in the words you'd actually type: "Writes a commit message from the staged diff. Use when the user asks for a commit message or to commit."

  3. Write the body as orders, not explanations. Once it loads, every line stays in the conversation, so cut anything that isn't an instruction:

    ---
    description: Writes a commit message from the staged diff. Use when the user asks for a commit message or to commit.
    disable-model-invocation: true
    allowed-tools: Bash(git diff *) Bash(git commit *)
    ---
    
    Current staged changes:
    !`git diff --cached`
    
    Write a commit message for the changes above:
    - Subject under 50 characters, imperative ("Add", not "Added").
    - A blank line, then a body explaining why, wrapped at 72.
    - If nothing is staged, say so and stop.
    

    The !`git diff --cached` line runs before Claude reads the skill, so the real diff arrives already pasted in.

  4. Test it both ways. Type /commit-message. For a skill without disable-model-invocation, also ask in plain words and check Claude picks it up. No restart needed: Claude Code notices new and edited skills mid-session.

  5. Measure it. Run a few real prompts with the skill on and off, in fresh sessions, and compare. The skill-creator plugin automates this, including tuning the description against prompts that should and shouldn't trigger it: /plugin install skill-creator@claude-plugins-official.

If you're turning a style or format into a skill, start from two or three examples you like. Drop them in the folder and have Claude write the rules it sees.

Where are Claude Code skills stored?

Where you save a skill decides where it works. A skill in your home folder works in every project on that machine. One in the repo works for everyone who clones it.

LevelPathWorks in
Personal~/.claude/skills/<name>/SKILL.mdAll your projects on this machine
Project.claude/skills/<name>/SKILL.mdThis repo. Commit it and your team gets it
Nested<folder>/.claude/skills/<name>/SKILL.mdSessions working in that folder (useful in monorepos)
Plugin<plugin>/skills/<name>/SKILL.mdWherever the plugin is on, as /plugin-name:skill-name
EnterpriseYour organization's managed settings folderEveryone in the organization
claude.ai accountSkills you turn on in claude.ai settingsTerminal sessions signed in with that account, plus Cowork and cloud sessions

If two skills share a name, enterprise beats personal and personal beats project.

Synced skills. Sign in to Claude Code with your claude.ai account (version 2.1.273 or later) and it downloads your account's skills into ~/.claude/skills/synced/. It checks for changes about every 10 minutes while you work. Sync only goes one way, so editing the downloaded copy changes nothing on claude.ai. Run /skills to see everything installed. Synced ones appear under "claude.ai sync".

One catch: Cowork and cloud sessions don't read ~/.claude/skills/ on your machine. If a scheduled cloud task says a skill wasn't found, turn the skill on in your claude.ai account or commit it to the repo.

If what you actually want is a job that runs on a schedule while your laptop is closed, that's the part Bento is built for: every workspace has its own always-on computer, and its agents research, browse and run on a schedule.

Edits under ~/.claude/skills/ and .claude/skills/ load live. If you create a skills folder that didn't exist when the session started, run /reload-skills.

Where do I find ready-made skills?

Start with what ships with Claude Code and what Anthropic publishes, then look wider. Read a skill's allowed-tools line before installing it: that's what it can run without asking you.

SourceWhat's thereHow to get it
Bundled with Claude Code/doctor, /code-review, /debug, /batch, /loop and moreAlready installed. Type / to see them
Anthropic's skills repositoryDocument skills (PDF, Word, Excel, PowerPoint) and examples/plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills
Official plugin marketplacePlugins that bundle skills, such as skill-creator/plugin install <name>@claude-plugins-official
Community directories and GitHubFar more skills, of very uneven qualityCopy the folder into ~/.claude/skills/, after reading it

How to judge the community ones is a guide of its own: where to find and vet Claude Code skills.

Can a skill connect Claude Code to other AI models?

Yes. A skill can teach Claude Code to use any command-line tool, and that tool can reach models Claude Code doesn't have. Bento publishes one for this.

Install the Bento command-line tool, then run bento local skill install --agent claude-code. Claude Code can then use your Bento workspace files and the text, image and video models in your plan, under one login.

Ask for a product photo or a short clip mid-session, and the skill tells Claude how to get it. It updates when you upgrade the tool.

It's worth it if you pay for a separate image tool, video tool and chat subscription next to Claude Code. Plans start at $20 a month, with your whole team included, and every new account gets $5 of free credits (see plans).

You don't need Bento for anything else on this page. Every skill here works in Claude Code on its own.

Make anything. One subscription. Every new account starts with $5 of free credits.

How do I share skills with my team?

Commit them to the repo, package them as a plugin, or push them through managed settings. Pick by how far they need to travel.

MethodBest forHow updates reach people
Commit .claude/skills/ to the repoSkills about one codebaseNormal pull requests, so changes get reviewed like code
A plugin in a marketplaceSkills used across many reposA version bump. Teammates update the plugin
Managed settingsRules every machine in the company must haveIT deploys them, and they win over a personal or project skill with the same name

The hard part isn't the mechanism. It's ownership: who reviews changes, who retires dead skills. If the teammates who need the output don't use a terminal at all, a shared Bento workspace is the simpler route: your whole team joins at no extra cost per person, and you can invite anyone to what the agents make. That's covered in how to run a shared skill library.

Why isn't my Claude Code skill working?

Usually it's the description. Claude can't match a vague or missing one. Run /skills first to check the skill is even installed, then work down this table.

What you seeLikely causeFix
Never triggers on its ownThe description doesn't use the words you type, or the header didn't parseAdd the phrases you actually say. Start Claude Code with claude --debug to see header errors
/name isn't recognised eitherThe name has a hidden or forbidden character (a zero-width space, <, a double space)Rename the folder. --debug lists refused names
Works by /name but never by itselfBroken header. The skill loads with no description at allCheck --- is line 1, then run claude plugin validate ~/.claude/skills
Triggers when you don't want itThe description is too broadNarrow it, or add disable-model-invocation: true
Followed it, then driftedThe conversation was compacted and only the start of the skill was keptInvoke it again. Put the must-follow rules at the top
Some skills ignored once you have manyThe description budget overflowedRun /skill-doctor to see each skill's cost and use, and turn some off
Personal skills vanishedAn older version moved themLook in ~/.claude/skills/.trash/ and move them back within 30 days

If a skill uses paths, it only activates for files inside Claude's current working folder.

Frequently Asked Questions

How does Claude know which skill to use?

It compares your request with every installed skill's description, which is always in its context. When one matches, it loads that skill's full instructions. A clear, specific description is what makes a skill trigger.

Is a Claude skill just a prompt?

Partly. The body is instructions, like a saved prompt. But a skill loads only when needed, can bundle scripts, can pre-approve or remove tools, and is versioned like code.

Are skills and slash commands the same thing now?

Yes. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files still work, but skills add a folder for supporting files and more header options, so use skills for new work.

How many skills can I install?

There's no fixed number. All descriptions share a budget of 1% of the context window, and past that the least-used ones lose their descriptions and stop triggering. Run /skill-doctor to see what each one costs.

Do Claude Code skills work in other tools?

Mostly. Skills follow the Agent Skills standard, which lists 46 products that support it as of November 2026, including Codex, Cursor, Gemini CLI, GitHub Copilot and VS Code. Claude Code-only extras such as ! command lines and context: fork won't work elsewhere.

Can a skill run code?

Yes. A skill can bundle scripts in any language the machine has and tell Claude when to run them. Only the script's output enters the conversation, not its code.

Make anything. One subscription.

Posts, reels, ads, apps and games, made with the best AI.

Free credits to try it all. Nothing to set up.

Related guides