Plugins — Packaging and Sharing

All those skills, hooks, MCP configs, and settings you've been building across these lessons? Scattered files. Plugins bundle them into a single installable unit. Hand it to a teammate, share it publicly, reuse across projects.

Instead of "copy these five files, add this hook config, install this MCP server," you give them one plugin. Done.

What Goes Inside a Plugin

A directory with a manifest at its root. Everything else is optional.

{
  "name": "my-team-plugin",
  "description": "Standard dev workflows for our team",
  "version": "1.0.0",
  "author": "your-name"
}

That goes in .claude-plugin/plugin.json. Around it, include whatever your plugin needs:

A skills/ directory for SKILL.md files. A hooks/ directory with hooks.json for event-driven automation. An agents/ directory for agent definitions. .mcp.json for MCP server configs. .lsp.json for LSP servers. settings.json for defaults when the plugin is active.

That code review skill from a previous lesson? The pre-commit linting hook? The MCP server connecting to your issue tracker? Bundle them all into one plugin.

Namespacing

Plugin skills get namespaced automatically. Plugin called my-team-plugin with a review skill? You invoke it as /my-team-plugin:review. No collisions with other plugins or standalone skills.

Only skills get namespaced, though. Hooks, MCP configs, and settings merge with your existing setup. On conflict, your local project config wins. Always.

Testing Locally

Test before you share. Always.

claude --plugin-dir ./my-plugin

This treats ./my-plugin as an installed plugin for the session. Full experience: namespaced skills, hooks firing, MCP servers connecting. Manifest errors or skill typos surface immediately.

Multiple plugins at once:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Useful when your team has separate plugins for different concerns. Test them together before rolling out.

Try It

Minimal plugin from scratch:

mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills

Write the manifest file at my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "quickstart",
  "description": "A minimal plugin with one skill",
  "version": "0.1.0",
  "author": "you"
}

Create a skill at my-first-plugin/skills/SKILL-summarize-pr.md:

# summarize-pr
 
Fetch the latest pull request for the current repo using `gh pr list --limit 1 --json title,body,files`.
Summarize the changes in 3 bullet points. Focus on what changed and why, not which files were touched.
If the PR has no description, note that and summarize based on the changed files alone.

Test it:

claude --plugin-dir ./my-first-plugin

Type /quickstart:summarize-pr inside the session. If it works, you have a functioning plugin. If not, check the name field in your manifest and that the skill file is in skills/.

Converting Existing Work Into a Plugin

You probably already have skills and hooks scattered around. Converting is mechanical: create the plugin directory structure, copy SKILL.md files into skills/, hooks config into hooks/hooks.json, MCP entries into the plugin's .mcp.json, write the manifest, test with --plugin-dir.

The real question is whether you should. Standalone skills in .claude/ work fine for one project. Plugins are portable, meant for other people on other machines. If it's only useful to you in one repo, keep it standalone. If teammates would benefit, or you want it across all your repos, make the plugin.

Sharing

Three distribution paths, in order of effort:

Git repo. Push to GitHub, people clone and use --plugin-dir. Simple, works for teams sharing tooling through internal repos.

The /plugin command. Install from a URL or registry directly inside Claude Code. Most convenient for consumers since there's no manual cloning.

Official marketplace. Submit at claude.ai/settings/plugins/submit for maximum visibility. There's a review process, so your manifest needs to be complete and your skills need to actually do what they claim.

When Plugins Are Overkill

Not everything needs to be a plugin. Skill for a single project with no reuse plans? Standalone SKILL.md. Hooks that only make sense for one codebase? Project-level config.

Plugins add real overhead: manifest maintenance, versioning, backward compatibility if others depend on you. Worth it for team sharing and community distribution. Not worth it for personal one-offs.

Best approach: start standalone. Build skills and hooks where you need them. Get them working. When you catch yourself copying the same files to a second project or walking a teammate through your setup, that's conversion time.

A plugin is a directory with a plugin.json manifest plus whatever combination of skills, hooks, agents, MCP configs, LSP configs, and settings you need. Skills get namespaced (/plugin-name:skill-name), everything else merges. Always test locally with claude --plugin-dir ./your-plugin before sharing. And start standalone, converting to a plugin only when you actually need portability.