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

Quick Reference

references/plugin-structure.md

plugins.md

references/common-patterns.md

plugins.md

references/troubleshooting.md

examples/

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

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

Cross-References

For deep dives into official documentation, use the

working-with-claude-code

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