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

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):

   bash

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

2. •

   Write plugin.json (required):

   json

   {
     "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:

   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:

   bash

   /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:

   bash

   /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:

   bash

   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:
     json

     {
       "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:
     json

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

5. •

   Test the release:

   bash

   # Test fresh installation
   /plugin marketplace add your-marketplace-source
   /plugin install your-plugin@marketplace-name
   # Verify functionality, then clean up
   /plugin uninstall your-plugin@marketplace-name
   

6. •

   Announce and maintain:

   • •GitHub releases (optional)
   • •Team notifications
   • •Monitor for issues and user feedback
   • •Plan maintenance updates

Critical Rules

Always follow these (from references/plugin-structure.md):

1. •

   .claude-plugin/ contains ONLY manifests (plugin.json and optionally marketplace.json)

   • •❌ Don't put skills, commands, or other components inside
   • •✅ Put them at plugin root
2. •

   Use ${CLAUDE_PLUGIN_ROOT} for all paths in config files

   • •Makes plugin portable across systems
   • •Required for hooks, MCP servers, scripts
3. •

   Use relative paths in plugin.json

   • •Start with ./
   • •Relative to plugin root
4. •

   Make scripts executable

   • •chmod +x script.sh
   • •Required for hooks and MCP servers

Resources in This Skill

• •references/plugin-structure.md - Directory layout, file formats, component syntax
• •references/common-patterns.md - When to use each plugin pattern, examples
• •references/polyglot-hooks.md - Cross-platform hook wrapper for Windows/macOS/Linux
• •references/troubleshooting.md - Debug guide for common issues
• •examples/simple-greeter-plugin/ - Minimal working plugin (one skill)
• •examples/full-featured-plugin/ - Complete plugin with all components (includes run-hook.cmd)

Cross-References

For deep dives into official documentation, use the working-with-claude-code skill to access:

• •plugins.md - Plugin development overview
• •plugins-reference.md - Complete API reference
• •skills.md - Skill authoring guide
• •slash-commands.md - Command format
• •hooks.md, hooks-guide.md - Hook system
• •mcp.md - MCP server integration
• •plugin-marketplaces.md - Distribution

Best Practices

1. •Start simple - Begin with minimal structure, add complexity when needed
2. •Test frequently - Install → test → uninstall → modify → repeat
3. •Use examples - Copy patterns from working plugins
4. •Follow conventions - Match style of existing plugins
5. •Document everything - Clear README helps users and future you
6. •Version properly - Use semantic versioning (major.minor.patch)

Workflow Summary

Plan → Choose pattern, review examples
Create → Make structure, write manifests
Add → Build components (skills, commands, etc.)
Test → Install via dev marketplace
Debug → Use troubleshooting guide
Release → Version, tag, distribute via marketplace
Maintain → Monitor, update, support users

The correct path is the fast path. Use references, follow patterns, test frequently.