What is the difference between skills and plugins?
A skill is one capability; a plugin is a package of capabilities. A skill is a folder with a SKILL.md file that teaches Claude how to do a task. A plugin is a directory that can bundle several skills together with subagents, hooks and MCP servers, so Claude Code installs and updates them as one unit.
So the real choice isn't skill or plugin. Every plugin skill is a skill. The question is whether your skills need packaging. Anthropic's plugins overview defines a plugin as "a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit."
What is a skill?
A skill is a folder with a SKILL.md file inside. The file starts with YAML frontmatter, usually a name and a description, followed by Markdown instructions. It can sit next to scripts, templates and reference files that Claude reads only when the instructions point to them.
According to the Claude Code skills docs, you can run a skill directly by typing /skill-name, or Claude loads it on its own when your request matches the description. Only descriptions stay in context; the full skill loads when it's invoked.
Where a standalone skill lives decides who gets it:
- Personal:
~/.claude/skills/<skill-name>/SKILL.md, for all your projects on that machine. - Project:
.claude/skills/<skill-name>/SKILL.md, for one repository. Commit it and your team has it too. - Enterprise: deployed by your organization through managed settings.
Skills follow the open Agent Skills standard, which the docs say "works across multiple AI tools." Claude Code also merged the older custom commands into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.
What is a plugin?
A plugin is a directory with a manifest and one folder or file per component type. The manifest lives at .claude-plugin/plugin.json and gives the plugin its name, which becomes the prefix on every skill and agent inside it. The create a plugin guide lists the usual layout:
| Location | Contents |
|---|---|
.claude-plugin/plugin.json |
The manifest: name, description, version, author |
skills/ |
One <name>/SKILL.md folder per skill |
agents/ |
One Markdown file per subagent |
hooks/hooks.json |
Hook configuration |
.mcp.json |
MCP server definitions |
commands/ |
The older single-file form of skills |
Most plugins come from a marketplace, which is a repo or folder with a .claude-plugin/marketplace.json file listing plugins and where to fetch each one. Claude Code adds Anthropic's official marketplace, claude-plugins-official, the first time you start an interactive terminal session. For the full install and authoring walkthrough, see the Claude Code plugins guide.
Skills vs plugins side by side
| Standalone skill | Plugin | |
|---|---|---|
| What it is | One folder with SKILL.md |
A directory of components plus a manifest |
| What it can hold | Instructions, scripts, reference files | Skills, subagents, hooks, MCP servers and more |
| Where it lives | ~/.claude/skills/ or .claude/skills/ |
Anywhere; installed copies go under ~/.claude/plugins/ |
| Command name | /skill-name |
/plugin-name:skill-name |
| How you get it | Copy a folder | Install from a marketplace, or load with --plugin-dir |
| Install scopes | Personal or project folder | User, project or local scope |
| Updates | You edit or re-copy the files | Through the marketplace; auto-update is on by default for Anthropic's official marketplace |
| Versioning | Whatever your Git history gives you | Optional version field in plugin.json |
| Name clashes | Enterprise beats personal, personal beats project | Never clashes, thanks to the prefix |
| Portability | Agent Skills standard, read by other agents too | Plugin format is specific to Claude's products |
| Best for | Your own workflows and one repo's conventions | Sharing a full setup across projects and teams |
When is a standalone skill enough?
Most of the time, start with a plain skill. It's one folder, you can read every line of it, and nothing else runs.
- It's just for you. A personal skill in
~/.claude/skills/already works in every project on your machine. - It's for one repo. A project skill committed to
.claude/skills/reaches everyone who clones the repo, through ordinary code review. No marketplace needed. - It's only instructions. If there are no hooks or MCP servers to ship alongside it, a plugin adds a manifest and a longer command name and little else.
- You want it to work in other agents. A plain skill folder follows the Agent Skills standard. Wrapping it in a Claude Code plugin doesn't make it more portable.
Anthropic's own guidance says the same: keep a standalone setup "while it serves one project or only you."
When should you use a plugin?
Reach for a plugin when packaging solves a real problem.
- Several pieces belong together. A review workflow might need a skill, a reviewer subagent and a hook that runs a linter after every edit. A plugin installs all three in one step.
- Many projects or teams need the same setup. The docs suggest making a plugin "when you want to share the setup with teammates, install it in several projects, or publish versioned releases."
- You want managed updates. Users install once from your marketplace and receive your updates, instead of re-copying folders.
- You want someone else's setup. Installing a plugin from a marketplace is the quickest way to get a tested bundle someone else maintains.
Know what you're signing up for. The overview warns that an enabled plugin "is part of every session, not only the sessions where you use it." Its MCP servers run alongside each session, its hooks fire at their events, and "what the plugin runs, it runs as you." Read the details pane in /plugin before installing, and see Claude Code hooks for what hooks can do.
What changes when a skill moves into a plugin?
Two things change: where the file sits and what you type to run it.
The skill moves under the plugin root, so .claude/skills/deploy/SKILL.md becomes my-plugin/skills/deploy/SKILL.md. Its command gains the plugin prefix, so /deploy becomes /my-plugin:deploy. Subagents get the same treatment: an agent called reviewer becomes my-plugin:reviewer.
The skill file itself doesn't change. Frontmatter, instructions and supporting files all work as before.
How do you turn skills into a plugin?
The create a plugin guide has a short conversion path. Run these from the project root, the folder that holds .claude/:
mkdir -p my-plugin/.claude-plugin
cp -r .claude/skills my-plugin/
cp -r .claude/agents my-plugin/ # skip if you have none
claude plugin validate ./my-plugin
claude --plugin-dir ./my-plugin
The manifest at my-plugin/.claude-plugin/plugin.json can be this small:
{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}
If you have hooks in .claude/settings.json, copy the hooks object into my-plugin/hooks/hooks.json. While the originals are still in .claude/, both sets load: /deploy and /my-plugin:deploy both work, and hooks run twice because they have no prefix. Delete the originals once the plugin checks out. To share it, give people the folder or a .zip, or list it in a marketplace.
Which should you pick?
- One person, a few workflows: personal skills in
~/.claude/skills/. - One team, one repo: project skills committed to
.claude/skills/. - The same skills in many repos, or skills plus hooks and MCP servers: a plugin.
- A setup you want versioned and updated for others: a plugin in your own marketplace.
- Skills you also use in Codex, Cursor or other agents: keep the plain skill folder as the source, and package a plugin around it only if your Claude Code users need one.
A good rule: write skills first, and promote them into a plugin the day you notice you're copying the same folders into a third place.
Where Kipt fits
Kipt works on the skills side of this choice. It keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code or Codex with one command: npx skills add https://github.com/<you>/<repo>.git --all -g. If a skill later needs hooks or an MCP server shipped with it, that's the point to wrap it in a plugin. To draft a new skill from a prompt you already use, try the free SKILL.md generator.