Plugins are the distribution layer. Skills are the content. A Claude Code plugin is an installable package that can contain one or more SKILL.md files, along with hook configurations, MCP server settings, and install scripts. A skill is the SKILL.md file Claude reads at runtime. You do not need a plugin to use a skill, and most developers never create one.

TL;DR: A skill is a SKILL.md file. A plugin bundles multiple skills, hooks, and MCP configurations into a single installable package. Use a standalone SKILL.md for personal workflows. Build a plugin when distributing a skill to multiple users or bundling it with external dependencies.

What is a Claude Code plugin?

A Claude Code plugin is an installable package containing a manifest file plus one or more component types: skills, hooks, MCP server definitions, or setup scripts. When a user installs a plugin, Claude Code reads the manifest and places each component in the correct directory. SKILL.md files go to .claude/skills/, hook scripts go to .claude/hooks/, MCP configurations merge into .claude/settings.json.

At AEM, roughly 70% of the skills we build ship as standalone files placed directly in a project's .claude/skills/ folder. The other 30% get plugin packaging, and the reason is always one of two things: the skill depends on an MCP server that must be configured alongside it, or the skill needs to deploy to multiple developers who cannot be expected to manage files manually.

The plugin format exists to solve a distribution problem. Before plugins, distributing a skill library to a 20-person team meant writing your own setup script or walking each person through file placement. Plugins reduce that to one install command. Claude Code had 1.6 million weekly active developers as of February 2026 (Pragmatic Engineer Survey, 2026, n=15,000). At that scale, file-placement friction compounds fast.

"Developers don't adopt AI tools because they're impressive, they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

The friction argument cuts both ways. A plugin eliminates the friction of multi-user distribution. Creating a plugin where a single file would work adds its own friction: a manifest to maintain, a version to track, an installer to test.

What can a plugin contain that a standalone skill file cannot?

A standalone SKILL.md provides exactly one thing: the skill itself. Description, trigger conditions, step-by-step instructions, and pointers to reference files. That is sufficient for any self-contained skill. What it cannot do is bundle hooks, configure MCP servers, or guarantee that external dependencies are installed alongside it. A plugin adds all three.

A plugin extends that with three additional component types:

  1. Multiple skills: A plugin can bundle a full workflow suite. A content production plugin might include separate skills for drafting, reviewing, formatting, and publishing, all installed together so cross-skill references resolve correctly.
  2. Hook configurations: Hooks run automated actions before or after Claude executes a task. A plugin can include hooks that log skill invocations, auto-format output, or trigger downstream processes. A SKILL.md file cannot define hooks.
  3. MCP server definitions: If a skill needs to query a database, call an API, or read files beyond Claude's native tools, it needs an MCP server. A plugin can bundle the MCP server configuration alongside the skill, ensuring they are installed together and the skill never runs without its dependencies.

This matters in practice: a SKILL.md that requires an MCP server will fail silently if the MCP server is not configured. A plugin that bundles both eliminates that failure mode. A 2025 analysis of MCP tool descriptions across the ecosystem found that 97.1% contained at least one quality issue (MCP ecosystem analysis, 2025). Packaging configuration alongside the skill is not optional when the skill depends on it. A survey of active MCP builders found that 70% already have two to seven MCP servers configured in their development environment (Zuplo State of MCP Report, 2025, n=100). When a developer is managing that many servers, one misconfigured dependency is enough to break a skill they didn't touch.

For a deeper look at how MCP servers and skills divide responsibilities, see When Should I Use MCP Tools vs Encoding Logic in a Skill?.

When do you need a plugin instead of a standalone skill?

Use a plugin when your skill cannot be deployed by dropping a single file. The four cases that cross that line: distributing to multiple users, bundling an MCP server dependency, linking a suite of co-dependent skills, or managing versioned rollouts. Everything else is a standalone SKILL.md.

  • Multiple recipients: If more than one person needs the skill, a plugin reduces installation to one command. For teams of 10 or more, the difference between a plugin and manual file distribution is meaningful.
  • External dependencies: If the skill requires a specific MCP server or API integration, bundle them in a plugin so they are never installed separately.
  • Related skills that must co-install: A skill library where skills reference each other needs to be installed as a complete set. A plugin enforces that.
  • Versioned distribution: Plugin versioning lets you push updates to all users at once. Standalone skill files have no version tracking.

For solo developers building personal productivity workflows, a standalone SKILL.md is almost always correct. In our work at AEM, we see 1 in 5 early-stage commissions request plugin packaging when there is no distribution requirement and no external dependency. The plugin adds a manifest, a version number, and an installer to maintain, for a skill used by one person on one machine. Team adoption changes the calculation. 84% of developers now use AI tools in their development process, up from 76% the prior year (Stack Overflow Developer Survey, 2025, n=65,000). When that many people on a team are running Claude Code, coordinated skill distribution stops being optional.

How do you install a plugin vs add a skill file?

The two approaches differ in complexity by an order of magnitude. Adding a standalone skill file is three manual steps with no tooling required. Installing a plugin runs a five-step automated sequence through the /install command in Claude Code. The end state is identical: a SKILL.md in .claude/skills/ that Claude reads at startup. The difference is who does the work.

Adding a standalone skill file requires three steps:

  1. Create the SKILL.md in your editor.
  2. Place it in .claude/skills/ in your project directory.
  3. Start a new Claude session.

Claude reads the file at startup and the skill is immediately available. No command, no manifest, no install process.

Installing a plugin uses the /install command in Claude Code. The command runs five steps in sequence:

  1. Reads the plugin manifest.
  2. Validates the package.
  3. Copies component files to their target directories.
  4. Runs any setup scripts.
  5. Reports what it installed.

The entire process takes one command (source: Claude Code documentation, Anthropic, 2025).

Both approaches result in identical runtime behavior. Claude reads skill files from .claude/skills/ regardless of whether they were placed there manually or by a plugin installer. The install mechanism affects distribution and maintenance, not skill performance. 73% of engineering teams use AI coding tools daily as of early 2026, up from 41% in 2025 (Pragmatic Engineer Survey, February 2026, n=15,000). Teams at that adoption level need repeatable installation, not manual file placement.

Does installing a plugin guarantee the skill works?

No. A clean install confirms that files landed in the correct directories. It says nothing about whether the skill description triggers reliably, whether the step-by-step instructions produce consistent output, or whether reference files contain the domain knowledge Claude needs to do the job. Installation and reliability are separate problems.

"The failure mode isn't that the model is bad at the task, it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

A well-packaged plugin with a poorly written SKILL.md installs in 10 seconds and fails on every third invocation. Distribution is not the same problem as reliability. Both need to be solved independently. A 2025 stress test of 100 production MCP servers found a median pass rate of 71%, with schema mismatches accounting for 38% of all failures (Digital Applied, 2025). The install succeeded on all 100. The skill worked reliably on 71.

This applies to single-domain skills. For skills spanning multiple domains or requiring complex orchestration, the gap between "installed" and "working" widens further, because more components can fail independently.

For a guide to making skills trigger reliably regardless of how they are distributed, see How Do I Write a Good Skill Description?.

Frequently Asked Questions

Can I use a skill without wrapping it in a plugin? Yes. Placing a SKILL.md file directly in .claude/skills/ is the standard approach for personal or single-machine use. Plugins are an optional distribution layer, not a requirement for skill functionality. The majority of production Claude Code skills are never packaged as plugins. A survey of active MCP builders found that 58% are wrapping existing APIs rather than building new infrastructure from scratch, which means the distribution tooling is the afterthought, not the starting point (Zuplo State of MCP Report, 2025).

What is the relationship between a plugin manifest and a SKILL.md? The manifest is the plugin's index, describing what the package contains and where each file should be installed. The SKILL.md is the actual skill content. The manifest points to SKILL.md files; the SKILL.md is what Claude reads at runtime to understand how to execute the skill.

Can one plugin contain multiple skills? Yes. A plugin can bundle an entire library of related skills. This is the primary use case for plugin packaging: delivering a coherent skill set that users install together and that can reference each other reliably across workflows.

Will reinstalling a plugin overwrite local edits to skill files? Yes. Plugin installers copy files to target locations without checking for local modifications first. If you have edited a plugin-installed skill file, a reinstall or version update will overwrite your changes. Keep local modifications in a separate file that the SKILL.md references.

Do plugin-installed skills perform differently from manually placed skill files? No. Once installed, a plugin-distributed SKILL.md is identical to a manually placed one. Claude reads both from the same location and applies the same activation and execution logic. The plugin is packaging, not runtime behavior.

Should beginners start with plugins or standalone files? Start with standalone SKILL.md files. Get comfortable with skill format, description writing, and activation behavior before adding plugin packaging. Add the plugin layer when distribution becomes the actual problem you are solving, not as a default approach. AI adoption among software development professionals reached 90% in 2025, up 14% year-over-year (DORA State of AI-Assisted Software Development, 2025, n=2,800+). At that adoption level, the skill quality bar matters far more than the packaging layer. Get the skill right first.

Last updated: 2026-05-06