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 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.