Plugins — One Install, Whole Workflow

// .claude-plugin/plugin.json — the manifest
{
  "name": "my-first-plugin",
  "description": "A greeting plugin",
  "version": "1.0.0",
  "author": { "name": "Your Name" },
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "license": "MIT"
}

Plus optional top-level dirs: templates/, scripts/, docs/, tests/, and themes/ (ship custom Claude Code themes, v2.1.118+).

Spaced invocation (v2.1.136+): /myplugin review resolves to the canonical /myplugin:review. Either form works; the colon form is recommended in scripts.

.lsp.json — Language Server Protocol

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Once configured: instant diagnostics after edits, go-to-definition / find references, hover types, symbol listing. Optional fields tune transport, env, timeouts, and restartOnCrash. Official marketplace ships pyright-lsp, typescript-lsp, rust-lsp pre-configured.

bin/ — executables on the session PATH

my-plugin/
├── plugin.json
└── bin/
    └── my-tool   # chmod +x

# with the plugin enabled:
$ my-tool --help

While the plugin is enabled, bin/ is prepended to PATH — hooks, skills, and commands in the same plugin can shell out to its helpers by bare name. Mark files executable in the repo; git preserves the bit.

pr-review/
├── .claude-plugin/plugin.json
├── commands/
│   ├── review-pr.md
│   ├── check-security.md
│   └── check-tests.md
├── agents/
│   ├── security-reviewer.md
│   ├── test-checker.md
│   └── performance-analyzer.md
├── mcp/github-config.json
└── hooks/pre-review.js

Each agent is ~10 lines of frontmatter + focus areas; the GitHub MCP config reads ${GITHUB_TOKEN} from the environment — never hardcoded.

What /review-pr actually runs

• pre-review.js hook validates you're in a git repo, warns on uncommitted changes
• GitHub MCP fetches the PR data
• security-reviewer, test-checker, performance-analyzer each analyze their slice
• Findings synthesized: ✅ security clean · ⚠️ coverage 65%, recommend 80%+ · ✅ no perf impact · 📝 12 recommendations

// .claude-plugin/marketplace.json
{
  "name": "my-team-plugins",
  "owner": "my-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "version": "1.2.0"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github",
        "repo": "my-org/deploy-helper",
        "ref": "v2.0.0" }
    }
  ]
}

• The official Anthropic-managed directory is anthropics/claude-plugins-official; enterprise admins can run private marketplaces for internal distribution
• Required fields: name, owner, plugins[] with name + source each — description, version, author are optional
• Strict mode: strict: true (default) — the local plugin.json is authoritative and the marketplace entry supplements it; strict: false — the marketplace entry is the entire plugin definition

Getting your marketplace to users

# GitHub (recommended)
/plugin marketplace add owner/repo-name

# other git services — full URL
/plugin marketplace add \
  https://gitlab.com/org/marketplace-repo.git

Private repositories work via git credential helpers or environment tokens — users need read access. Official-marketplace submissions go through claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit.

The publishing path

• Build the structure + plugin.json, write a README documenting components and requirements
• Test locally with claude --plugin-dir ./my-plugin
• Cut the release with claude plugin tag v0.3.0 (v2.1.118+) — validates the version format and creates the matching git tag
• Submit → review → approval → published; users install with one command

Dependency enforcement (v2.1.143)

• plugin disable refuses if another enabled plugin still depends on the target — the dependency graph can't be broken
• plugin enable force-enables transitive dependencies after a single confirmation prompt
• In-session equivalents exist too: /plugin list, /plugin info, /plugin install ./local-path, /plugin install github:username/repo

# load one or many local plugins
claude --plugin-dir ./my-plugin
claude --plugin-dir ./a --plugin-dir ./b

# .zip archives work too (v2.1.128+)
claude --plugin-dir ./my-plugin.zip

# fetch a .zip from a URL (v2.1.129+)
claude --plugin-url \
  https://example.com/releases/my-plugin-0.3.0.zip

# after editing plugin files mid-session
/reload-plugins

The test checklist

• All slash commands available · subagents function · MCP servers connect · hooks execute · LSP configs load · no config errors
• /reload-plugins re-reads all manifests, commands, agents, skills, hooks, and MCP/LSP configs — plugins also support change auto-detection
• First diagnostics when something won't load: plugin.json paths match the actual directory layout · scripts are chmod +x · JSON validates · /plugin debug name shows the logs

When auto-update runs it: 1) refreshes the marketplace catalog, 2) updates installed plugins to latest, 3) shows a notification prompting /reload-plugins.

Managed settings (org-level)

Enforced on every lifecycle event since v2.1.117 — install, update, refresh, and autoupdate, not just at first add. Managed settings take precedence over user-level settings.

The plugin-subagent sandbox

• Plugin subagents run restricted — three frontmatter keys are banned in their definitions:
• hooks — can't register event handlers
• mcpServers — can't configure MCP servers
• permissionMode — can't override the permission model

So a plugin can't escalate privileges or modify the host environment beyond its declared scope — what you saw in the manifest is what it gets.