Claude Code Skills vs Plugins (2026): When to Use Each

TL;DR: Skills are prompted procedures. Plugins are packaged tool kits. A skill is a markdown file that teaches Claude Code how to do a specific task, voice, steps, gotchas, output format. A plugin is a distributable package that can bundle multiple skills plus slash commands, subagents, hooks, and MCP servers. Reach for a skill when you want repeatable behavior inside one repo. Reach for a plugin when you want to ship that behavior, together with tools and integrations, to other repos, teammates, or clients.

Claude Code changed shape in 2025. The early version was a single coding agent with a few slash commands. By 2026 it is a runtime: a sandbox where the model loads context on demand, calls tools, runs subagents, and triggers hooks at well-defined lifecycle points. Two abstractions sit on top of that runtime, skills and plugins, and most teams confuse them within the first week of adoption.

The confusion is fair. Both live in the .claude/ directory. Both can include markdown. Both can be triggered automatically. But they answer different questions. A skill answers "how should the agent perform this task?" A plugin answers "how do I package and distribute a bundle of capabilities to anyone running Claude Code?" Treating them as interchangeable leads to bloated context, brittle workflows, and skills that should have been plugins (or worse, plugins that should have been a single skill).

This guide is the version we wished existed when we were building Claude Code agents for clients. It defines each primitive precisely, compares them across the dimensions that actually matter (surface area, distribution, discoverability, maintenance), and gives concrete scenarios, with code, for when to use which, and when to combine both.

Skills vs Plugins: side-by-side comparison

The rest of this guide walks through each dimension in depth and shows the patterns that hold up after a year of production use.

What a Skill is

A Claude Code skill is a markdown file with YAML frontmatter that tells the agent: when this situation comes up, follow these instructions. Skills are loaded into context on demand, either because the description matches the user's request, or because the agent (or user) explicitly invokes one with the Skill tool.

A minimal skill looks like this:

---
name: postgres-migration
description: Use when writing or reviewing PostgreSQL migrations. Enforces our naming, transaction, and rollback rules.
---

# PostgreSQL Migration Skill

## Naming

- Files: `YYYYMMDDHHMM_verb_noun.sql`
- Verbs: `create`, `add`, `drop`, `rename`, `backfill`

## Required structure

Every migration must:
1. Open with `BEGIN;` and close with `COMMIT;`
2. Include a rollback comment block at the bottom
3. Use `IF NOT EXISTS` / `IF EXISTS` guards
4. Run `EXPLAIN` on any new index before committing

## Examples

(... concrete before/after examples ...)

That is the whole thing. There is no compilation step, no manifest. The file sits in .claude/skills/ (or ~/.claude/skills/ for personal global skills) and Claude Code picks it up automatically. When a user types "add a migration to drop the legacy users_old table", the runtime sees the description match, loads the file into context, and the agent follows it.

Skills can include three optional concepts beyond the markdown body:

• scripts/, Helper scripts the skill tells the agent to run (a linter, a generator, a validator). The agent invokes them through the Bash tool; the skill explains when and why.
• references/, Larger reference docs the agent should consult only when needed, kept out of the main skill body to save tokens.
• Progressive disclosure, A skill can describe a family of related procedures and instruct the agent to read deeper files only when a specific path matches.

The mental model: a skill is a playbook page. It is everything the agent needs to know to handle one well-defined situation, written for the agent to read, structured so the agent does not have to guess.

We use skills heavily inside client repos: one for the brand voice on landing-page copy, one for our Next.js conventions, one for the testing pyramid, one for migration rules, one for review checklists. Each skill is a few hundred lines. Together they are the agent's onboarding.

What a Plugin is

A Claude Code plugin is a distributable package. Think of it as the unit of installation: what you publish so that someone else (a teammate, a client, the wider ecosystem) can run a single command and pick up an entire workflow.

A plugin has a manifest and can bundle any combination of these:

• Skills, One or more skill markdown files
• Slash commands, Custom /foo commands with their own logic
• Subagents, Specialized agents the runtime can dispatch (e.g., a reviewer agent, a tester agent)
• Hooks, Lifecycle handlers (pre-tool-use, post-tool-use, stop, etc.) that run on every matching event
• MCP servers, Model Context Protocol servers that expose new tools
• Tool wrappers, Helper binaries the bundled skills or commands depend on

A simplified plugin tree:

my-stripe-plugin/
  .claude-plugin/
    plugin.json             # manifest: name, version, description
  skills/
    stripe-webhooks/
      SKILL.md
    stripe-subscriptions/
      SKILL.md
  commands/
    stripe-test.md          # /stripe-test slash command
  agents/
    payments-reviewer.md    # subagent for payment-related PRs
  hooks/
    hooks.json              # blocks commits that leak Stripe keys
  .mcp.json                 # exposes the Stripe API as MCP tools   # exposes Stripe API as MCP tools

The manifest, at .claude-plugin/plugin.json, lists what is in the box and what version it is. When the plugin is installed, from a marketplace, a git URL, or a local path, Claude Code wires up every component automatically. Skills become available to the agent's description matcher. Commands appear in the slash menu. Hooks start firing at the configured events. The MCP server is registered and its tools are exposed.

That is the key difference. A skill is a single instruction sheet. A plugin is the whole capability bundle.

Plugins matter because they decouple building a workflow from shipping it. A team can develop a "Postgres + Stripe SaaS" workflow inside one repo using local skills and commands. The moment they want a second project, or a teammate, to get the same setup, they package those skills, commands, hooks, and any MCP servers into a plugin and publish it. Now bootstrapping a new repo is claude-code install @ourteam/saas-stack.

We ship plugins to clients exactly this way. The best Claude Code plugins we have studied, internal and public, share that same property: they collapse a stack of conventions into a single install.

Head-to-head

Surface area

A skill is small by design. One file, a few hundred lines, optionally a handful of helper scripts. If your skill grows past 500 to 800 lines, it is almost certainly two skills (or it wants to become a plugin).

A plugin is wide by design. It can ship dozens of skills, multiple slash commands, several subagents, and a full MCP server. The unit of measurement is "how many things does it install", not "how long is the file".

If you find yourself writing a skill that also wants a hook and an MCP tool, stop. That is a plugin.

Distribution

Skills travel with whatever repo they live in. If you commit .claude/skills/migration.md, anyone who clones the repo gets it. There is no install step.

Plugins travel independently of any repo. They are published to a marketplace or a git URL and installed by name. A plugin can be updated without touching any of the repos that use it, bump the version, anyone re-installs, the new behavior shows up everywhere.

The practical rule: if the procedure is about this repo, skill. If the procedure is about a workflow that lives in many repos, plugin.

When to combine

Most production setups combine both. A plugin ships shared skills, commands, and tools. Each individual repo adds its own local skills for repo-specific conventions. The agent picks up both layers and treats them as one set of available procedures.

This is the layering we recommend to clients: one or two opinionated plugins (the agency stack, the company stack), plus a thin layer of repo-specific skills. The plugin handles "how we build SaaS apps". The local skills handle "how this particular SaaS app names its modules".

Discoverability

Skills are discovered by description. When the user makes a request, the runtime checks every loaded skill's description against the request and surfaces matches. Good skill descriptions are critical, they are the only thing the matcher sees before deciding whether to load the file.

Plugins are discovered through the marketplace (or wherever they are published). Once installed, their internal components, skills, commands, become discoverable through the normal Claude Code surfaces. The marketplace gives plugins a name; that is how they enter the world.

If your team keeps re-implementing the same skill in different repos because nobody can find the canonical version, you have a discoverability problem and the fix is a plugin.

Maintenance

Skills are maintained inside each repo. If three repos have the same skill and you change it in one, the others drift. That drift is fine for repo-specific conventions and painful for shared workflows.

Plugins centralize maintenance. One plugin, one source of truth, version-pinned consumers. The cost is that you now have a release process, bumping versions, communicating changes, handling breaking updates.

The trade-off is straightforward: skills are cheap to write and expensive to keep in sync; plugins are more expensive to set up and much cheaper to evolve at scale.

When to use a Skill

Use a skill when the procedure lives in one repo, one team, or is otherwise low-leverage to package.

Scenario 1: Repo-specific naming conventions. Your monorepo has strict module naming (every feature is features/{verb}-{noun}, every internal package is @yourco/{domain}-{capability}). Encode this as a skill:

---
name: module-naming
description: Use when creating new modules, packages, or features in this monorepo. Enforces the naming scheme used across the codebase.
---

# Module Naming

- Features: `features/{verb}-{noun}` (e.g., `features/import-leads`)
- Internal packages: `@yourco/{domain}-{capability}` (e.g., `@yourco/billing-stripe`)
- Public packages: `@yourco-public/{name}`
- Never create flat files at the root of `src/`

This is the right call because the convention is unique to this repo. Packaging it as a plugin would be over-engineering.

Scenario 2: A single repeatable procedure. Your team writes RFC documents in a specific format with a specific review flow. Skill. One file, a template inline, a description that triggers on "draft an RFC" or "write an architecture proposal".

Scenario 3: Capturing a tribal-knowledge gotcha. "The deploy script must be run from scripts/, not the repo root, or Vercel resolves the wrong project." That is a 30-line skill. Anyone who tries to deploy now gets the right context automatically.

Scenario 4: Brand voice or copy guidelines. Marketing-site copy must hit specific tone targets. A skill encodes the voice rules and triggers on "write copy", "draft a landing page section", "rewrite this for the website". We use this on every client site, including the patterns we shipped while building our own listicle pipeline.

Scenario 5: Domain knowledge the agent forgets. Tax rules, healthcare compliance, a specific regulatory framework. Skill body explains the rules; agent loads it when the request touches that domain.

Common thread: one well-defined situation, one file, one team. If the answer to "who else will use this" is "nobody outside our repo", it is a skill.

When to use a Plugin

Use a plugin when the procedure is reusable, multi-component, or needs to be distributed.

Scenario 1: An agency stack. You build SaaS apps with a fixed stack, Next.js, Postgres, Stripe, Clerk, Vercel, and want every new project to get the same skills, the same lint hooks, the same /scaffold-feature slash command, and the same MCP integration with your project management tool. Plugin. Install once per repo, everyone is aligned.

Scenario 2: Custom tools via MCP. You want the agent to query your internal data warehouse, your CRM, or your billing system. Those need MCP servers, and MCP servers must be bundled with documentation telling the agent how to use them. That bundle is a plugin.

Scenario 3: Lifecycle hooks. You want every Claude Code session in a repo to run a pre-tool-use hook that blocks edits to vendor/, or a stop-hook that runs your test suite before declaring done. Hooks are configured in the plugin manifest and ride along when the plugin is installed.

Scenario 4: Specialized subagents. You want a security-reviewer subagent that the main agent can dispatch when working on auth code, and a migration-writer subagent for database changes. Subagents live in plugins, they need their own scope, their own tools, their own description.

Scenario 5: Distributing to clients. This is our main use case. We package our Claude Code conventions, coding rules, review checklists, deployment hooks, custom MCP servers, into a plugin and install it on every client engagement. The client gets a consistent agent experience without copy-pasting markdown files between repos.

Common thread: multiple components, multiple consumers, version-pinned. If you find yourself thinking "I want everyone to have this without explaining it", it is a plugin.

When to combine both

Most mature teams end up with a layered setup. The plugin handles the shared, opinionated stack. The repo-local skills handle the specific conventions of that repo. The agent reads them as a single context.

Concrete example from a recent build:

• Shared plugin (installed once per repo): Next.js conventions, RSC vs client boundary rules, Tailwind tokens, Stripe webhook signing, our deploy hook, MCP server for our internal CRM, three subagents (reviewer, tester, docs-writer), and a /scaffold-route slash command.
• Repo-local skills: This client's brand voice. This client's API naming. This client's specific compliance rules (HIPAA in one case, FERPA in another). This client's product vocabulary so the agent never calls "Boards" "Lists".

The plugin is stable across all our engagements. The local skills are unique per client. The agent treats them as one, the user does not care which layer a procedure came from, only that the procedure was followed.

This layered model is also the cleanest answer to the "should this be a skill or a plugin" question that comes up weekly. The honest answer is usually: a skill for now. If three months later the skill is being copy-pasted into other repos, promote it to a plugin.

How to choose

If you are still on the fence after the scenarios above, the decision boils down to four questions:

1) Who else needs this?

If the answer is "only this repo, only this team", write a skill. If the answer is "everyone who uses our stack", write a plugin. If the answer is "right now just us, but probably others later", write a skill now and promote it later.

2) Does it need a tool, hook, or subagent?

Skills cannot ship tools, hooks, MCP servers, or subagents. They prompt the agent only. The moment your design includes any of those four things, you are building a plugin. Trying to fake it inside a skill, "tell the user to install this Python package and run this script", works for solo use and breaks for distribution.

3) Will the procedure change frequently?

Frequent change argues for a plugin: bump version, everyone updates, no drift. Rare change argues for a skill: commit it once, leave it alone. A skill that needs to be edited weekly across five repos should have been a plugin two months ago. See our breakdowns of the best Claude Code skills and the best Claude Code plugins for examples of each pattern done well.

4) Is there a packaging cost you cannot afford right now?

Plugins have overhead, a manifest, a versioning discipline, a release flow. If the team is two weeks into Claude Code adoption, the right move is almost always a few well-written skills, not a half-finished plugin. Promote later, when the value is obvious and the maintenance pain is real.

Closing: pick the smallest abstraction that solves the problem

Most teams over-build. The first Claude Code workflow does not need a plugin, a marketplace listing, and three subagents. It needs one well-written skill, used by one person, for two weeks. Then a second skill. Then, when the same two skills show up in three repos, the case for a plugin writes itself.

The opposite mistake is also common: keeping everything as skills until the team is drowning in copy-paste drift. By the time a skill exists in five repos with three slightly different versions, the plugin should have happened months ago.

If you want help designing this layering for your stack, what to ship as a plugin, what to keep as repo-local skills, how to wire MCP servers and hooks without breaking your existing workflow, that is exactly the work we do at AY Automate's Claude Code agency. We have built this layering for SaaS teams, agencies, and internal platforms, and we can audit your existing setup or design one from scratch. Book a free consultation to walk through your specific stack.

FAQ

What is the difference between a Claude Code skill and a plugin in one sentence? A skill is a single markdown procedure the agent loads on demand; a plugin is a distributable package that can bundle skills, slash commands, subagents, hooks, and MCP servers together.

Can a plugin contain skills? Yes, that is one of the main use cases. A plugin can ship one or many skills alongside its commands, hooks, and tools. Installing the plugin makes all its skills available to the agent automatically.

Can a skill call a tool the way a plugin does? Skills can instruct the agent to use existing tools (Bash, Read, Edit, MCP tools that are already registered), but skills cannot register new tools or MCP servers. If you need a new tool, you need a plugin.

Do I need a marketplace to publish a plugin? No. Plugins can be installed from a git URL or a local path. The marketplace is convenient for discoverability and versioning, but it is not required. Many teams ship private plugins via git only.

Should I start with skills or plugins? Start with skills. They have near-zero overhead, write a markdown file, commit it, done. Promote to a plugin once you find yourself copy-pasting the same skills into multiple repos or needing tools, hooks, or subagents that a skill cannot ship.

Can a skill and a plugin describe the same procedure? Yes, and it is a common refactor path. A procedure starts as a local skill in one repo, gets copied to a second repo, and once it is in three or more repos, it is extracted into a plugin. The skill version is deleted from the repos and replaced by the plugin install.

Do skills and plugins work together at runtime, or do they conflict? They work together. The agent treats skills from plugins and skills from .claude/skills/ as one set. If two skills have overlapping descriptions, the more specific one usually wins, but this is rare in practice if descriptions are written carefully.

Are plugins the same as MCP servers? No. An MCP server exposes tools over the Model Context Protocol; it is one possible component of a plugin. A plugin can bundle an MCP server plus skills, commands, and hooks. You can also run an MCP server standalone, without any plugin around it.