Claude Code plugins and skills, explained

Teams adopting Claude Code hit the same wall about a week in. They have written some instructions that work, they want everyone to have them, and the documentation offers skills, plugins, commands, subagents, hooks, MCP servers and a CLAUDE.md. All of them sound like the answer.

They do different jobs. Here is the map.

A skill is a procedure

A skill is a folder with a SKILL.md file in it. The file has YAML frontmatter and a markdown body: the frontmatter tells Claude when to use the skill, the body tells it what to do.

---
description: Summarizes uncommitted changes and flags anything risky. Use when
  the user asks what changed, wants a commit message, or asks to review a diff.
---

## Instructions

Summarize the changes in two or three bullet points, then call out anything
that touches auth, migrations or billing.

Drop that in .claude/skills/summarize-changes/ and it is live in that project. Put it in ~/.claude/skills/ instead and you have it everywhere.

Skills can carry supporting files and scripts, and can run a command at activation time and put the output in front of Claude before it starts — useful when the skill needs real state rather than a description of it.

The description field is the whole game

Most skills that "do not work" are skills Claude never loaded.

Claude decides whether to pull a skill in by reading its description. That field is not documentation. It is the trigger, and it is competing with every other skill's description for the model's attention.

So write it as a when, not a what:

• No: Code analysis tool
• Yes: Reviews code for best practices and likely bugs. Use when reviewing code, checking a PR, or analyzing code quality.

The second names the situations that should fire it. The first names a category and leaves the model guessing.

If you want a skill to run only when you ask for it, set disable-model-invocation: true and call it with /skill-name. That is the right setting for anything destructive, and the wrong one for anything you want Claude to remember on your behalf.

A plugin is a delivery mechanism

A plugin is a directory that packages extensions together so they can be versioned, shared and installed as a unit. It can contain skills — and also agents, hooks, MCP servers, LSP servers, background monitors and settings.

The manifest is small:

{
  "name": "my-plugin",
  "description": "What the plugin does",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

That goes in .claude-plugin/plugin.json. One thing catches almost everyone: only the manifest belongs inside .claude-plugin/. The skills/, agents/ and hooks/ directories live at the plugin root, not inside it.

So the relationship is not that a skill is a small plugin. A plugin is the box. Skills are one of the things you can put in it.

The pairing that makes plugins worth it

A skill is instructions. It can tell Claude how to do something, but it cannot give Claude a tool it does not have. If the procedure touches a system outside your repository — your issue tracker, a database, a deploy pipeline — the tools come from an MCP server.

Which means a skill for that kind of work is only half the thing. Ship it alone and the person who installs it gets instructions for tools they do not have, and a skill that half-works in a way nobody enjoys debugging.

A plugin carries both. The .mcp.json that configures the server sits in the same directory as the SKILL.md that knows how to use it, and one install sets up the capability and the instructions together. That is the case for packaging something rather than pasting it into a directory — not versioning, which is nice, but the fact that a procedure and the tools it depends on stop being two separate things somebody has to get right.

The guidance in the docs matches what we would tell you anyway: start with a loose skill in .claude/, and convert it to a plugin when you are ready to hand it to someone else.

Marketplaces are just git repos

A marketplace is a catalog: a repository with a .claude-plugin/marketplace.json listing the plugins it offers. Nothing more exotic than that.

Anthropic curates two. claude-plugins-official is registered for you on first launch and browsable at claude.com/plugins. claude-plugins-community carries third-party submissions that have passed review.

You add any other one yourself:

/plugin marketplace add owner/repo

It takes a GitHub shorthand, any git URL, a local path, or a URL serving a marketplace.json. Which means a team's internal marketplace is a private repo and one command — and that is the part most teams miss. You do not need to publish anything to get the benefit of packaging.

The /plugin command opens a browser for all of it: discover, install, manage marketplaces, and a stats tab showing what each skill is costing you in context.

When it is not a skill

Skills are the default answer often enough that people reach for them when something else fits better.

Two distinctions are worth holding onto.

Hooks are not skills. A skill is an instruction the model chooses to follow. A hook is a shell command that runs on an event whether the model likes it or not. If the requirement is "this must happen every time" — format on save, block a commit, send a notification — that is a hook, and writing it as a skill will fail in exactly the cases you care about.

Subagents are not skills either. A subagent starts with a fresh context and does not see your conversation. That is the point: it is for work that produces a lot of output you will never read again. A skill runs in your conversation, which is what you want when the work is iterative.

What this means for lock-in

SKILL.md is an open standard, and other tools read it — Cursor reads .claude/skills/ directly. Plugins are Claude Code's own packaging, so they are the part that does not travel.

That splits your investment cleanly. The instructions are portable. The distribution is not. Which is a good trade, because the instructions are the part that took the work, and it makes the choice of tool more reversible than it feels — a point we make at more length in Cursor vs Claude Code.

Sources

Checked September 2026.

• Plugins — structure, manifest, what a plugin can contain
• Plugin marketplaces — catalogs, adding a marketplace
• Discover plugins — the official and community marketplaces, /plugin
• Skills — SKILL.md structure, the description field, skills vs plugins
• Hooks — event-triggered automation
• Subagents — isolated context and tool restrictions
• MCP — connecting external tools