/developing-claude-code-plugins

name: developing-claude-code-plugins
description: Use when working on Claude Code plugins (creating, modifying, testing, releasing, or maintaining) - provides streamlined workflows, patterns, and examples for the complete plugin lifecycle

Developing Claude Code Plugins

Overview

This skill provides efficient workflows for creating Claude Code plugins. Use it to make plugin development fast and correct - it synthesizes official docs into actionable steps and provides working examples.

When to Use

Use this skill when:

• Creating a new Claude Code plugin from scratch
• Adding components to an existing plugin (skills, commands, hooks, MCP servers)
• Setting up a development marketplace for testing
• Troubleshooting plugin structure issues
• Understanding plugin architecture and patterns
• Releasing a plugin (versioning, tagging, marketplace distribution)
• Publishing updates or maintaining existing plugins

**For comprehensive official documentation**, use the `working-with-claude-code` skill to access full docs.

Quick Reference

| Need to... | Read This | Official Docs | |-----------|-----------|---------------| | Understand directory structure | `references/plugin-structure.md` | `plugins.md` | | Choose a plugin pattern | `references/common-patterns.md` | `plugins.md` | | Make hooks work cross-platform | `references/polyglot-hooks.md` | `hooks.md` | | Debug plugin issues | `references/troubleshooting.md` | Various | | See working examples | `examples/` directory | N/A |

Plugin Development Workflow

Phase 1: Plan

Before writing code:

1. **Define your plugin's purpose**

• What problem does it solve?
• Who will use it?
• What components will it need?

2. **Choose your pattern** (read `references/common-patterns.md`)

• Simple plugin with one skill?
• MCP integration with guidance?
• Command collection?
• Full-featured platform?

3. **Review examples**

• `examples/simple-greeter-plugin/` - Minimal plugin
• `examples/full-featured-plugin/` - All components
• Installed plugins in `~/.claude/plugins/`

Phase 2: Create Structure

1. **Create directories** (see `references/plugin-structure.md` for details):

   mkdir -p my-plugin/.claude-plugin
   mkdir -p my-plugin/skills
   # Add other component directories as needed

2. **Write plugin.json** (required):

   {
     "name": "my-plugin",
     "version": "1.0.0",
     "description": "What your plugin does",
     "author": {"name": "Your Name"}
   }

See `references/plugin-structure.md` for complete format.

3. **Create development marketplace** (for local testing):

Create `.claude-plugin/marketplace.json`:

   {
     "name": "my-dev",
     "plugins": [{
       "name": "my-plugin",
       "source": "./"
     }]
   }

See `references/plugin-structure.md` for complete format.

Phase 3: Add Components

Use TodoWrite to track component creation:

**Example:**

- Create skill: main-workflow
- Add command: /hello
- Configure hooks
- Write README
- Test installation

For each component type, see:

• **Format/syntax**: `references/plugin-structure.md`
• **When to use**: `references/common-patterns.md`
• **Working code**: `examples/` directory

Phase 4: Test Locally

1. **Install for testing**:

   /plugin marketplace add /path/to/my-plugin
   /plugin install my-plugin@my-dev

Then restart Claude Code.

2. **Test each component**:

• Skills: Ask for tasks matching skill descriptions
• Commands: Run `/your-command`
• MCP servers: Check tools are available
• Hooks: Trigger relevant events

3. **Iterate**:

   /plugin uninstall my-plugin@my-dev
   # Make changes
   /plugin install my-plugin@my-dev
   # Restart Claude Code

Phase 5: Debug and Refine

If something doesn't work, read `references/troubleshooting.md` for:

• Plugin not loading
• Skill not triggering
• Command not appearing
• MCP server not starting
• Hooks not firing

Common issues are usually:

• Wrong directory structure
• Hardcoded paths (use `${CLAUDE_PLUGIN_ROOT}`)
• Forgot to restart Claude Code
• Missing executable permissions on scripts

Phase 6: Release and Distribute

1. **Write README** with:

• What the plugin does
• Installation instructions
• Usage examples
• Component descriptions

2. **Version your release** using semantic versioning:

• Update `version` in `.claude-plugin/plugin.json`
• Document changes in CHANGELOG.md or RELEASE-NOTES.md
• Example: `"version": "1.2.1"` (major.minor.patch)

3. **Commit and tag your release**:

   git add .
   git commit -m "Release v1.2.1: [brief description]"
   git tag v1.2.1
   git push origin main
   git push origin v1.2.1

4. **Choose distribution method**:

**Option A: Direct GitHub distribution**

• Users add: `/plugin marketplace add your-org/your-plugin-repo`
• Your plugin.json serves as the manifest

**Option B: Marketplace distribution** (recommended for multi-plugin collections)

• Create separate marketplace repository
• Add `.claude-plugin/marketplace.json` with plugin references:

     {
       "name": "my-marketplace",
       "owner": {"name": "Your Name"},
       "plugins": [{
         "name": "your-plugin",
         "source": {
           "source": "url",
           "url": "https://github.com/your-org/your-plugin.git"
         },
         "version": "1.2.1",
         "description": "Plugin description"
       }]
     }

• Users add: `/plugin marketplace add your-org/your-marketplace`
• Update marketplace manifest for each plugin release

**Option C: Private/team distribution**

• Configure in team's `.claude/settings.json`:

     {
       "extraKnownMarketplaces": {
         "team-tools": {
           "source": {"source": "github", "repo": "your-org/plugins"}
         }
       }
     }

5. **Test the release**:

   # Test fresh in