Plugins

 Plugins — one-step installation of your entire setup

A plugin bundles your skills, hooks, subagents, and MCP servers into a single versioned installable unit. Instead of a teammate manually copying your .claude/ directory, configuring hooks, and wiring MCP servers — they run one install command and get the identical setup.

Structure of what a plugin contains:

plugin/
  skills/          ← your .md skill files
  hooks/           ← PreToolUse, PostToolUse scripts
  agents/          ← custom subagent definitions
  settings.json    ← MCP servers, permissions
  manifest.json    ← describes the bundle

---

Marketplace — where plugins are distributed

• Anthropic's official marketplace is available automatically in Claude Code
• Add third-party marketplaces (hosted on GitHub) with /plugin marketplace add <owner/repo>
• Enterprise admins can deploy plugins org-wide via managed settings — sits above user and project settings, cannot be overridden

---

The decision table — which layer to reach for

Layer	Reach for it when
Skill	A procedure should stay out of context until the task calls for it
Custom command	The procedure has a clear name and you want explicit invocation
Plugin	A working setup on your machine needs to be shared, versioned, and kept consistent across a team

---

The one risk worth remembering

A deny rule or hook you rely on locally is not included in a plugin unless explicitly listed in the bundle. If your guardrails aren't part of the plugin manifest, your teammates install the skills without the safety net you built around them. Always audit what the plugin actually bundles before distributing it.

Installation success and Execution success are two different things.

What went wrong

A developer built a deployment skill, tested it locally, packaged it as a plugin, pushed it to the internal marketplace. Every teammate's install succeeded. Every teammate's execution failed.

Two root causes in the same SKILL.md:

bash

# Failure 1 — absolute path to author's home directory
/Users/joseph/projects/deploy-utils/validate.sh

# Failure 2 — environment variable set only in author's shell profile
$DEPLOY_TOKEN

The first failure is visible — a reviewer reading the file can catch it immediately. The second is invisible — nothing in the package announces the dependency, the skill runs fine until the exact step that needs $DEPLOY_TOKEN, and only then fails silently. That's why it cost three people two hours to debug.

---

The fix — four rules

1. No absolute paths, ever.
Use $CLAUDE_PROJECT_DIR for scripts stored in the project, ${CLAUDE_PLUGIN_ROOT} for scripts bundled inside the plugin itself.

bash

# Wrong
/Users/joseph/projects/deploy-utils/validate.sh

# Right
${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh

2. Bundle everything the plugin needs.
Scripts, config files, assets — either inside the plugin or in a shared project location every teammate gets on install. Nothing that only exists on the author's machine.

3. Document and validate every environment variable at install time.
Don't let a missing variable surface mid-run. Surface it immediately when the plugin installs, not two hours into a debugging session.

4. Test on a clean machine before distributing.
Your own machine hides problems. A clean machine reveals them instantly.

---

The underlying principle

The author's machine is not the team's machine. A plugin that only works on the author's setup isn't a plugin — it's a local script with extra packaging steps. Portability has to be deliberately designed in, because nothing in the installation process will warn you it's missing.