What you will be able to do
- Explain what a Skill adds that a tool or MCP server does not, and what it costs in context
- Split a use case between a Skill and an MCP server when it needs both knowledge and access
- Reject a Skill when the requirement calls for a hook, CLAUDE.md or a plugin
- Write a SKILL.md in the current format rather than a legacy command file
1.What a Skill adds that a tool does not
Tools and MCP servers give an agent new actions. A Skill gives it know-how: workflows, context and best practices, packaged as a directory the agent can read. A prompt has to be pasted into every conversation that needs it. A Skill loads on demand instead. It can hold three kinds of content: instructions for flexible guidance, code for reliable repeatable steps, and resources to look facts up in.
Skills are cheap to install because of progressive disclosure: Claude loads a Skill in stages, not all at once.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | None until accessed | Bundled files; scripts run through bash and only their output enters context |
Only the metadata is loaded all the time, so installing many Skills barely touches context. The catch is that the description does all the selection work. Claude matches each request against it, so it has to say both what the Skill does and when to use it. A Skill with a vague description may never trigger.
Sources1
2.Skill or MCP server? Often both
The features guide draws the line between the two clearly:
| Aspect | MCP | Skill |
|---|---|---|
| What it is | Protocol for connecting to external services | Knowledge, workflows, and reference material |
| Provides | Tools and data access | Knowledge, workflows, reference material |
| Examples | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |
A Skill can include scripts, which blurs its line with tools. When Claude runs a bundled script, only the output enters context, never the code. Anthropic's engineering write-up explains why this suits mechanical work: sorting a list by generating tokens costs far more than running a sort, and code gives the same result every time. So a Skill with a script is a good home for a repeatable, deterministic step inside a larger procedure.
What a Skill can't always do is reach the outside world. On the Claude API, Skills need the code execution tool and run in a sandboxed container with no network access and no way to install packages at runtime. Live data from your ticketing system or database still needs a tool or an MCP server. The Skill supplies the procedure for using it.
Database access is an MCP job: it provides tools and data access, and database queries are one of the guide's examples. The checklist is a Skill job: a code review checklist is one of the guide's Skill examples. Neither replaces the other. They work together.
An engineering team already has a working internal Slack bot with OAuth handled by Anthropic's published Slack MCP server. They now want Claude Code to post release notes to a channel. What should they do instead of writing a custom tool from scratch?
Correct answer: A — Connect the existing Slack MCP server so Claude reuses its messaging tools and authentication
- A. Correct: when a maintained MCP server already exists for a service, connecting to it reuses its authentication and tool definitions instead of duplicating that work in a custom tool.
- B. Reimplementing the OAuth flow and API client duplicates work the existing MCP server already solved, adding maintenance burden without adding capability.
- C. A Skill can describe how to use a tool, but it cannot itself authenticate or make network calls, so release notes would never actually reach Slack.
- D. Shelling out with curl bypasses structured tool schemas and error handling, and requires managing credentials manually inside the Bash environment.
3.When a Skill is the wrong layer
A Skill is a set of instructions Claude reads and follows. That makes it the right layer for work that needs reasoning and the wrong layer for anything that must happen every time. Hooks run a shell command, HTTP request, MCP tool call, prompt or subagent on lifecycle events such as PostToolUse, and they are guaranteed to fire. With a Skill, Claude interprets the instructions, so the outcome can vary. CLAUDE.md sits at the other extreme: it loads every session, suits "always do X" rules, and can't trigger a workflow.
| Layer | How it applies | Best for |
|---|---|---|
| CLAUDE.md | Every session, automatically | Core conventions and build commands |
| Skill | On demand, when invoked or relevant | Reference material, repeatable workflows |
| Hook | Always fires on its event | Linting after edits, blocking unsafe commands, logging |
| Plugin | Wherever the plugin is enabled | Giving a second repository the same setup |
The guide's rules of thumb all start from a symptom:
- You keep typing the same prompt to start a task: save it as a user-invocable skill. - You paste the same playbook into chat for the third time: capture it as a skill. - You want something to happen every time without asking: write a hook. - A second repository needs the same setup: package it as a plugin.
Plugins package and distribute all the other features, and plugin skills are namespaced so their names don't clash.
Sources2
4.Slash commands, SKILL.md and where Skills live
A Skill can be triggered in two ways: you type /<name>, or Claude matches its description to your task. So the old split between Skills Claude chooses to use and slash commands you type is now just two ways of triggering the same file. Custom commands used to be Markdown files in .claude/commands/. That older format still works, but new work should be a skill, because skills can also carry supporting files.
---
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.
---
## Current changes
!`git diff HEAD`
## Instructions
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 description covers both things discovery needs, what the skill does and when to use it. The docs test this skill with a plain question, "What did I change?", and with /summarize-changes. Where you put the directory decides who gets the skill:
| Location | Path | Loads in |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md | Sessions in this repository; commit it so your team gets it |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | Managed settings directory | All users on machines where your organization deploys it |
When two skills share a name, one wins by priority instead of the two being merged. For skills the order is managed, then user, then project.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Installing many Skills fills the context window, so keep the set small.Why is that wrong?
Until a Skill triggers, only its name and description are loaded. The body and bundled files load only when needed.
Covered in What a Skill adds that a tool does not
2.On the Claude API, a Skill's bundled script can fetch live data from your service, so you don't need a tool or MCP server.Why is that wrong?
Skills on the API run in a sandbox with no network access, so live external data still needs a tool or MCP connection.
Covered in Skill or MCP server? Often both
3.Putting "always run the linter after edits" in a Skill guarantees it happens.Why is that wrong?
Claude interprets a Skill's instructions, so results can vary. A hook is guaranteed to fire on its event.
Covered in When a Skill is the wrong layer
4.New custom slash commands belong in .claude/commands/.Why is that wrong?
That is the older format. It still works, but new work should be a skill, which can also carry supporting files.
Practise it for real
Create a personal Skill and trigger it both by description matching and by slash command
1.Run: mkdir -p ~/.claude/skills/summarize-changes
Why: The personal location loads the skill in all your projects on this machine
You should see: An empty summarize-changes directory under ~/.claude/skills/
2.Save the SKILL.md shown in this lesson into that directory
Why: The frontmatter description is what Claude matches requests against, so it says both what the skill does and when to use it
You should see: ~/.claude/skills/summarize-changes/SKILL.md exists
3.In a repository with uncommitted changes, start Claude Code and ask: What did I change?
Why: This tests triggering by description, with no command typed
You should see: Claude summarizes the changes in two or three bullets and lists any risks
4.Type /summarize-changes
Why: This tests triggering the same skill by typing its name
You should see: The same kind of summary, produced on demand
Stuck? Get a nudge
If the plain question doesn't trigger the skill, make the "Use when..." clause in the description more specific. Claude has nothing else to match against.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Skills load on demand, so you don't have to repeat the same guidance across conversations.”
↩︎ What a Skill adds that a tool does not“instructions for flexible guidance, code for reliability, resources for factual lookup.”
↩︎ What a Skill adds that a tool does not“The description is what Claude matches your request against when determining whether to trigger the Skill”
↩︎ What a Skill adds that a tool does not“When Claude runs validate_form.py, the script's code never loads into the context window.”
↩︎ Skill or MCP server? Often both“Using Skills through the API requires the code execution tool, whose container Skills run in.”
↩︎ Skill or MCP server? Often both“until a Skill is triggered, only its name and description occupy context.”
↩︎ Exam trap 1“Skills on the API run in a sandboxed container with no network access and no runtime package installation.”
↩︎ Exam trap 2 - 2.https://code.claude.com/docs/en/features-overviewOfficial docs
“Knowledge, workflows, and reference material”
↩︎ Skill or MCP server? Often both“Always fires on its event; the trigger is guaranteed”
↩︎ When a Skill is the wrong layer“Plugins and marketplaces package and distribute these features”
↩︎ When a Skill is the wrong layer“Plugin skills are namespaced to avoid conflicts.”
↩︎ When a Skill is the wrong layer“You typing /<name>, or Claude matching the description to your task”
↩︎ Slash commands, SKILL.md and where Skills live“managed > user > project for skills”
↩︎ Slash commands, SKILL.md and where Skills live“Claude interprets the instructions; outcome can vary”
↩︎ Exam trap 3 - 3.https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skillsSecondary source
“sorting a list via token generation is far more expensive than simply running a sorting algorithm.”
↩︎ Skill or MCP server? Often both - 4.https://code.claude.com/docs/en/skillsOfficial docs
“a Markdown file in .claude/commands/ is the older format and still works.”
↩︎ Slash commands, SKILL.md and where Skills live“Prefer a skill for new work, since skills also support supporting files.”
↩︎ Exam trap 4