plugins-management

Plugins Manager

Manage plugins across coding agents: create, validate, publish, delete, and submit to official directories or npm.

Supported agents:

• Claude Code: .claude-plugin/plugin.json-based plugins, distributed via marketplaces
• OpenCode: TypeScript/JavaScript plugins in .opencode/plugins/ or npm packages listed in opencode.json

CRITICAL: Before performing any deletion, uninstall, or removal operation, you MUST use the AskUserQuestion tool to confirm with the user. Never delete/uninstall plugins or remove marketplaces without explicit user confirmation.

Quick Reference

Task	Command/Script
Create plugin	python scripts/init_plugin.py <name>
Create marketplace	python scripts/init_marketplace.py <name>
Validate plugin	python scripts/validate_plugin.py <path>
Validate marketplace	claude plugin validate <path>
Prepare submission	python scripts/prepare_submission.py <path> --email X --company-url Y
Install plugin	/plugin install <name>@<marketplace>
Delete plugin	/plugin uninstall <name>@<marketplace>
Test plugin (dev)	claude --plugin-dir ./my-plugin
Reload after edits	/reload-plugins
Cut release tag	claude plugin tag --push
List installed	claude plugin list [--json] [--available]
Update plugin	claude plugin update <name>@<marketplace>

Workflows

1. Create a New Plugin

# Basic plugin with commands
python scripts/init_plugin.py my-plugin --path ./

# Full plugin with all components
python scripts/init_plugin.py my-plugin --path ./ --all

# Specific components
python scripts/init_plugin.py my-plugin --with-agents --with-skills

Flags:

• --with-commands (default): Include commands directory
• --with-agents: Include agents directory
• --with-skills: Include skills directory
• --with-hooks: Include hooks configuration
• --with-mcp: Include MCP server configuration
• --all: Include all components
• --author "Name": Set author name

After creation:

1. Edit .claude-plugin/plugin.json with plugin details
2. Add commands to commands/*.md with YAML frontmatter
3. Add agents to agents/*.md if needed
4. Update README.md with documentation

2. Create a Marketplace

# Empty marketplace
python scripts/init_marketplace.py my-marketplace --path ./

# With initial plugin
python scripts/init_marketplace.py my-marketplace --with-plugin my-plugin

After creation:

1. Edit .claude-plugin/marketplace.json
2. Add plugins to plugins/ directory
3. Push to GitHub: git push origin main

Users install with:

/plugin marketplace add username/my-marketplace

Marketplace references:

• Required file: .claude-plugin/marketplace.json
• Plugin entries must have name that matches each plugin's plugin.json name
• Use relative paths in source (e.g., ./plugins/my-plugin), not absolute paths
• Use ${CLAUDE_PLUGIN_ROOT} inside hooks and MCP configs referenced by marketplace plugins

3. Validate a Plugin

python scripts/validate_plugin.py ./my-plugin

Validates:

• plugin.json required fields (name, description, version, author)
• Semantic versioning format
• Command/agent frontmatter
• Hooks and MCP configuration
• README.md and LICENSE presence

Also consider:

• claude plugin validate <path> for marketplace JSON validation

4. Publish a Plugin

To GitHub:

cd my-marketplace
git init
git add .
git commit -m "Initial release"
git remote add origin https://github.com/user/my-marketplace.git
git push -u origin main

# Tag release
git tag -a v1.0.0 -m "Version 1.0.0"
git push origin v1.0.0

Distribution methods:

• GitHub: /plugin marketplace add user/repo
• GitLab: /plugin marketplace add https://gitlab.com/user/repo.git
• URL: /plugin marketplace add https://example.com/marketplace.json

5. Delete/Uninstall Plugins

⚠️ ALWAYS confirm with user before deleting/uninstalling. Use AskUserQuestion to ask: "Are you sure you want to uninstall '[plugin-name]'? This action cannot be undone."

# Uninstall from Claude Code
/plugin uninstall plugin-name@marketplace-name

# Remove marketplace (confirm with user first!)
/plugin marketplace remove marketplace-name

To delete source files: First confirm with user via AskUserQuestion, then remove the plugin directory from the marketplace's plugins/ folder and update marketplace.json.

6. Submit to Anthropic's Official Directory

The submission script automatically gathers all required form fields using gh CLI and git.

Prerequisites:

1. Plugin pushed to GitHub
2. gh CLI installed and authenticated
3. All validation checks pass

Prepare submission:

# Basic - gathers repo URL and SHA automatically
python scripts/prepare_submission.py ./my-plugin

# With required contact info
python scripts/prepare_submission.py ./my-plugin \
  --email [email protected] \
  --company-url https://yourcompany.com

# Copy SHA to clipboard
python scripts/prepare_submission.py ./my-plugin --copy-sha

# Save to JSON file
python scripts/prepare_submission.py ./my-plugin --output submission.json

# Open form in browser
python scripts/prepare_submission.py ./my-plugin --open-form

Form fields gathered automatically:

Field	Source
Link to Plugin	gh repo view --json url
Full SHA	git rev-parse HEAD
Plugin Homepage	plugin.json homepage or repo URL
Plugin Name	plugin.json name
Plugin Description	plugin.json description (50-100 words)

Fields you must provide:

• --email: Primary contact email
• --company-url: Company/Organization URL

Submission requirements:

• Plugin must be pushed to GitHub
• Working directory should be clean (no uncommitted changes)
• Description should be 50-100 words
• README.md and LICENSE files present
• No secrets/API keys in code

Plugin Structure Reference

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Optional manifest (auto-discovered if absent)
├── skills/               # Agent skills (preferred over commands/)
│   └── */SKILL.md
├── commands/             # Skills as flat .md files
│   └── *.md
├── agents/               # AI subagents
│   └── *.md
├── output-styles/        # Output style definitions (2026)
├── themes/               # Color themes (2026)
├── monitors/             # Background monitors (2026, v2.1.105+)
│   └── monitors.json
├── hooks/
│   └── hooks.json        # Event handlers
├── bin/                  # Executables added to PATH (2026)
├── settings.json         # Default agent / subagentStatusLine (2026)
├── .mcp.json             # MCP servers
├── .lsp.json             # LSP server config (since v2.0.74)
├── package.json          # Auto-installed dependencies (2026)
├── README.md             # Documentation
├── CHANGELOG.md
└── LICENSE

For detailed reference: See references/plugin-guide.md

OpenCode Plugins

OpenCode (anomalyco/opencode v1.14.x) plugins are TypeScript/JavaScript modules — fundamentally different from Claude Code plugins.

Quick reference

Task	Approach
Create local plugin	Drop .ts file in .opencode/plugins/ (project) or ~/.config/opencode/plugins/ (global)
Author npm plugin	npm init, add keywords: ["opencode-plugin"], depend on @opencode-ai/plugin
Install npm plugin	Add package name to opencode.json → "plugin": [...]; restart
Distribute	Publish to npm (no central marketplace)

Minimal plugin

// .opencode/plugins/env-protection.ts
import type { Plugin } from "@opencode-ai/plugin"

export default (async () => ({
  tool: {
    execute: {
      before: async (input, output) => {
        if (output.args.filePath?.includes(".env")) {
          throw new Error("Reading .env is forbidden")
        }
      },
    },
  },
})) satisfies Plugin

Register npm plugins

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "@my-org/custom-plugin"
  ]
}

OpenCode runs bun install at startup. Cached at ~/.cache/opencode/node_modules/.

What plugins can do

• Add custom tools the AI can call (Zod-validated args)
• Intercept/block tool calls (tool.execute.before throws to block)
• Subscribe to ~25 lifecycle events (session.idle, file.edited, permission.asked, ...)
• Register custom slash commands and auth providers
• Transform messages or system prompts during context compaction (experimental)

Critical caveats (v1.14.x)

• tool.execute.* hooks do not fire for MCP tool calls — use the permission block in opencode.json
• No central marketplace — distribute via npm and aggregators like awesome-opencode
• Plugins run in-process with full SDK access — audit third-party code before installing

See references/opencode-plugins.md for the full OpenCode plugin reference.

Critical Rules (Avoid Silent Failures)

• Keep skills/, commands/, agents/, hooks/, monitors/, themes/, output-styles/, bin/ at the plugin root (never inside .claude-plugin/).
• Do not add standard component paths to plugin.json. Only specify non-standard paths starting with ./.
• Use ${CLAUDE_PLUGIN_ROOT} (cache path, changes per version) and ${CLAUDE_PLUGIN_DATA} (persistent across updates) in hooks and MCP/LSP/monitor config paths. Relative paths break after install.
• Ensure hook scripts are executable (chmod +x scripts/*).
• Marketplace plugins[].name must match the plugin's plugin.json name.
• Path traversal limit (2026): plugins cannot reference files outside their directory; use symlinks inside the plugin if needed.
• Versioning (2026): omit version to use git SHA (every commit is a new version). Set version and bump for stable releases. Use claude plugin tag to cut release tags.

Common Patterns

Command File Format

---
description: What this command does
---

# Command Name

Instructions for Claude when command is invoked.

Agent File Format

---
description: Agent specialty and purpose
---

# Agent Name

Detailed instructions and expertise.

Hooks Configuration

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  }
}

MCP Server Configuration

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["./servers/server.js"]
    }
  }
}

Skill File Format

---
name: my-skill
description: What this skill does and when to use it
---

# Skill Title

Instructions for Claude when this skill is invoked.

Marketplace Entry Example

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "Short description",
  "version": "1.0.0",
  "author": { "name": "Author Name" },
  "category": "productivity",
  "keywords": ["tag1", "tag2"],
  "strict": true
}