
MCP vs Skills: Tools, CLAUDE.md, and MCP Explained
Skills vs MCP, with a worked example

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
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?
02Do I need a skill, or something else?
03What goes in a SKILL.md file?
04How do I create a Claude Code skill?
05Where are Claude Code skills stored?
06Where do I find ready-made skills?
07Can a skill connect Claude Code to other AI models?
08How do I share skills with my team?
09Why isn't my Claude Code skill working?
10FAQ
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:
| What | When it's in Claude's context | Rough cost (Anthropic's estimate) |
|---|---|---|
| Name and description | Every session, from the start | About 100 tokens per skill |
| The SKILL.md body | When the task matches, or you type /skill-name. It then stays for the rest of the conversation | Usually under 5,000 tokens |
| Scripts and reference files | Only when the body tells Claude to open or run them | Only 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.

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… | Use | Why |
|---|---|---|
| Always know a fact ("we use pnpm", "tests live in /spec") | CLAUDE.md | It loads every session. See how CLAUDE.md memory works |
| Follow a procedure when it's relevant (review a PR, write release notes) | A skill | Only the description loads until it's needed |
Run a fixed action when you say so (/deploy) | A skill with disable-model-invocation: true | Old .claude/commands/ files still work, but they're now the same thing |
| Reach a live system (GitHub, a database, Slack) | An MCP server | A skill can't log in to anything by itself. Set up an MCP server |
| Do a big piece of work in its own clean context | A subagent | It 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.
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:
| Field | What it does |
|---|---|
name | The command you type. Defaults to the folder name |
description | What the skill does and when to use it. Put the trigger first |
when_to_use | Extra trigger phrases. Shares the 1,536-character cap with description |
disable-model-invocation | true means only you can run it. Use it for anything with side effects |
user-invocable | false hides it from the / menu, so only Claude uses it |
allowed-tools | Tools Claude may use without asking, for the turn the skill runs. It doesn't restrict anything |
disallowed-tools | Tools removed while the skill is active. This is the one that restricts |
paths | File 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.
Make a folder, write the description, write the steps, then test it both ways. Most of the work is the description.
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.
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."
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.
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.
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 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.
| Level | Path | Works in |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<name>/SKILL.md | This repo. Commit it and your team gets it |
| Nested | <folder>/.claude/skills/<name>/SKILL.md | Sessions working in that folder (useful in monorepos) |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is on, as /plugin-name:skill-name |
| Enterprise | Your organization's managed settings folder | Everyone in the organization |
| claude.ai account | Skills you turn on in claude.ai settings | Terminal 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.
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.
| Source | What's there | How to get it |
|---|---|---|
| Bundled with Claude Code | /doctor, /code-review, /debug, /batch, /loop and more | Already installed. Type / to see them |
| Anthropic's skills repository | Document skills (PDF, Word, Excel, PowerPoint) and examples | /plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills |
| Official plugin marketplace | Plugins that bundle skills, such as skill-creator | /plugin install <name>@claude-plugins-official |
| Community directories and GitHub | Far more skills, of very uneven quality | Copy 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.
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.
Commit them to the repo, package them as a plugin, or push them through managed settings. Pick by how far they need to travel.
| Method | Best for | How updates reach people |
|---|---|---|
Commit .claude/skills/ to the repo | Skills about one codebase | Normal pull requests, so changes get reviewed like code |
| A plugin in a marketplace | Skills used across many repos | A version bump. Teammates update the plugin |
| Managed settings | Rules every machine in the company must have | IT 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.
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 see | Likely cause | Fix |
|---|---|---|
| Never triggers on its own | The description doesn't use the words you type, or the header didn't parse | Add the phrases you actually say. Start Claude Code with claude --debug to see header errors |
/name isn't recognised either | The 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 itself | Broken header. The skill loads with no description at all | Check --- is line 1, then run claude plugin validate ~/.claude/skills |
| Triggers when you don't want it | The description is too broad | Narrow it, or add disable-model-invocation: true |
| Followed it, then drifted | The conversation was compacted and only the start of the skill was kept | Invoke it again. Put the must-follow rules at the top |
| Some skills ignored once you have many | The description budget overflowed | Run /skill-doctor to see each skill's cost and use, and turn some off |
| Personal skills vanished | An older version moved them | Look 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.
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.
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.
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.
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.
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.
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.
Posts, reels, ads, apps and games, made with the best AI.
Free credits to try it all. Nothing to set up.

Skills vs MCP, with a worked example

How to run a shared skill library

Where to find and vet Claude Code skills

Speed up client emails and renewal follow-ups with an AI drafting system that keeps communication consistent.

Reduce carrier portal rekeying with AI that extracts ACORD data and powers automated carrier submissions across portals.

The 10 best AI coding agent platforms compared — Cursor, Devin, Claude Code, Bento, v0, and more. Ranked by fit for solo devs, teams, and enterprises.