Plugin Composition

Plugin Composition

A plugin is more than the sum of its components. Shared conventions — path substitution, namespacing, directory layout, hook merge order — make the difference between a plugin that "just works" and one that breaks the moment it meets another installed plugin.

When to use this skill

• Building a plugin that contains more than one component type (e.g. skills + hooks)
• Deciding where to put shared scripts that multiple skills use
• Confused about ${CLAUDE_PLUGIN_ROOT} vs ${CLAUDE_PLUGIN_DATA} vs ${CLAUDE_PROJECT_DIR}
• A path reference in a hook or skill script is not resolving at runtime
• Your plugin breaks when installed alongside another plugin that has a similar hook
• Designing an MCP server alongside a skill and unsure how they should share state

When NOT to use this skill

• Deciding which component type to use → plugin-architecture
• Writing a single skill's content → skill-foundry
• Writing hook scripts → plugin-hooks
• Designing MCP tools → mcp-server

The canonical directory layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # REQUIRED — plugin manifest
├── README.md                    # REQUIRED — user-facing docs
├── CHANGELOG.md                 # recommended
├── LICENSE                      # recommended
│
├── skills/                      # if plugin has skills
│   └── <skill-name>/
│       ├── SKILL.md             # required per skill
│       ├── references/          # progressive disclosure
│       ├── scripts/             # skill-private scripts
│       ├── evals/               # plugin-evaluation format
│       └── fixtures/
│
├── hooks/                       # if plugin has hooks
│   ├── hooks.json               # hook configuration
│   └── scripts/                 # hook scripts
│
├── agents/                      # if plugin has subagents
│   └── <agent-name>.md
│
├── commands/                    # if plugin has slash commands
│   └── <command-name>.md
│
├── .mcp.json                    # if plugin ships an MCP server
│
├── scripts/                     # SHARED scripts across multiple skills
│   └── *.py / *.sh              # referenced as ${CLAUDE_PLUGIN_ROOT}/scripts/X
│
└── bin/                         # alternative: executable wrappers
    └── plugin-cli               # invoked as ${CLAUDE_PLUGIN_ROOT}/bin/plugin-cli

Rules:

1. plugin.json lives in .claude-plugin/, not the root
2. A skill's private scripts live inside the skill directory (skills/X/scripts/)
3. Scripts used by multiple skills live at the plugin root (scripts/)
4. Hook scripts live under hooks/scripts/ — they are not shared with skills even if the code is similar

Full annotated layout: references/directory-layout-reference.md.

Path substitution variables

Claude Code substitutes these in hooks.json command strings and in skill bodies (when the skill is executed by a tool-using flow). The difference between them matters:

CLAUDE_PLUGIN_ROOT — the install dir

Use for read-only bundled assets: scripts, hook scripts, reference files, bundled fixtures.

{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"}

⚠️ Wiped on plugin update. Anything you write here is gone after /plugin update. For state, use CLAUDE_PLUGIN_DATA.

CLAUDE_PLUGIN_DATA — persistent per-plugin state

Use for: counters, cached responses, per-user preferences, log files.

mkdir -p "$CLAUDE_PLUGIN_DATA"
echo "$count" > "$CLAUDE_PLUGIN_DATA/run-count.txt"

Not shared across plugins. If plugin A needs to see plugin B's state, they must coordinate through CLAUDE_PROJECT_DIR or an external store.

CLAUDE_PROJECT_DIR — the user's project

Use for: project-relative paths in hook scripts, reading .claude/settings.json, writing into the user's repo.

# Read current project's CLAUDE.md
cat "$CLAUDE_PROJECT_DIR/CLAUDE.md"

CLAUDE_ENV_FILE — set env vars that persist beyond the hook

Hook scripts run in a subprocess — normal export FOO=bar is lost when the subprocess exits. Writing to $CLAUDE_ENV_FILE persists the env var to the Claude Code session:

# FileChanged hook for .envrc → persist direnv env to Claude
direnv export bash >> "$CLAUDE_ENV_FILE"

Full examples and the common pitfalls are in references/path-substitution-patterns.md.

The scripts/ vs bin/ pattern

Both are valid patterns for shared executables.

scripts/: interpreted scripts called explicitly with their interpreter or with a #! shebang. Good for Python/Ruby/Bash tools.

${CLAUDE_PLUGIN_ROOT}/scripts/validate_plugin.py

bin/: pre-wrapped executables, often a thin shim that forwards to the interpreter. Good when users may want to invoke the tool outside of Claude Code (e.g. CLI usage).

${CLAUDE_PLUGIN_ROOT}/bin/plugin-cli validate

This plugin (plugin-dev) uses scripts/ because the scripts are intended for skill-internal use, not for direct user invocation.

Namespacing

Two plugins with the same component name collide. Namespace defensively:

• Skill names: prefix with the plugin's domain (plugin-dev-validation, not validation)
• Slash commands: same — /plugin-dev-scaffold not /scaffold
• Subagent names: same — plugin-dev-validator not validator
• Hook matchers: no namespacing needed — matchers filter by tool name, not plugin name
• MCP tools: prefix with the plugin name — plugin_dev_validate, not validate

Exception: single-skill plugins can use an unprefixed name if it's already distinctive (skill-foundry, plugin-dev). Multi-skill plugins should consider prefixing internally (plugin-dev/skills/plugin-hooks rather than plugin-dev/skills/hooks).

Hook merge semantics (when multiple plugins install)

When two plugins register hooks for the same event, they BOTH run. The order is not guaranteed — don't rely on it.

Precedence for decisions (from plugin-hooks SKILL.md):

deny > defer > ask > allow

A single deny decision stops the tool call. allow decisions are overridden by any non-allow from another hook.

Rule: write your hooks assuming other hooks also fire on the same event. Do not assume yours is the only one.

MCP auto-start lifecycle

If your plugin ships .mcp.json, the MCP server:

1. Is auto-started when the plugin is enabled
2. Is auto-restarted if it crashes
3. Is stopped when the plugin is disabled or uninstalled

Implications:

• Your server must be idempotent (restarting must not corrupt state)
• Store persistent state in $CLAUDE_PLUGIN_DATA so it survives restarts
• Don't assume exclusive access to resources — two users with the same plugin installed are running two separate server processes

How components integrate inside one plugin

The canonical integration pattern:

1. Skill description says "use when X" and references the MCP tool or hook behavior
2. Hook enforces automation or guardrails around the domain
3. MCP server exposes the concrete tools the skill's body instructs the model to call
4. Command provides a user-triggered entry point for the full workflow
5. All share ${CLAUDE_PLUGIN_ROOT}/scripts/ for any deterministic helper scripts

Example — a hypothetical linting-toolkit plugin:

• Skill lint-fixing — methodology for fixing lint errors (activates on "my code has errors")
• Hook PostToolUse on Edit|Write — runs linter in background, writes results to $CLAUDE_ENV_FILE
• Script scripts/run-linter.sh — shared by both the hook and (if the user asks explicitly) by the skill

All three reference ${CLAUDE_PLUGIN_ROOT}/scripts/run-linter.sh. They don't duplicate the script.

References

Plugin-Dev Authoring Toolkit by Viktor Bezdek — licensed under MIT.