8. Skills and plugins
"A skill is a folder with a SKILL.md: a short description that tells Claude when to use it, and instructions it follows when it does. Only the description sits in context every turn; the full text loads when you type /name or when Claude decides it fits the request. Custom slash commands have merged into skills, so existing .claude/commands files keep working. A plugin packages skills with subagents, hooks and MCP servers so a whole setup installs from a marketplace in one step, namespaced as /plugin-name:skill. /skills and /skill-doctor show what you have and what it costs, /plugin installs and manages, and the two reload commands pick up changes without a restart. One thing to say up front: a skill is guidance. A rule that must always hold belongs in a hook, which a skill or plugin can carry."
The last two sentences are the architect's answer. Most people stop at "skills are reusable prompts."
8 pictures, in order.
Use the arrow keys or the dots. Tap a picture to see it full size.
The facts someone can check.
Anatomy of a skill
A skill is a folder whose only required file is SKILL.md. The file opens with YAML frontmatter between --- lines, then markdown instructions. Other files in the folder (reference docs, examples, scripts) load only when Claude needs them, and scripts are executed rather than loaded.
| Field | What it does |
|---|---|
description |
Recommended. What it does and when to use it. Claude matches requests against it. Put the key use case first |
name |
The command you type. Defaults to the folder name |
when_to_use |
Extra trigger phrases. Together with description, capped at 1,536 characters in the listing |
disable-model-invocation: true |
Only you can run it. For anything with side effects: deploy, commit, send |
user-invocable: false |
Hidden from the / menu. Only Claude loads it, for background knowledge |
allowed-tools |
Pre-approves listed tools for the turn that invokes the skill. Restricts nothing |
model, effort |
Overrides while the skill is active. A model override lasts for the rest of that turn |
context: fork |
Runs the skill in a subagent that does not see your conversation |
paths |
Glob patterns. Claude auto-loads the skill only when working on matching files |
Every field is optional, and a misspelled field name is silently ignored. Keep SKILL.md under 500 lines and move detail into supporting files.
Where skills live, and which one wins
| Location | Path | Who gets it |
|---|---|---|
| Enterprise | .claude/skills/ in the managed settings folder |
Everyone on machines the org deploys to |
| Personal | ~/.claude/skills/<name>/SKILL.md |
You, every project on this machine (not Cowork or cloud sessions) |
| Project | .claude/skills/<name>/SKILL.md |
The team, through git |
| Nested | <subdir>/.claude/skills/ |
Loads once Claude works on files in that folder |
| Plugin | <plugin>/skills/<name>/SKILL.md |
Wherever the plugin is enabled, as /plugin-name:skill-name |
| claude.ai account | Skills enabled on your account | Cowork, cloud, and signed-in terminal sessions |
Custom commands merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and behave the same. A skill adds a folder for supporting files. On a name clash: enterprise beats personal, personal beats project, a skill beats a command file, and your skill replaces a bundled or built-in command but not its aliases. Plugin skills never clash because they are namespaced.
How a skill loads
- Every turn: a listing of names and descriptions, so Claude knows what exists. The listing gets 1% of the context window by default (
skillListingBudgetFraction). Over budget, the least-used skills lose their descriptions first; names always stay. - When invoked: the full
SKILL.mdenters the conversation as one message and stays. Claude Code does not re-read the file on later turns, so write standing instructions. - When needed: supporting files are read on demand; scripts are run, not loaded.
- After compaction: the most recent run of each skill is re-attached, keeping its first 5,000 tokens, inside a shared 25,000-token budget filled newest first. Put the important rules at the top.
| Frontmatter | You can run it | Claude can run it | In context |
|---|---|---|---|
| (default) | Yes | Yes | Description always, full text when invoked |
disable-model-invocation: true |
Yes | No | Nothing until you invoke it |
user-invocable: false |
No | Yes | Description always, full text when invoked |
To hide a skill without editing its file, use skillOverrides in settings: "on", "name-only", "user-invocable-only", or "off". The /skills menu writes these for you (Space to cycle, Esc to save). Plugin skills ignore skillOverrides; manage those in /plugin. To block skills by permission, deny Skill entirely or Skill(deploy *) for one.
Plugins
- A plugin is a folder of components that installs and loads as one unit. The manifest is
.claude-plugin/plugin.json; onlynameis required. - Components:
skills/,commands/(older format),agents/,hooks/hooks.json,.mcp.json, plus language servers, output styles, monitors and more. - A
CLAUDE.mdat the plugin root is not loaded. Plugin instructions go in a skill. - An enabled plugin is part of every session: its skill and agent descriptions sit in context each turn, its MCP servers run, its hooks fire, and it runs with your user privileges.
- Install scopes: user (
~/.claude/settings.json), project (committed.claude/settings.json; each collaborator still installs it once), local (.claude/settings.local.json). Local beats project beats user.
Marketplaces
A marketplace is a repo with .claude-plugin/marketplace.json listing plugins and where to fetch each. It is a catalog, not a hosted store.
| Official | Community | Demo | |
|---|---|---|---|
Name after @ |
claude-plugins-official |
claude-community |
claude-code-plugins |
| Repo | anthropics/claude-plugins-official |
anthropics/claude-plugins-community |
anthropics/claude-code |
| How you get it | Added automatically on first interactive session | /plugin marketplace add |
/plugin marketplace add |
Every other marketplace is third party, including your own company's, and Anthropic does not review it. Admins can use managed settings to allowlist or block marketplaces, force-install plugins, and turn off session-only loading. While developing, load a plugin for one session with claude --plugin-dir ./my-plugin.
The five commands
| Command | What it does | Worth knowing |
|---|---|---|
/skills |
Lists skills; type to filter | t sorts by token count; Space cycles visibility, saved to .claude/settings.local.json |
/skill-doctor |
Context cost and usage per skill | Flags never-used skills and idle plugins. Opens in the /plugin Stats tab. Needs v2.1.252+ |
/reload-skills |
Re-scans skill and command folders | Edits in watched folders are picked up live; this is for a new top-level skills folder |
/plugin [subcommand] |
Plugin panel, or install, enable, disable, uninstall, marketplace add |
Aliases /plugins, /marketplace. Interactive terminal only |
/reload-plugins [--force] |
Applies plugin changes without a restart | Skips and warns if MCP tools would change the prompt cache, unless --force |
Skill or subagent?
The question customers ask most once they have both. A skill changes what Claude knows in the current context. A subagent changes where the work happens: a separate context window, with only a summary coming back. They combine: a skill with context: fork hands its text to a subagent as the task, and a subagent with a skills: list preloads those skills (up to the first 32) at startup.
Answer out loud, then flip the card.
Mark each one honestly. Cards you miss stay flagged for review, in this browser.
A customer has 40 custom slash commands in .claude/commands. Do they have to migrate them to skills?
No. Custom commands merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Move one to a skill folder when it needs supporting files or the frontmatter that only skills get (name, paths). If both exist with the same name, the skill wins, so avoid keeping both.
"Claude keeps running our deploy skill when nobody asked." How do you stop that without deleting the skill?
Add disable-model-invocation: true to its frontmatter. You can still type /deploy; Claude can't start it on its own, and if it tries, Claude Code blocks the call. Its description also leaves Claude's context. Without editing the file, set it to "user-invocable-only" in skillOverrides. To forbid it outright, add a permission deny rule such as Skill(deploy *).
"We have 120 skills. Does that slow Claude down or cost money?"
Yes, a little, every turn. Each skill Claude can invoke puts its name and description in context, within a listing budget of 1% of the context window. Past that budget, the least-used skills lose their descriptions, so Claude is less likely to pick them. Run /skill-doctor to see cost and usage per skill, set rarely used ones to "name-only" or "off", and keep descriptions short with the key use case first. The body of a skill costs nothing until it runs.
The security team asks what a plugin can do on a developer's laptop, and how to control which plugins get installed.
A plugin runs with the developer's own privileges: its MCP servers run alongside each session, its hooks fire on lifecycle events, and its skills and agents shape what Claude does. Anthropic reviews nothing outside its own marketplaces. Control it with managed settings: allowlist or block marketplaces, force-install the approved plugins, and turn off session-only loading so --plugin-dir can't side-load one. Review a plugin's contents before approving it.
How would you roll out a standard set of skills and hooks to 300 developers?
Package them as a plugin and list it in a private marketplace: a git repo with a marketplace.json that developers add once. Push it through managed settings so it is installed everywhere, or enable it at project scope in a committed .claude/settings.json (each person still installs it once). Because it is a plugin, updates ship as new versions and the skills are namespaced so they never collide with personal ones. For repo-specific skills, committing .claude/skills/ is enough.
A skill sets allowed-tools: Bash(git *). Does that mean Claude can only use git while the skill runs?
No. allowed-tools pre-approves the listed tools for the turn that invokes the skill, so they run without a prompt. It does not restrict anything: every other tool stays callable under the normal permission rules. To remove tools while a skill is active, use disallowed-tools. Worth adding for a security audience: workspace trust doesn't gate this field, so review the allowed-tools of skills committed to a repo before running Claude there.
When do you write a skill and when do you write a subagent?
A skill when Claude needs knowledge or a procedure in the current conversation: a style guide, a deploy checklist, a workflow you start with /name. A subagent when the work should happen somewhere else: reading dozens of files, running noisy tests, or working in parallel, with only a summary returning. They combine: a skill with context: fork runs its instructions in a subagent, and a subagent can preload skills with a skills: list.
A developer edited a plugin's hook and nothing changed, and a skills folder they just created doesn't show up. What do you tell them?
Plugin changes such as hooks, agents and MCP servers apply on /reload-plugins, no restart needed. If the reload would change which MCP tools are loaded, it warns that the next message would reread the whole conversation and skips unless they pass --force. Skill text edits are picked up live, but a top-level skills folder that didn't exist when the session started needs /reload-skills.
Wrong answers that sound right.
Before you tap, say why each one is wrong.
Three moves in a fresh project.
Facts checked against code.claude.com/docs/en/skills, /plugins/overview, /plugins/components, /plugins/install, /plugins/anthropic-marketplaces, /plugins/cli-reference, /features-overview, /sub-agents and /commands on 2026-10-25. Claude Code ships fast: confirm anything that matters against the official docs.