Plugin authoring
A plugin is a directory Claude Code loads as one unit: a manifest under .claude-plugin/, and the
component folders beside it. Everything below is checked against the Claude Code plugins docs on
2026-09-12 (the plugins guide, the plugins reference, the marketplaces page, the plugin evals
page). A claim marked community comes from field reports, not the docs - re-verify it through
The documentation server before relying on it. Anything version-coupled here (a minimum CLI version, a flag) is
re-checked the same way at the moment of use: the docs are the authority, this file is the map.
When this skill applies
- A
.claude-plugin/plugin.json or marketplace.json is being created or edited.
- A command, skill, agent, hook, MCP server or LSP server is being added to a plugin.
- A plugin is being published, versioned, installed for a test, or measured.
- A plugin's behaviour is being tested (
claude plugin eval) or its cost read (claude plugin details).
Not for a project's own .claude/ folder (skills, agents and hooks there load without a manifest)
and not for a single skill's body - that is the skills docs (code.claude.com/docs/en/skills), the same inside or
outside a plugin.
The manifest - .claude-plugin/plugin.json
name is the only required field. Kebab-case, unique within the marketplace, and it becomes the
namespace of every command, skill and agent the plugin ships (/<plugin>:<command>). The rest is
optional: version (semver), description, author (an OBJECT with name, plus optional email
and url), homepage, repository, license, keywords, and the component path fields
(commands, agents, skills, hooks, mcpServers, lspServers, outputStyles,
workflows, userConfig). Full schema, path semantics and the marketplace shape:
references/manifest-and-marketplace.md.
Four rules the schema does not shout about:
- A component path is relative to the plugin root and starts with
./. Nothing may reach
above the root with ../ - a plugin copied out of a marketplace clone loses whatever ../
pointed at, and validate rejects the shape.
- Path fields REPLACE the default folder for that component, except
skills, which ADDS.
Setting commands: ["./cmd"] means ./commands/ is no longer scanned; setting skills scans both,
unless the entry is sourced from the marketplace root, where the listed skill folders are the
whole set. Hooks, MCP and LSP servers merge by their own rules.
- The cache entry is the whole SOURCE, not the paths the entry lists. An entry sourced from a
repo ROOT caches that repo entire - every sibling folder, not just the subdir it serves as the
plugin (measured on a real install). That is free tooling if you mean it: a plugin whose
installer needs the repo's scripts reads them out of
<config>/plugins/cache/<marketplace>/<plugin>/<version>/ instead of downloading anything. It is
also the leak to watch - anything in that repo ships to every machine that installs the plugin.
version in plugin.json is authoritative, silently. A version in the marketplace entry is
ignored when plugin.json carries one - set it in ONE place and let the other inherit. An explicit
version also gates updates: a source change that does not bump the version is not delivered.
Only .claude-plugin/plugin.json lives inside .claude-plugin/; commands/, skills/,
agents/, hooks/ sit at the plugin ROOT. A CLAUDE.md at the plugin root is not loaded - the
plugin's standing instruction, if it needs one, is a skill or a hook.
Paths inside a plugin
${CLAUDE_PLUGIN_ROOT} - the plugin's install directory, used in hook commands, MCP command
/ args and LSP config. It changes on every update (the cache is versioned), so nothing durable
is written under it. Hard-coded absolute paths break for every other install.
${CLAUDE_PLUGIN_DATA} - the plugin's persistent data directory
(~/.claude/plugins/data/<plugin-id>/), the same across updates and across projects. State a
plugin owns (an index, a cache, a preference the user set through it) goes here, never into the
project tree and never into ${CLAUDE_PLUGIN_ROOT}.
${CLAUDE_PROJECT_DIR} - the project the session runs in; hooks read and write project files
through it. Any other value a plugin needs at runtime comes from userConfig, whose
sensitive: true entries land in secure storage and reach the process as environment variables,
or from the session's own environment.
- Plugin MCP tools arrive as
mcp__plugin_<plugin>_<server>__<tool>; plugin skills as
<plugin>:<skill>. Name them that way in any body that routes to them.
Loading and precedence
A plugin loads at session start; /reload-plugins re-reads skills, agents, hooks and plugin MCP / LSP config without a restart. claude --plugin-dir <path> loads a local plugin for one session and OVERRIDES an installed plugin of the same name - that is the test route. The rest (what overrides what, what a plugin agent may not declare, which settings.json keys a plugin honours) is under 'Loading and precedence' in references/manifest-and-marketplace.md; read it before wiring a component.
Distribution and versioning
- A marketplace is a git repo (or a URL) carrying
.claude-plugin/marketplace.json: name,
owner.name, and plugins[] with name + source each. Source kinds and the reserved
marketplace names are in the reference. metadata.pluginRoot (2.1.239+) sets a common
base directory; renames is append-only, null marking a removed plugin.
- Pinning:
sha beats ref in a git source. A marketplace submitted to the official catalog is
pinned to a commit and re-synced nightly, so a fix ships when the pin moves, not when you push.
- Auto-update is ON by default for the official Anthropic marketplaces and OFF for third-party and
local ones (a user toggles it per marketplace; an admin sets
autoUpdate: true on a managed
extraKnownMarketplaces entry). So a plugin you distribute yourself reaches its users on THEIR
claude plugin update, and an updater the plugin ships is what makes that reliable.
- Managed settings can restrict what installs:
strictKnownMarketplaces, blockedMarketplaces,
disableCommandPluginSources, allowManagedHooksOnly, disableSideloadFlags. A plugin that
needs a command source or side-loading may be blocked in an enterprise install - say so in
its README.
bin/ under the plugin root is added to the Bash PATH for the session; it is not allowed for
plugins distributed through a claude.ai organization.
- Node dependencies install automatically only with a
package.json plus a supported lockfile
(package-lock.json; yarn.lock / pnpm-lock.yaml are skipped), always with
--ignore-scripts. A plugin that needs a post-install script has no supported way to run it.
- Bump the version on every user-visible change, in the ONE place that owns it. A release tag
named
v<version> from that field keeps the tag, the manifest and the marketplace listing equal
by construction, and a lint that reads both files catches the drift a human edit introduces.
Per-component rules
- Commands (
commands/<name>.md, listed as /<plugin>:<name>): one job, imperative body,
arguments through $ARGUMENTS. allowed-tools is a per-turn PERMISSION pre-approval, not a
restriction and not a context saving - it covers the turn the command runs in and nothing after,
so a multi-turn walk gains nothing from it. Commands and skills are both listed as slash entries;
the difference that matters is DISPLAY: a plugin command lists namespaced-only, a plugin skill
named exactly like the plugin lists bare (/<plugin>) - choose by what the user should see.
- Skills (
skills/<name>/SKILL.md): read the skills docs (code.claude.com/docs/en/skills) before the first write.
- Agents (
agents/<name>.md): a tools: allowlist of tools that exist (a whole MCP server is one
mcp__<server> entry, listed as written; disallowedTools is never listed), a model / effort pin
with the measurement that justifies it, and no hooks / mcpServers / permissionMode.
- Hooks (
hooks/hooks.json): a command hook without timeout gets Claude Code's 600s
default - one stalled child freezes the session for ten minutes, so every entry carries a short
timeout (the house value is 10s; a hook runs in ~25ms, almost all of it the runtime spawn).
Paths go through ${CLAUDE_PLUGIN_ROOT}. A hook is a deterministic gate at a discrete event;
advice belongs in a skill. A UserPromptSubmit denial erases the user's prompt, so that event
injects and never denies.
- MCP servers (
.mcp.json at the plugin root, or mcpServers in the manifest): a registered
server re-injects its tool schemas into every session, so ship one only where the plugin's whole
purpose needs it, and prefer a runtime the user already has. Credentials come from userConfig
sensitive entries or the account settings env, never from a literal in the config.
- LSP servers (
lspServers): the binary is the user's to install; the config names the command
and the file extensions, and a missing binary fails at launch, so the README says what to install.
Verify before publishing
Run these in this order; each is cheap and each catches a class the previous one cannot.
claude plugin validate <plugin-dir> --strict - schema, paths, frontmatter; --strict turns
warnings into failures. Run it on the marketplace root too when one exists.
claude --plugin-dir <plugin-dir> in a scratch project, then /reload-plugins after each edit.
Check the slash list shows the entries you meant (namespaced commands, bare or namespaced
skills) and nothing you did not.
claude plugin details <plugin>@<marketplace> for the installed copy, or
claude --plugin-dir <plugin-dir> plugin details <plugin> for the working tree (a bare path is
not accepted) - the always-on and on-invoke token cost. The inventory lists skills, agents, hooks,
MCP and LSP servers; COMMANDS are not in it, and neither is an agent LISTED by file in an
agents array - it reads Agents (0) and leaves those descriptions out of the always-on number,
yet every such seat registers (measured 2026-09-22: 42 of 42 listed seats in a real session's
init list; the same three seats read Agents (0), ~456 tok listed and Agents (3), ~828 tok
from a default agents/ folder). So a plugin that lists its agents pays their descriptions ON
TOP of the number. The estimate also ignores disable-model-invocation
(the skills docs say such a description is NOT in context, yet a user-only skill still shows an
always-on number - measured on a user-only router skill: ~210 tok reported, 0 loaded). Read the
number as the cost of every description the MODEL can see. The always-on number is what every session pays before
the first message; a description that grows by a paragraph is costed here, never assumed free.
claude plugin eval <plugin-dir> (Claude Code 2.1.269+) - behavioural cases under evals/,
each run with and without the plugin. The command shapes, the case layout and how to read the
with / without delta: references/evals.md. A tool_used: Skill grader that fails on natural
phrasing sends you to the description rules in the skills docs. A plugin with NO
model-invocable component is still evaluable, and 'nothing here is model-invocable' is not a
reason to skip this step: a case's prompt.md is a USER turn, which is exactly how a disable-model-invocation
command is invoked, so a read-only walk makes a valid case whose without-arm cannot resolve the
command at all - a clean delta. Reach for a named substitute only where every walk MUTATES a real
install, and say so.
- The security pass -
references/security-and-governance.md - before the first publish and
after any change to hooks, MCP config or dependencies.
A behaviour claim ('the plugin makes X cheaper', 'it still catches Y') ships with the eval delta
or a measured token number, never asserted.
1---2name: plugin-authoring3description: Use when creating or changing a Claude Code plugin - a `.claude-plugin/plugin.json` manifest, a `marketplace.json`, plugin commands / skills / agents / hooks / MCP or LSP config, `${CLAUDE_PLUGIN_ROOT}` paths - or when publishing, versioning or testing one (`claude plugin validate`, `--plugin-dir`, `claude plugin eval`). Covers manifest schema, layout and precedence, distribution, versioning, per-component rules, verification and the security review. Not for a project's own `.claude/` folder, and not for authoring one skill's body.4metadata:5 source: https://skillmd.com/skills/envoydev/plugin-authoring6---78# Plugin authoring910A plugin is a directory Claude Code loads as one unit: a manifest under `.claude-plugin/`, and the11component folders beside it. Everything below is checked against the Claude Code plugins docs on122026-09-12 (the plugins guide, the plugins reference, the marketplaces page, the plugin evals13page). A claim marked `community` comes from field reports, not the docs - re-verify it through14The documentation server before relying on it. Anything version-coupled here (a minimum CLI version, a flag) is15re-checked the same way at the moment of use: the docs are the authority, this file is the map.1617## When this skill applies1819- A `.claude-plugin/plugin.json` or `marketplace.json` is being created or edited.20- A command, skill, agent, hook, MCP server or LSP server is being added to a plugin.21- A plugin is being published, versioned, installed for a test, or measured.22- A plugin's behaviour is being tested (`claude plugin eval`) or its cost read (`claude plugin details`).2324Not for a project's own `.claude/` folder (skills, agents and hooks there load without a manifest)25and not for a single skill's body - that is the skills docs (code.claude.com/docs/en/skills), the same inside or26outside a plugin.2728## The manifest - `.claude-plugin/plugin.json`2930`name` is the only required field. Kebab-case, unique within the marketplace, and it becomes the31namespace of every command, skill and agent the plugin ships (`/<plugin>:<command>`). The rest is32optional: `version` (semver), `description`, `author` (an OBJECT with `name`, plus optional `email`33and `url`), `homepage`, `repository`, `license`, `keywords`, and the component path fields34(`commands`, `agents`, `skills`, `hooks`, `mcpServers`, `lspServers`, `outputStyles`,35`workflows`, `userConfig`). Full schema, path semantics and the marketplace shape:36`references/manifest-and-marketplace.md`.3738Four rules the schema does not shout about:3940- **A component path is relative to the plugin root and starts with `./`.** Nothing may reach41 above the root with `../` - a plugin copied out of a marketplace clone loses whatever `../`42 pointed at, and validate rejects the shape.43- **Path fields REPLACE the default folder for that component, except `skills`, which ADDS.**44 Setting `commands: ["./cmd"]` means `./commands/` is no longer scanned; setting `skills` scans both,45 unless the entry is sourced from the marketplace root, where the listed skill folders are the46 whole set. Hooks, MCP and LSP servers merge by their own rules.47- **The cache entry is the whole SOURCE, not the paths the entry lists.** An entry sourced from a48 repo ROOT caches that repo entire - every sibling folder, not just the subdir it serves as the49 plugin (measured on a real install). That is free tooling if you mean it: a plugin whose50 installer needs the repo's scripts reads them out of51 `<config>/plugins/cache/<marketplace>/<plugin>/<version>/` instead of downloading anything. It is52 also the leak to watch - anything in that repo ships to every machine that installs the plugin.53- **`version` in plugin.json is authoritative, silently.** A version in the marketplace entry is54 ignored when plugin.json carries one - set it in ONE place and let the other inherit. An explicit55 version also gates updates: a source change that does not bump the version is not delivered.5657Only `.claude-plugin/plugin.json` lives inside `.claude-plugin/`; `commands/`, `skills/`,58`agents/`, `hooks/` sit at the plugin ROOT. A `CLAUDE.md` at the plugin root is not loaded - the59plugin's standing instruction, if it needs one, is a skill or a hook.6061## Paths inside a plugin6263- `${CLAUDE_PLUGIN_ROOT}` - the plugin's install directory, used in hook commands, MCP `command`64 / `args` and LSP config. It changes on every update (the cache is versioned), so nothing durable65 is written under it. Hard-coded absolute paths break for every other install.66- `${CLAUDE_PLUGIN_DATA}` - the plugin's persistent data directory67 (`~/.claude/plugins/data/<plugin-id>/`), the same across updates and across projects. State a68 plugin owns (an index, a cache, a preference the user set through it) goes here, never into the69 project tree and never into `${CLAUDE_PLUGIN_ROOT}`.70- `${CLAUDE_PROJECT_DIR}` - the project the session runs in; hooks read and write project files71 through it. Any other value a plugin needs at runtime comes from `userConfig`, whose72 `sensitive: true` entries land in secure storage and reach the process as environment variables,73 or from the session's own environment.74- Plugin MCP tools arrive as `mcp__plugin_<plugin>_<server>__<tool>`; plugin skills as75 `<plugin>:<skill>`. Name them that way in any body that routes to them.7677## Loading and precedence7879A plugin loads at session start; `/reload-plugins` re-reads skills, agents, hooks and plugin MCP / LSP config without a restart. `claude --plugin-dir <path>` loads a local plugin for one session and OVERRIDES an installed plugin of the same name - that is the test route. The rest (what overrides what, what a plugin agent may not declare, which `settings.json` keys a plugin honours) is under 'Loading and precedence' in `references/manifest-and-marketplace.md`; read it before wiring a component.8081## Distribution and versioning8283- A marketplace is a git repo (or a URL) carrying `.claude-plugin/marketplace.json`: `name`,84 `owner.name`, and `plugins[]` with `name` + `source` each. Source kinds and the reserved85 marketplace names are in the reference. `metadata.pluginRoot` (2.1.239+) sets a common86 base directory; `renames` is append-only, `null` marking a removed plugin.87- Pinning: `sha` beats `ref` in a git source. A marketplace submitted to the official catalog is88 pinned to a commit and re-synced nightly, so a fix ships when the pin moves, not when you push.89- Auto-update is ON by default for the official Anthropic marketplaces and OFF for third-party and90 local ones (a user toggles it per marketplace; an admin sets `autoUpdate: true` on a managed91 `extraKnownMarketplaces` entry). So a plugin you distribute yourself reaches its users on THEIR92 `claude plugin update`, and an updater the plugin ships is what makes that reliable.93- Managed settings can restrict what installs: `strictKnownMarketplaces`, `blockedMarketplaces`,94 `disableCommandPluginSources`, `allowManagedHooksOnly`, `disableSideloadFlags`. A plugin that95 needs a `command` source or side-loading may be blocked in an enterprise install - say so in96 its README.97- `bin/` under the plugin root is added to the Bash PATH for the session; it is not allowed for98 plugins distributed through a claude.ai organization.99- Node dependencies install automatically only with a `package.json` plus a supported lockfile100 (`package-lock.json`; `yarn.lock` / `pnpm-lock.yaml` are skipped), always with101 `--ignore-scripts`. A plugin that needs a post-install script has no supported way to run it.102- Bump the version on every user-visible change, in the ONE place that owns it. A release tag103 named `v<version>` from that field keeps the tag, the manifest and the marketplace listing equal104 by construction, and a lint that reads both files catches the drift a human edit introduces.105106## Per-component rules107108- **Commands** (`commands/<name>.md`, listed as `/<plugin>:<name>`): one job, imperative body,109 arguments through `$ARGUMENTS`. `allowed-tools` is a per-turn PERMISSION pre-approval, not a110 restriction and not a context saving - it covers the turn the command runs in and nothing after,111 so a multi-turn walk gains nothing from it. Commands and skills are both listed as slash entries;112 the difference that matters is DISPLAY: a plugin command lists namespaced-only, a plugin skill113 named exactly like the plugin lists bare (`/<plugin>`) - choose by what the user should see.114- **Skills** (`skills/<name>/SKILL.md`): read the skills docs (code.claude.com/docs/en/skills) before the first write.115- **Agents** (`agents/<name>.md`): a `tools:` allowlist of tools that exist (a whole MCP server is one116 `mcp__<server>` entry, listed as written; `disallowedTools` is never listed), a model / effort pin117 with the measurement that justifies it, and no `hooks` / `mcpServers` / `permissionMode`.118- **Hooks** (`hooks/hooks.json`): a `command` hook without `timeout` gets Claude Code's 600s119 default - one stalled child freezes the session for ten minutes, so every entry carries a short120 timeout (the house value is 10s; a hook runs in ~25ms, almost all of it the runtime spawn).121 Paths go through `${CLAUDE_PLUGIN_ROOT}`. A hook is a deterministic gate at a discrete event;122 advice belongs in a skill. A `UserPromptSubmit` denial erases the user's prompt, so that event123 injects and never denies.124- **MCP servers** (`.mcp.json` at the plugin root, or `mcpServers` in the manifest): a registered125 server re-injects its tool schemas into every session, so ship one only where the plugin's whole126 purpose needs it, and prefer a runtime the user already has. Credentials come from `userConfig`127 `sensitive` entries or the account settings `env`, never from a literal in the config.128- **LSP servers** (`lspServers`): the binary is the user's to install; the config names the command129 and the file extensions, and a missing binary fails at launch, so the README says what to install.130131## Verify before publishing132133Run these in this order; each is cheap and each catches a class the previous one cannot.1341351. `claude plugin validate <plugin-dir> --strict` - schema, paths, frontmatter; `--strict` turns136 warnings into failures. Run it on the marketplace root too when one exists.1372. `claude --plugin-dir <plugin-dir>` in a scratch project, then `/reload-plugins` after each edit.138 Check the slash list shows the entries you meant (namespaced commands, bare or namespaced139 skills) and nothing you did not.1403. `claude plugin details <plugin>@<marketplace>` for the installed copy, or141 `claude --plugin-dir <plugin-dir> plugin details <plugin>` for the working tree (a bare path is142 not accepted) - the always-on and on-invoke token cost. The inventory lists skills, agents, hooks,143 MCP and LSP servers; COMMANDS are not in it, and neither is an agent LISTED by file in an144 `agents` array - it reads `Agents (0)` and leaves those descriptions out of the always-on number,145 yet every such seat registers (measured 2026-09-22: 42 of 42 listed seats in a real session's146 init list; the same three seats read `Agents (0)`, ~456 tok listed and `Agents (3)`, ~828 tok147 from a default `agents/` folder). So a plugin that lists its agents pays their descriptions ON148 TOP of the number. The estimate also ignores `disable-model-invocation`149 (the skills docs say such a description is NOT in context, yet a user-only skill still shows an150 always-on number - measured on a user-only router skill: ~210 tok reported, 0 loaded). Read the151 number as the cost of every description the MODEL can see. The always-on number is what every session pays before152 the first message; a description that grows by a paragraph is costed here, never assumed free.1534. `claude plugin eval <plugin-dir>` (Claude Code 2.1.269+) - behavioural cases under `evals/`,154 each run with and without the plugin. The command shapes, the case layout and how to read the155 with / without delta: `references/evals.md`. A `tool_used: Skill` grader that fails on natural156 phrasing sends you to the description rules in the skills docs. A plugin with NO157 model-invocable component is still evaluable, and 'nothing here is model-invocable' is not a158 reason to skip this step: a case's `prompt.md` is a USER turn, which is exactly how a `disable-model-invocation`159 command is invoked, so a read-only walk makes a valid case whose without-arm cannot resolve the160 command at all - a clean delta. Reach for a named substitute only where every walk MUTATES a real161 install, and say so.1625. The security pass - `references/security-and-governance.md` - before the first publish and163 after any change to hooks, MCP config or dependencies.164165A behaviour claim ('the plugin makes X cheaper', 'it still catches Y') ships with the eval delta166or a measured token number, never asserted.