Claude Skills vs Plugins
Claude skills vs plugins
Both arrive as folders you install into Claude Code and show up as slash commands in one listing, so the query reads like a choice.
It is a layering. A skill is content: a SKILL.md file of instructions. A plugin is packaging: a directory carrying skills, subagents, hooks, and MCP servers. A plugin can contain skills. A skill cannot contain a plugin.
- Publisher
- Skills Board
- Published
- Last checked
The short answer
A skill is a unit of content: one SKILL.md file of instructions the agent loads when your request matches its description. A plugin is a unit of distribution: a Claude Code package bundling skills, agents, hooks, and MCP servers, installed from a marketplace and versioned as one. Skills are what you write. Plugins are how you ship them.
No first-party page frames this as skill or plugin. The plugins guide compares standalone .claude/ configuration against plugins: standalone for personal workflows and quick experiments, plugins for sharing, versioned releases, and reuse.
One file demonstrates it. A folder holding only SKILL.md loads as a plain skill. Add .claude-plugin/plugin.json and the same folder loads as a plugin that can also bundle agents, hooks, and MCP servers.
01 / Comparison
Side by side
Five dimensions, from the Agent Skills specification and the Claude Code documentation.
| Dimension | Claude skill | Claude Code plugin |
|---|---|---|
| What it is | A directory whose entrypoint is SKILL.md: frontmatter, Markdown instructions, optional scripts and references. Alone it registers no hook, subagent, or MCP server. | A directory holding skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, monitors/, bin/, settings.json, and an optional .claude-plugin/plugin.json manifest. |
| Where it lives | ~/.claude/skills/<name>/SKILL.md for you, .claude/skills/<name>/SKILL.md for the project, a plugin's skills/ directory, or managed settings. | Its own directory: loaded with --plugin-dir, discovered in place under a skills directory, or installed from a marketplace. |
| What you type | /skill-name, from the directory name. Enterprise overrides personal, personal overrides project. | /plugin-name:skill-name, namespaced to prevent conflicts. The last segment can come from frontmatter name, and the bare /skill-name works when nothing else claims it. |
| Distribution and versions | Commit .claude/skills/, ship it in a plugin, or deploy through managed settings. The specification defines no version field. | A .claude-plugin/marketplace.json listing plugins by name and source. An optional version field gates updates; omit it and git sources use the commit SHA. |
| Where it works | Follows the Agent Skills open standard, documented as working across multiple AI tools. Also runs on claude.ai and the Claude API. | Documented for Claude Code, plus a desktop-app plugin browser and claude.ai organization sync. No page we checked describes plugins on the Claude API. |
The trust asymmetry comes first. A skill is text you read in a minute. Claude Code's wording for plugins and marketplaces is that they can execute arbitrary code with your user privileges, which is why the plugin manager lists what will install.
The documentation does not rank them, and no first-party table sets skills against plugins. If that changes, so does this page.
02 / Skills
When a plain skill is enough
Three cases where the manifest buys you nothing.
- 01
You are the only consumer
Personal workflows, project-specific customizations, and quick experiments are what the plugins guide lists standalone .claude/ configuration as best for. No install step to explain.
- 02
It has to leave Claude Code
Claude Code documents its skills as following the Agent Skills open standard, which works across multiple AI tools. Outside it, only the six specification fields are accepted.
- 03
One checkout already reaches everyone
Committing .claude/skills/ is one of the three sharing routes the documentation names, and on one repository it is the whole distribution problem.
When a plain skill is not enough
- The capability is not only instructions. A procedure plus the hook, subagent, and connection it depends on is more than one SKILL.md holds.
- Updates have to reach people. A committed file changes when someone pulls, and nothing records a version or says which copy a teammate runs.
03 / Plugins
When the plugin wrapper earns its keep
Three cases where the packaging is the point.
- 01
Several components ship together
One install carrying skills, subagents, hooks, and MCP servers is what the manifest exists for, and the docs describe adding plugin.json to a skill folder for exactly that.
- 02
Other people install it on purpose
A .claude-plugin/marketplace.json in a repository, added with /plugin marketplace add and installed with /plugin install name@marketplace at user, project, or local scope.
- 03
Name collisions are a real risk
Every plugin skill gets a namespaced command, and the namespaced form loads alongside a same-named project skill rather than overriding it.
When the plugin wrapper is overhead
- You are still rewriting it. The guide's sequencing is start standalone in .claude/ for quick iteration, then convert when you are ready to share.
- The audience is another product. If the procedure runs through the Claude API, the plugin wrapper does not travel; the SKILL.md does.
04 / Together
A skill inside a plugin
The combination runs one way: a plugin packages skills, never the reverse. It changes the skill's name, not its content.
| Layer | File | Decides |
|---|---|---|
| Skill | skills/<name>/SKILL.md | What the agent does, and what triggers it |
| Plugin | .claude-plugin/plugin.json | What ships together, under what namespace, at what version |
The namespace is the visible change. A skills/hello/SKILL.md folder in a plugin named my-first-plugin is invoked as /my-first-plugin:hello, with the prefix from the manifest name field. A single-skill plugin can put SKILL.md at its root.
The manifest is optional, which most summaries get wrong: without it Claude Code auto-discovers components in default locations and derives the name from the directory.
A plugin whose only component is one skill
release-tools/
.claude-plugin/
plugin.json
skills/
release-notes/
SKILL.md
# .claude-plugin/plugin.json
{
"name": "release-tools",
"description": "How this team cuts a release",
"version": "1.0.0"
}
# skills/release-notes/SKILL.md
---
name: release-notes
description: How this team writes release notes. Use when cutting a release or when someone asks for the changelog entry.
---
Group the merged pull requests by user-visible change rather than by author,
and leave anything internal out of the published note.
# Invoked as /release-tools:release-notes
Once more than one person depends on it, the format stops being the hard part: how to share AI agent skills with your team covers ownership, the distribution models, and keeping one recommendation instead of five forks.
05 / Questions
Frequently asked questions
- What is the difference between Claude skills and plugins?
- A skill is content: one SKILL.md file of instructions Claude loads when your request matches its description. A plugin is a Claude Code package that can bundle skills, subagents, hooks, MCP servers, and LSP servers, installed from a marketplace and versioned as one unit. A plugin can contain skills.
- Can a Claude Code plugin contain skills?
- Yes. They live in a skills/ directory at the plugin root, each as a folder with its own SKILL.md. Every plugin skill gets a namespaced command, plugin-name:skill-name, which the docs say prevents conflicts between plugins, so hello inside a plugin named my-first-plugin is invoked as /my-first-plugin:hello.
- Do I need a plugin to share a skill with my team?
- No. The skills documentation names three sharing routes: commit .claude/skills/ to version control, ship the skill in a plugin, or deploy it through managed settings. A plugin adds versioned releases, marketplace installation, and the ability to bundle hooks, agents, and MCP servers alongside the skill.
- Do Claude Code plugins work in claude.ai or the Claude API?
- The plugin documentation is written for Claude Code. It also references a plugin browser in the Claude desktop app and marketplace sync through claude.ai organization settings. No first-party page we checked describes plugins on the Claude API. Skills do run there.
- Should I start with a skill or a plugin?
- The Claude Code guide answers this directly: start with standalone configuration in .claude/ for quick iteration, then convert to a plugin when you are ready to share. Adding a .claude-plugin/plugin.json to an existing skill folder is the documented conversion, and it needs no marketplace and no install step.
Sources
Editorial method: every claim about how skills and plugins behave comes from the first-party documentation below, checked on the date at the top of this page. Where the documentation says nothing, this page says so instead of filling the gap. Product behavior changes, so check the linked pages before you rely on a detail.
- Claude Code: create plugins
The standalone-versus-plugins table and its best-for column, the advice to start standalone and convert when ready to share, the plugin structure table covering skills, commands, agents, hooks, .mcp.json, .lsp.json, monitors, bin, and settings.json, the namespacing note and its stated reason, the single-skill plugin root layout, and the migration steps from .claude/ to a plugin.
- Claude Code: discover and install plugins
The two-step marketplace model, the official and community marketplaces, the user, project, and local install scopes, the details pane showing context cost and a will-install component list, the /plugin install syntax, and the warning that plugins and marketplaces can execute arbitrary code with your user privileges.
- Claude Code: create and distribute a plugin marketplace
The .claude-plugin/marketplace.json file at a repository root, its name, owner, and plugins fields, the plugin entry requiring a name and a source, the seven source types, and the version field behaviour including the fallback to a resolved commit SHA for git-based sources.
- Claude Code: plugins reference
The optional manifest with name as its only required field, component auto-discovery and name derivation when the manifest is absent, the skills-directory table showing that adding .claude-plugin/plugin.json turns a skill folder into a plugin that can bundle skills, agents, hooks, and more, and the standard plugin directory layout.
- Claude Code: extend Claude with skills
The SKILL.md frontmatter plus Markdown structure, the four locations skills load from and the precedence between them, the plugin-name:skill-name namespace and the fact that it loads alongside rather than overriding, the three sharing routes, and the statement that Claude Code skills follow the Agent Skills open standard with only six fields accepted elsewhere.
- Agent Skills specification
The skill directory structure, the required name and description fields and the four optional ones, the absence of any version field, the optional scripts, references, and assets directories, and progressive disclosure with metadata loaded at startup and the body loaded on activation.
- Anthropic: Agent Skills overview
The surfaces custom Skills run on, the statement that custom Skills do not sync across surfaces, the per-surface sharing model naming Claude Code Plugins as one route, and the runtime constraints for each surface.
Keep reading
View all resourcesPackaging is easy. Deciding what deserves packaging is not.
Skills Board is a shared library for the skills a team recommends, loose or inside a plugin. Free forever, MIT licensed, and open source.