What this unit solvesMost people follow the Quick Start, install a plugin, and consider it done — without being able to say what it installed, what capabilities it provides, or how to configure it fully. That is knowing the surface without knowing the substance. Since Claude Code v2.1, a plugin is “a unit that packages and distributes skills, agents, hooks, MCP/LSP configuration, and background monitors,” distributed through two public marketplaces (
claude-plugins-official and claude-community). This unit covers plugin directory structure, a post-install audit SOP, advanced configuration beyond the Quick Start, version management, and the security evaluation SOP you should run before picking up any plugin.Learning objectives
- Name the components a plugin packages (skills, agents, commands, hooks,
.mcp.json,.lsp.json, monitors,bin/,settings.json) and explain the role each plays in the system. - After installing a plugin, proactively inventory every skill, agent, command, hook, and MCP server it actually provides, rather than relying on what the Quick Start happens to mention.
- Perform complete configuration beyond the Quick Start: environment variables, conflict resolution with existing settings, model selection, and preloaded skills.
- Distinguish when to use each of the three install paths:
claude --plugin-dir(local development),--plugin-url(CI artifact),/plugin install(marketplace). - Apply the 03-1 evaluation framework and 03-3 security principles to decide whether to install a plugin, whether to keep it, and whether to restrict its hook or MCP permissions.
1. What a plugin is: a bundled capability set
A plugin is a directory containing a manifest and a set of components: skills, agents, commands, hooks, MCP server configuration, LSP server configuration, background monitors, and executables. It upgrades the “project-local scattered.claude/ configuration” into a distributable, versioned, cross-project-shareable unit (as of 2026-06, per the official plugins chapter [1]).
What actually happens when you install a plugin:
- Its component directories and files are registered in Claude Code’s load list.
- The
namefield inplugin.jsonadds a namespace prefix to all skills and commands (/plugin-name:skill-name). - The included MCP server and LSP server configurations are activated.
- Default values in
settings.jsonare applied (currently limited to theagentandsubagentStatusLinekeys) [1].
2. Plugins versus standalone .claude/ configuration
Claude Code supports two ways to add custom skills, agents, and hooks ([1]):
| Dimension | Standalone config (.claude/) | Plugin |
|---|---|---|
| Skill naming | /hello (short, no prefix) | /my-plugin:hello (namespaced) |
| Best for | Personal workflows, single-project customization, rapid experimentation | Cross-project sharing, team distribution, community marketplace, versioning |
| Distribution | Through version control (travels with the repo) | Through marketplace or git URL |
| Version management | Follows the repo | Explicit version field or git commit SHA |
| Hook configuration | Inside settings.json | hooks/hooks.json (separated from settings) |
| Install command | Edit files | /plugin install or claude --plugin-dir |
3. Directory structure
Complete plugin directory structure (as of 2026-06) [1]:my-plugin/
.claude-plugin/
plugin.json · required: manifest
skills/ · optional: Agent Skills
commands/ · optional: user-triggered commands
agents/ · optional: custom Subagents
hooks/ · optional: event handlers
.mcp.json · optional: MCP server configuration
.lsp.json · optional: LSP server configuration
monitors/ · optional: background monitors
bin/ · optional: executables added to PATH when the plugin is active
settings.json · optional: defaults applied when the plugin is activated
README.md · recommended: human-readable description
4. Manifest: .claude-plugin/plugin.json
Minimal manifest [1]:
| Field | Purpose |
|---|---|
name | Unique identifier; also the skill namespace prefix. The my-first-plugin in /my-first-plugin:hello comes from this value |
description | Displayed in the plugin manager so users can judge what the plugin does |
version | Optional. If set, users receive updates only when this field changes. If omitted, each commit is treated as a new version when distributing via git [1] |
author | Optional; author info (name, email) |
homepage | Optional; plugin homepage |
repository | Optional; source repo |
license | Optional; license terms |
5. How to place each component
5.1 Skills
Skills go as directories atskills/<name>/SKILL.md, identical to standalone configuration ([1]; see also 04-4 Skills):
my-plugin/
skills/
code-review/
SKILL.md
references/
description:
/reload-plugins after installing the plugin for it to load. Complete skill authoring guidelines are in 04-4 Skills.
5.2 Commands
Commands go as single files atcommands/<name>.md ([1]; see also 04-3 Commands):
my-plugin/
commands/
deploy.md
commands/ is the legacy form for pluginsThe official v2.1 documentation explicitly states “Use skills/ for new plugins” ([1]). New plugins should put imperative logic in skills/<name>/SKILL.md to gain directory-based structure, references/, scripts/, and progressive disclosure.5.3 Agents
Subagents go atagents/<name>.md, with the same frontmatter as standalone configuration (see 04-5 Subagents). Plugin Subagents have three restrictions ([1]): the hooks, mcpServers, and permissionMode frontmatter fields are ignored.
5.4 Hooks
Hook configuration goes inhooks/hooks.json, using the same format as the hooks block in settings.json ([1]):
jq to extract fields (examples in 04-6 Hooks).
5.5 MCP servers
.mcp.json uses the same schema as standalone configuration ([1]):
5.6 LSP servers
LSP (Language Server Protocol) servers give Claude real-time code intelligence ([1]). Example.lsp.json:
5.7 Monitors
Monitors let a plugin watch logs, files, and external state in the background and notify Claude when events occur ([1]).monitors/monitors.json:
command is treated as a notification sent to Claude. The full schema including when triggers and variable substitution is in [2].
5.8 bin/
Executables inbin/ are added to the Bash tool’s PATH when the plugin is activated [1]. Place things here carefully: every executable becomes a command callable at any time in your shell and can be triggered by any hook or agent.
5.9 Default settings
Thesettings.json at the plugin root applies defaults when the plugin is activated. Only two keys are currently supported ([1]): agent and subagentStatusLine.
agents/security-reviewer.md as the main session agent. Unknown keys are silently ignored.
6. Installation: four paths
Choose the install method that matches your use case:| Path | Command | Use |
|---|---|---|
| Local development | claude --plugin-dir ./my-plugin | Development, testing, debugging |
| Local ZIP | claude --plugin-dir ./my-plugin.zip | Same as above with a packaged version (v2.1.128+) [1] |
| URL CI artifact | claude --plugin-url https://example.com/my-plugin.zip | Load-testing a CI-produced plugin |
| Marketplace | /plugin install <name> | Install from claude-plugins-official or claude-community |
6.1 Local development mode
--plugin-dir loads a directory directly without an install step ([1]):
/reload-plugins to reload without restarting.
6.2 Installing from the marketplace
The marketplace is managed with the/plugin command. Install flow ([1]):
6.3 The two public marketplaces
Anthropic maintains two public marketplaces ([1]):claude-plugins-official: Anthropic-curated, hand-picked plugins. Available automatically with every Claude Code installation.claude-community: community-submitted, review-approved plugins. Users add it with/plugin marketplace add anthropics/claude-plugins-communityand install from@claude-community.
The difference between them
claude-plugins-official curation is entirely Anthropic’s decision; there is no application process, and the submission form does not place plugins there. claude-community goes through an automated pipeline: claude plugin validate automatic checks plus automated security screening. Once approved, the plugin is pinned to a specific commit SHA in the anthropics/claude-plugins-community repository; CI automatically bumps the pin when you push a new commit. The catalog syncs nightly, so there can be a 24-hour gap between approval and installability.Submission entry points: claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit.6.4 Private marketplaces (internal team distribution)
Teams can host a marketplace in a private repository accessible only to organization members. Detailed mechanics are in [2].7. Post-install audit SOP: do not stop at the Quick Start
30-minute audit workflowRun through these steps after installing any plugin. This is the gap between “installed and actually using it” and “installed and running only 20% of it.”
Read the manifest
Open
~/.claude/plugins/<plugin-name>/.claude-plugin/plugin.json and note the name, version, author, description, and homepage (if present).Confirm inside Claude Code
Run
/help and look for the plugin’s skills and commands (they will carry the namespace prefix). Run /agents and check whether the plugin’s agents appear in the Library. Ask Claude in conversation: “list the plugins enabled in the current session and the skills and MCP servers each provides.”Read every SKILL.md, agent.md, and hooks.json
Do not skip this. Spend 30 seconds scanning each file to understand what it does, when it triggers, whether it takes arguments, and whether it dynamically injects shell commands. For every
command in hooks.json, run the supply-chain scan in the next section.Record configuration override points
What does the plugin’s
settings.json write (currently only agent and subagentStatusLine)? Which environment variables do the plugin’s MCP servers need at startup (check the env field in .mcp.json)? Does your own settings.json have any settings the plugin would override (see [2] for plugin settings.json precedence rules)?lint-on-save hook that fires on PostToolUse: Write|Edit — which the Quick Start never mentioned.
8. Complete configuration: beyond the Quick Start
The Quick Start typically demonstrates only one or two happy paths. Advanced settings are often buried in the details.8.1 Environment variables and secrets
A plugin’s.mcp.json and monitors/monitors.json frequently reference environment variables (${GITHUB_TOKEN}, etc.). The Quick Start sets the minimum required set; you need to:
- Confirm those variables exist in your local or CI environment.
- Inject them through an environment variable management tool (1Password CLI,
.envwith direnv, a cloud secret manager) — do not hardcode them in plugin configuration files; plugins go into version control.
8.2 Name collisions between skills and commands
Plugin skills are always namespaced (/plugin-name:hello), but standalone configuration (.claude/commands/) same-named commands can still collide with a plugin’s commands/<name>.md. Precedence rules (as of 2026-06; full details in [2]):
- Standalone configuration takes priority (loaded first, matched first).
- Plugin commands are loaded after.
- When names collide, standalone configuration wins.
.claude/commands/deploy.md share a name with a plugin’s commands/deploy.md?
8.3 Hook execution order
When multiple hooks are triggered by the same event, execution order follows configuration position ([1]): hooks insettings.json run first, then the plugin’s hooks/hooks.json. If multiple plugins have PostToolUse hooks with the same matcher, all of them run in sequence. There is no debouncing or manual priority ordering. If your formatting hook and a plugin’s formatting hook both process the same file, you need to consolidate manually.
8.4 MCP server port collisions
If two plugins both try to start a server on the same port, the second one to start will fail. Check each plugin’s.mcp.json:
- Commands starting with
node,python, ornpxtypically let the server choose a port dynamically, so collisions are less common. - If a port is hardcoded (e.g.,
localhost:8080), change one of them to a different port manually.
8.5 Model selection
Some plugin Subagents inherit the main conversation model by default. For high-repetition workers (code formatters, test runners), changing the frontmatter tomodel: haiku can produce significant cost savings (see 04-5 Subagents).
8.6 Scaffolding with claude plugin init
claude plugin init my-tool scaffolds a plugin skeleton into ~/.claude/skills/my-tool/, including a .claude-plugin/plugin.json manifest and a starter SKILL.md. It is loaded automatically as my-tool@skills-dir in the next session without any marketplace step ([1]).
9. Version management
Two version modes for plugins ([1]):| Mode | Trigger | Behavior |
|---|---|---|
Explicit version | The field changes | Users receive updates only on a new version |
| Implicit (git SHA) | version omitted; distributed via git | Every commit is a new version |
- Production lock: freeze the
versionfield; bump only after reviewing the PR. - Dev tracking: omit
version; useclaude --plugin-dirpointing to a local directory. - Internal team distribution: private marketplace + git tag; CI bumps the version.
10. Migrating from standalone configuration to a plugin
If you already have.claude/commands/, agents/, and skills/, you can migrate them into a plugin ([1]):
11. Security and evaluation
A plugin is code you do not fully control entering your working environment. The risk surface:11.1 Supply chain evaluation
| Dimension | What to assess |
|---|---|
| Maintainer | Who is it? An individual or an organization? Community reputation? Commit activity history? |
| Update frequency | When was the last commit? If the plugin has not been updated in a year, test thoroughly before applying |
| Source | From claude-plugins-official, the reviewed claude-community, or a private git URL? Trust level varies enormously |
| Code review | Have you read the manifest and every SKILL.md, hooks.json, and .mcp.json? |
| Known vulnerabilities | Snyk ToxicSkills (2026-02) found that 36% of public skills contain prompt injection [needs source verification] |
11.2 Pre-install scan
Following the SOP from 04-6 Hooks, run this againsthooks/hooks.json and every SKILL.md:
11.3 Restricting plugin permissions
If you are not comfortable with a plugin’s hooks or MCP permissions after installing:- Disable all hooks: set
"disableAllHooks": trueinsettings.json(this also stops plugin hooks; managed-tier hooks are unaffected) [1]. - Deny a specific MCP server: add a rule to
permissions.denyinsettings.json. - Fork the plugin: copy the entire plugin to a local directory, remove the parts you are concerned about, rename
nameto<name>-local, and load it withclaude --plugin-dir.
11.4 Connecting to the 03-1 evaluation framework
Before installing a plugin, run the 03-1 evaluation framework:- Does this plugin address a real, high-frequency pain point in my workflow, or does it just look good in the Quick Start?
- Try it for a week: how many times per day do you actually invoke it? Does the time saved justify the supply-chain risk introduced?
- Is there a smaller, more trustworthy alternative (for example, extracting just one skill from the plugin and using it as standalone configuration)?
12. Tool comparison
Plugin and extension mechanisms differ significantly in naming and architecture across vendors (as of 2026-06):| Concept | Anthropic Claude (primary) | OpenAI Codex | Google Antigravity | GitHub Copilot CLI | Cursor (brief) |
|---|---|---|---|---|---|
| Extension unit | Plugin (manifest + skills/agents/hooks/mcp/lsp/monitors/bin/settings) | Codex extension (config.toml + extensions/<name>/) [needs source verification] | Antigravity extension (~/.gemini/antigravity/extensions/) [needs source verification] | Copilot Extensions (third-party apps on GitHub Marketplace) [needs source verification] | Cursor extensions (.cursor/extensions/) [needs source verification] |
| Namespace | Required (/plugin-name:hello) | Configuration-based | Configuration-based | No namespace | Configuration-based |
| Install method | claude --plugin-dir, /plugin install, marketplace | codex extension install [needs source verification] | Configuration-based | Marketplace UI | Configuration-based |
| List installed | /plugin command, filesystem scan | codex extension list [needs source verification] | Configuration-based | Configuration-based | Configuration-based |
| Configuration override points | settings.json (applied on activation), hooks/hooks.json, monitors/monitors.json | Configuration-based | Configuration-based | Configuration-based | Configuration-based |
| Security scanning | No built-in; manual rg scan | Configuration-based | Configuration-based | Configuration-based | Configuration-based |
| Public marketplace | claude-plugins-official (enabled by default) + claude-community (user-added) | (No unified public marketplace; needs verification) [needs source verification] | Configuration-based | GitHub Marketplace | Configuration-based |
| Version management | Explicit version or git commit SHA | Configuration-based | Configuration-based | Configuration-based | Configuration-based |
Naming clarificationClaude Code plugins and “Copilot Extensions” are different things: the former is a directory-based extension to the local CLI; the latter is a third-party app on GitHub Marketplace that typically integrates cloud services (issue trackers, CI platforms, cloud providers). This table compares like-for-like mechanisms only. The plugin and extension mechanisms of OpenAI Codex, Antigravity, and Cursor each differ in naming and architecture; entries marked “needs source verification” require confirmation. Cursor is a third-party IDE (Anysphere) and is mentioned here briefly for one column only.
13. Hands-on exercises
30-minute exercises
- Audit an existing plugin: run the
find/catSOP from this unit on your most-used plugin; list five components it actually provides (including ones the Quick Start omitted) and the trigger conditions for each. - Security scan: run the four
rgcommands against the same plugin; note every hit and manually review the surrounding context. - Local development test: create an empty plugin at
~/playground/my-test-plugin/usingclaude plugin init my-test-plugin, add one SKILL and one PostToolUse hook, load it withclaude --plugin-dir, and observe the namespace prefix and hook triggering behavior. - Fork a live plugin: copy a plugin you have installed from
~/.claude/plugins/to a local directory, remove the hooks block, renamenameto<original-name>-no-hooks, load it withclaude --plugin-dir, and verify the hooks do not run. - Pre-submission validation: if you have written a plugin and want to submit it to
claude-community, first runclaude plugin validateto pass the automated checks.
14. Common pitfalls
Self-check
The bar for passing this unit
- Can you name the nine component types a plugin packages (skills, commands, agents, hooks,
.mcp.json,.lsp.json, monitors,bin/,settings.json) and explain what each does? - Without looking at the Quick Start, can you list all components a plugin has installed, the purpose of each, and what it wrote into
settings.json— just from the plugin directory structure? - Can you distinguish when to use each of the three install paths:
claude --plugin-dir,--plugin-url, and/plugin install? - Before installing a new plugin, can you name at least three supply-chain evaluation questions and the corresponding scan commands?
- If a plugin conflicts with your existing
.claude/configuration, can you name at least two paths to investigate?
Sources and further reading
Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.-
[1] Anthropic, “Create plugins,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugins (as of 2026-06; covers directory structure, manifest schema, four install paths,
claude-plugins-officialandclaude-communitymarketplaces,--plugin-dirvs.--plugin-urldifference) - [2] Anthropic, “Plugins reference,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugins-reference (as of 2026-06; full schema, version management, private marketplace, three restricted Subagent frontmatter fields)
- [3] Anthropic, “Discover and install plugins,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/discover-plugins (as of 2026-06; marketplace browsing and install flow)
- [4] Anthropic, “Create and distribute a plugin marketplace,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/plugin-marketplaces (as of 2026-06; private marketplace and CI/CD integration)
-
[5] Anthropic, “Hooks,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/hooks (as of 2026-06; plugin
hooks/hooks.jsonuses the same schema as settings.json)
- Configuration layer model: 02-1 Configuration Layer Model.
- Skill authoring and progressive disclosure: 04-4 Skills.
- Subagent frontmatter: 04-5 Subagents.
- Hook trigger events and command handlers: 04-6 Hooks.
- MCP server configuration: 04-9 MCP Integration.
- Evaluation framework: 03-1 Evaluating Fit.
- Supply chain risk: 03-3 Security, Privacy, and Supply Chain Risk.