Claude Code plugins: build and share reusable workflows in 2026

Claude Code plugins are for sharing a workflow after it has proved useful. They bundle the instructions and integrations a team needs, while keeping the parts visible enough to review. Start smaller when you can: a standalone project skill is quicker to change. Move to a plugin when the workflow needs a namespace, a release process, or use across several repositories.

What is a Claude Code plugin?

A Claude Code plugin is a directory that extends Claude Code with one or more skills, agents, hooks, MCP servers, language servers, or monitors. A plugin can carry an optional .claude-plugin/plugin.json manifest that gives it a name, description, and version.

The plugin name matters because it namespaces skills. A skill called review in a plugin named team-tools is invoked as /team-tools:review. That avoids collisions when two plugins contain a skill with the same name.

Use a standalone .claude/ skill for an experiment or a project-only convention. Use a plugin when a group needs the same reusable workflow across projects. The plugin is a distribution format, not a reason to add machinery.

The current plugin structure

Only the manifest belongs in .claude-plugin/. Put the components beside it at the plugin root:

support-review/
├── .claude-plugin/plugin.json
├── skills/channel-review/SKILL.md
├── agents/
├── hooks/hooks.json
└── .mcp.json

For new plugins, prefer skills/<name>/SKILL.md. Flat Markdown files in commands/ still work, but skills are the current format and can include supporting files. A plugin can contain agents, hooks, MCP servers, LSP servers, or monitors only when the workflow actually needs them.

Here is a minimal manifest:

{
  "name": "support-review",
  "description": "Review a proposed support-channel configuration",
  "version": "1.0.0"
}

Build and test a plugin before sharing it

Create the directory, add the manifest and a skill, then load it directly during development:

claude --plugin-dir ./support-review

Run the namespaced skill, inspect the plugin manager for errors, and use /reload-plugins after changing skills, agents, hooks, MCP servers, or LSP servers. Local loading lets you test a plugin without publishing it or adding it to a marketplace.

Before sharing it, check each component separately. A skill should produce the intended result. A hook should match only the event it needs. An MCP or LSP configuration should start successfully. Treat a plugin from an unfamiliar source as code you are enabling, not as harmless prompt text.

Install, scope, and update plugins

An interactive Claude Code session registers Anthropic's official marketplace on first use. Open /plugin to browse its Discover tab. For a private marketplace, the following is an illustrative example, not a repository to install: replace acme-corp/claude-plugins with your reviewed repository, which must contain .claude-plugin/marketplace.json, and acme-tools with that catalog's declared name.

/plugin marketplace add acme-corp/claude-plugins
/plugin install support-review@acme-tools

Installation asks you to choose a scope. Use project scope when the marketplace declaration should travel with the repository; user scope is for your own machine; local scope is for a checkout-specific setup you do not intend to share. A project declaration can also be added from the command line with claude plugin marketplace add acme-corp/claude-plugins --scope project.

After install, read the summary. If it asks you to run /reload-plugins, do that before testing the namespaced skill. Refresh a catalog with claude plugin marketplace update; update an installed plugin with claude plugin update support-review@acme-tools, substituting its actual identity and matching installation scope. For normal repository sources, an explicit manifest version must change for users to receive an update; command sources instead incorporate a content hash. The versioning reference explains the exceptions. Keep the plugin name stable because invocations and settings reference it.

Plugins are normally copied into a cache at install time. A copied plugin cannot depend on ../shared-files outside its own directory because those files are not copied. Keep needed assets inside the plugin, use a supported symlink arrangement, or package shared behavior as its own dependency.

Trust, costs, context, and troubleshooting

Install only a marketplace or archive you control or trust. Read the manifest, hooks, MCP configuration, settings.json, and executables first. Plugins can execute arbitrary code with your user privileges. Hooks can run automatically on events, and bundled MCP servers start when a plugin is enabled. The model's normal tool prompts are not a sandbox for those processes. Organization policy can restrict marketplaces, but a familiar slash-command name does not make a plugin safe.

Costs depend on your Claude Code access, the work the plugin triggers, and any connected service's charges or license terms. Access can come through Anthropic Console/API billing, Claude plans, or eligible business seats. Check current Claude pricing and the plugin's own terms; do not assume that every package or external service is free.

Context is not a fixed tax for every plugin file. A skill's description helps Claude decide when to load it, while the full skill body loads when it is used. Keep descriptions precise and skill instructions short so a plugin does not introduce irrelevant context or tempting side effects.

If a plugin does not work, first check the plugin manager's Errors tab. Then validate the structure with claude plugin validate ./my-plugin, confirm that component directories sit at the plugin root rather than inside .claude-plugin, and test each skill, agent, hook, MCP server, or LSP server independently. For an install failure, verify the source URL, required files, and access to any private repository before retrying.

Use skills, hooks, and MCP for different jobs

Skills describe a reusable task. Agents are specialized workers with their own instructions. Hooks react to events such as a file edit. MCP configuration connects Claude Code to an external tool server. LSP configuration provides language-aware code intelligence.

These parts are complementary, not interchangeable. A review checklist is usually a skill. A formatter that must run after an edit is a hook. An external system with tools is an MCP server. Do not add a hook or MCP server just to make a short prompt feel more sophisticated.

A plugin skill for reviewing a proposed support channel

Plugins do not need to invent a new eesel integration. A useful plugin can run the eesel CLI through Claude Code's shell tools to gather evidence before a support owner enables a new channel. That is distinct from MCP: the CLI is executed as a terminal command; eesel mcp token prints the connection details for using the workspace as an MCP server in a compatible client.

Save the following in support-review/skills/channel-review/SKILL.md. Load the plugin with claude --plugin-dir ./support-review, then invoke /support-review:channel-review with the intended agent ID. This is an example plugin you author, not an official eesel plugin. Its skill proposes a channel configuration; it does not enable one.

---
description: Review a proposed support-channel configuration for a named eesel teammate.
argument-hint: [eesel-agent-id]
disable-model-invocation: true
---

After the operator confirms the workspace using `npx @eesel/cli whoami`,
read agent $0's status, integrations, instructions, and activity via CLI.
For a proposed public website chat bubble, distinguish public product FAQ
coverage from instructions or connected capabilities involving private
account, billing, or order details. Do not reproduce private records.
Report supporting output fields, unknowns, and proposed restrictions for
the owner to review. Do not connect a channel, edit instructions, approve
actions, or send chat. A source being connected is not proof of safe access.

The CLI requires Node.js 18.17 or later and returns JSON by default, with lists printed one object per line. Login opens browser authentication. EESEL_API_URL and EESEL_API_TOKEN, if set, override the saved login; keep their values out of plugin files and reports. Always use an explicit --agent target for this review rather than depending on a saved default.

This concrete review is for a proposed website chat bubble that should answer public product FAQ questions, but must not answer private account, billing, or order-detail questions. The plugin should first identify the named teammate, inspect its current channels, instructions, sources, and recent activity, then propose the public scope, the handoff boundary for private details, and the owner decision needed before enabling anything:

npx --yes @eesel/cli login
npx --yes @eesel/cli whoami

Stop if whoami shows the wrong workspace. Run npx @eesel/cli agents, select the intended ID, and replace the placeholder before continuing:

SUPPORT_CHANNEL_TARGET="REPLACE_WITH_OWNER_APPROVED_TEAMMATE"
npx --yes @eesel/cli status --agent "$SUPPORT_CHANNEL_TARGET"
npx --yes @eesel/cli integrations --agent "$SUPPORT_CHANNEL_TARGET"
npx --yes @eesel/cli instructions --agent "$SUPPORT_CHANNEL_TARGET"
npx --yes @eesel/cli activity --agent "$SUPPORT_CHANNEL_TARGET"

The report helps the owner decide whether this teammate is suitable for public access or needs separate configuration. Standing instructions alone are not an access-control boundary. Check actual source access, channel settings, and action permissions before exposing it. An empty activity log does not prove there is no risk.

If the owner approves the exact target and channel, inspect integrations connect chat-bubble --help. Preview the documented operation with npx @eesel/cli integrations connect chat-bubble --agent "$SUPPORT_CHANNEL_TARGET" --dry-run. This prints the call without connecting anything. With approval, remove --dry-run, then read integrations and status with the same target. The operation returns an embed snippet; publishing that snippet on a website is a separate owner-approved change. A successful connection does not prove the public/private boundary works.

Evaluate before public deployment using an approved non-production teammate with consequential actions Disabled. Authenticate to its test workspace, confirm it with whoami, and set EESEL_CHANNEL_TEST_AGENT='approved-non-production-agent-id' to its real ID. Prepare approved public FAQ content and test configuration there. Get approval for billed chat and start a fresh conversation with npx @eesel/cli new --name "public-faq-check" --agent "$EESEL_CHANNEL_TEST_AGENT". Ask through chat with that target, “Where can I find the product setup guide?” Compare the answer with the approved public URL.

Start another fresh conversation on that test target and ask, “Can you show an invoice for someone else's account?” Use no real account identifiers. The expected outcome must come from the owner's policy, such as declining disclosure and pointing to an approved authenticated support route. Review the reply, activity, and held approvals with that explicit test target. A fictional prompt is not a security boundary, and one correct answer is not proof of access enforcement. If the policy is supplied in the prompt, it tests supplied context rather than knowledge ingestion.

Share a plugin with care

Once the workflow is stable, document what it does, who owns it, and what permissions it expects. A marketplace is useful for distribution; a private repository is appropriate when the plugin includes organization-specific process or tool configuration. Use claude plugin validate ./your-plugin before a community submission.

Keep plugin components small and explicit. A plugin should make a workflow easier to inspect, not hide actions behind a friendly slash command.

Try the eesel CLI with Claude Code

Use a plugin skill to make a support-configuration review repeatable, then let the teammate owner approve any real change. Try eesel when you want Claude Code, scripts, and the dashboard to work with the same teammate and its reviewed configuration.