Plugin Development

name plugin-development description Comprehensive guide for creating, modifying, testing, releasing, and maintaining Claude Code plugins. Use when creating a plugin, defining plugin structure, writing plugin.json manifests, publishing to marketplaces, installing plugins, setting up plugin directories, distributing plugins to teams, migrating standalone configurations to plugin format, or working with plugin components like skills, agents, hooks, MCP servers, and LSP servers. Trigger phrases: "create a plugin", "plugin structure", "plugin.json", "marketplace", "install plugin", "plugin directory", "distribute plugin", "plugin manifest", "plugin marketplace", "migrate to plugin", "plugin components", "LSP plugin". Plugin Development Guide Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. A plugin is a self-contained directory containing a manifest file ( plugin.json ) and one or more components: skills, commands, agents, hooks, MCP server configs, and LSP server configs. Plugins use namespaced skill names (like /my-plugin:hello ) to prevent conflicts when multiple plugins define skills with the same name. They support semantic versioning, marketplace distribution, and scoped installation (user, project, local, or managed). This guide covers the full plugin lifecycle: planning, creating, adding components, testing locally, distributing through marketplaces, and migrating existing standalone configurations into plugin format. When to Use This Skill Creating a new Claude Code plugin from scratch Adding components (skills, commands, agents, hooks, MCP, LSP) to an existing plugin Writing or editing a plugin.json manifest Setting up plugin directory structure Testing plugins locally with --plugin-dir Publishing plugins to a marketplace Installing plugins from marketplaces Migrating standalone .claude/ configurations into plugin format Setting up team or organization marketplaces Debugging plugin loading or configuration issues When NOT to Use This Skill Writing standalone skills in .claude/skills/ (use the skills-authoring skill instead) Configuring hooks directly in settings.json without a plugin (use hooks-automation skill) Setting up MCP servers without a plugin wrapper (use mcp-integration skill) General Claude Code configuration or troubleshooting Quick Reference Topic Reference File plugin.json schema, required/optional fields, marketplace.json format references/plugin-manifest.md Directory structure, component types, path conventions, ${CLAUDE_PLUGIN_ROOT} references/plugin-components.md Marketplace creation, publishing, installation commands, team distribution references/marketplace-distribution.md Converting standalone configs to plugins, comparison tables, step-by-step migration references/migration-guide.md Plugin Development Workflow Phase 1: Plan Decide whether you need a plugin or standalone configuration: Approach Skill Names Best For Standalone ( .claude/ directory) /hello Personal workflows, project-specific customizations, quick experiments Plugins (directories with .claude-plugin/plugin.json ) /plugin-name:hello Sharing with teammates, distributing to community, versioned releases, reusable across projects Use standalone configuration when: You are customizing Claude Code for a single project The configuration is personal and does not need to be shared You are experimenting with skills or hooks before packaging them You want short skill names like /hello or /review Use plugins when: You want to share functionality with your team or community You need the same skills/agents across multiple projects You want version control and easy updates for your extensions You are distributing through a marketplace You are okay with namespaced skills like /my-plugin:hello Tip: Start with standalone configuration in .claude/ for quick iteration, then convert to a plugin when you are ready to share. Phase 2: Create the Plugin Create a directory for your plugin: mkdir my-plugin Create the manifest directory and file: mkdir my-plugin/.claude-plugin Create my-plugin/.claude-plugin/plugin.json : { "name" : "my-plugin" , "description" : "A description of what your plugin does" , "version" : "1.0.0" , "author" : { "name" : "Your Name" } } See references/plugin-manifest.md for all available fields. Phase 3: Add Components Add any combination of components to your plugin root directory: commands/