A Claude Code plugin is a packaged distribution format that bundles one or more Claude Code skills together with their configuration, dependencies, and installation metadata. Where a bare SKILL.md requires the installer to manually copy files into the correct directory, a plugin installs with a single command and brings its dependencies along. The packaging step is the difference between "copy this file somewhere" and "run one command and it works."
TL;DR: A plugin packages Claude Code skills for distribution, handling installation, version management, and dependency declaration automatically. AEM builds and commissions skills in both formats. Use bare SKILL.md for simple single-skill sharing. Use plugin packaging for multi-file skills, MCP dependencies, or active user bases. Rule of thumb: if installation takes more than four lines of instructions, package it.
What Does a Claude Code Plugin Actually Contain?
A plugin is a directory with a defined structure that Claude Code's package manager can process. The critical piece is the package.json manifest: it declares the plugin name, version, the skills it bundles, and any MCP server dependencies. The manifest is what lets Claude Code install everything automatically. Without it, the directory is just a folder with a SKILL.md inside.
The core contents:
my-skill-plugin/
package.json — name, version, description, dependencies
skills/
my-skill/
SKILL.md — the skill itself
references/ — reference files, if any
mcp/
server-config.json — MCP server declarations the skill needs
README.md — installation instructions at repository root
The package.json is what makes it a plugin rather than a bare skill directory. It declares the plugin name, the skills it contains, and the MCP servers it depends on. When a user installs the plugin, Claude Code reads this manifest and configures all three components — skills, references, and MCP servers — in the correct locations without manual placement.
A bare SKILL.md has none of this infrastructure. It works, and for simple single-file skills it's entirely appropriate. Plugin packaging adds installation convenience and version management at the cost of a more complex repository structure. The official Anthropic marketplace listed 101 verified plugin-format skills as of March 2026 (claudemarketplaces.com, 2026); the community ecosystem extends well beyond that through independent marketplaces.
How Does Plugin Packaging Help Distribution?
Plugins solve three specific distribution problems that bare SKILL.md files cannot: multi-file placement, MCP dependency declaration, and version management for an active install base. Each is solvable manually, but the manual path requires the installer to follow instructions precisely and execute multiple steps without error. Plugin format eliminates that failure surface by encoding the correct configuration in the manifest.
- Multi-file skill distribution: A skill with three reference files requires the installer to know which files go where. In a plugin, the manifest handles placement. The installer runs one command; the files land in the right directories.
- MCP server dependencies: If your skill relies on a specific MCP server, a bare SKILL.md can only document that dependency in text. A plugin can declare the MCP server in
server-config.json, and the installation process can prompt the user to configure it or even configure it automatically. - Version management: When you update a bare SKILL.md on GitHub, installers need to manually re-download and overwrite their local copy. A plugin supports version pinning and update commands. Users on version 1.2 can run an update command to get 1.3 without touching file paths.
"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." — Addy Osmani, Engineering Director, Google Chrome (2024)
That same principle applies to installation formats. An explicit, structured plugin format produces consistent installs. A "copy these files somewhere" instruction produces installation errors proportional to how many files are involved.
When Should I Use Plugin Packaging vs. Bare SKILL.md Distribution?
Use bare SKILL.md distribution for single-file skills with no external dependencies, shared with developers comfortable with manual file placement. Switch to plugin packaging when your skill has two or more reference files, requires MCP servers, or has an install base needing updates. The dividing line is whether installation requires the user to make decisions about file placement.
Bare SKILL.md distribution works for:
- Single-file skills with no reference files
- Skills with no external MCP dependencies
- Personal sharing with a specific colleague who can follow manual instructions
- Skills posted to GitHub where the primary installer is a developer comfortable with manual setup
Plugin packaging makes sense for:
- Skills with two or more reference files that must land in specific directories
- Skills that require one or more MCP servers to function
- Any skill distributed through SkillsMP or SkillHub where you expect non-developer installers
- Skills with an active user base that will need to receive updates
In our commissions at AEM, we've shipped both formats. For single-file utility skills, bare SKILL.md on GitHub is faster to maintain and easier for developers to inspect. For production workflows involving MCP integrations and multiple reference files, plugin packaging eliminates a class of "why isn't this working" support requests that would otherwise land in our email (AEM commission data, 2026).
The 700,000+ skills on SkillsMP (SkillsMP, 2026) are a mix of both. Community skills in plugin format have consistently higher install success rates, because the installation process is explicit rather than instruction-dependent. This matters because 71% of developers who regularly use AI agents now use Claude Code (Pragmatic Engineer Survey, February 2026), and most of them are installing community skills, not building from scratch.
"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)
Plugin format is friction reduction made concrete. A single install command beats a four-step README every time.
How Do I Create a Plugin from an Existing Skill?
The conversion from bare SKILL.md to plugin format takes four steps and under an hour for most existing skills. The only new file you are creating is package.json; the SKILL.md itself does not change. Get the manifest right, move the files into the correct directory structure, add a root README, and test on a clean install before publishing.
- Create the package.json: This is the manifest Claude Code reads during installation:
{
"name": "my-skill-plugin",
"version": "1.0.0",
"description": "Short description of what the skill does",
"claudeSkills": ["skills/my-skill"],
"mcpServers": []
}
Fill mcpServers with any MCP server dependencies the skill requires.
Move files into the plugin directory structure: Place your SKILL.md and reference files under
skills/my-skill/, following the standard SKILL.md folder structure.Add a README.md at the repository root: Not inside the skill folder; that adds noise Claude Code has to skip. The root README.md is for human installers, not Claude. Include the install command, the version requirements, and what the skill does.
Test installation: Run the install command on a clean machine or fresh directory. If it fails, the manifest has an error. Fix it before publishing.
For attribution and licensing in the plugin format, the same rules apply: author, version, and license fields belong in both the package.json and the SKILL.md frontmatter. See How Do I Add Attribution to a Free Skill I'm Distributing for the complete attribution checklist.
With 73% of engineering teams using AI coding tools daily as of February 2026, up from 41% in 2025 (Pragmatic Engineer Survey, 15,000 developers), the install experience for community skills is now a competitive differentiator. Plugin format is how you ensure your skill's first impression is a working install, not a troubleshooting session.
What Are the Limits of Plugin Packaging?
Plugin packaging solves one problem: getting the skill and its dependencies onto the user's machine without manual file placement. It has no effect on whether the skill works correctly, whether its description triggers on the right inputs, or whether anyone tested it on edge cases. A clean install is not a quality signal.
A well-packaged bad skill installs cleanly and then fails to work. The plugin format reduces friction between a user and a skill. It has no effect on whether the skill's description triggers correctly, whether the output contract is defined, or whether the skill has been tested on inputs other than the author's.
Before packaging, verify the skill passes the production bar: working description field under 1,024 characters (Anthropic Claude Code specification, code.claude.com/docs), defined output contract, tested reference file loading, and cross-project portability. Packaging a skill that hasn't passed this bar just makes it easier for more people to install something that doesn't work.
For evaluating whether a community skill meets the production bar before you install it in your own project, see What Makes a Community Skill Production Ready.
"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)
Plugin packaging does not fix ambiguous instructions. It delivers them more efficiently.
Plugin packaging is also not a requirement for distribution. Most of the 700,000+ skills on SkillsMP are bare SKILL.md files distributed without plugin infrastructure. For individual skill authors without an active install base, bare distribution is faster to ship and easier to maintain.
Frequently Asked Questions
Creating and distributing Claude Code plugins raises consistent questions around tooling requirements, marketplace compatibility, and version control. No JavaScript knowledge is required; the package.json is plain JSON, not code. The six questions below address the most common decision points for skill authors moving from bare SKILL.md to plugin format.
Do I need to know JavaScript or npm to create a Claude Code plugin?
The package.json format is JSON, not JavaScript, and Claude Code plugins do not require any code — just a valid JSON manifest and your SKILL.md files. You don't need to run npm install or write code to package a skill as a plugin.
Can I submit a plugin to SkillsMP and SkillHub the same way as a bare skill? Yes. SkillsMP and SkillHub accept both plugin-format and bare SKILL.md submissions. The submission process is the same. The platforms differ in curation model: SkillHub evaluates all submissions on five quality dimensions and lists approximately 7,000 curated skills, while SkillsMP aggregates broadly (Claude Skills Marketplace Comparison, OpenAIToolsHub, 2026). Plugin format skills get better visibility on platforms that display install complexity, since the install process is simpler for users.
What happens to plugin versioning when I update my SKILL.md?
Increment the version field in package.json and update the version field in the SKILL.md frontmatter to match. Users with an existing install can then run an update command to receive the new version.
Can one plugin contain multiple skills?
Yes. Add each skill directory path to the claudeSkills array in package.json. This is the primary advantage of plugin packaging for skill bundles: users install one package and get a coordinated set of skills that are designed to work together.
Is plugin packaging supported across all Claude Code versions? Plugin packaging was introduced in Claude Code 2.0. Bare SKILL.md distribution works on all versions. If your target audience includes Claude Code 1.x users, distribute as bare SKILL.md and document the version requirement clearly.
How do I handle MCP server configuration inside a plugin?
Declare the MCP server in the plugin's mcp/server-config.json. The installation process will surface the configuration step to the user rather than letting the skill fail silently when the MCP server is absent.
Last updated: 2026-04-26