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

Debug plugin issues references/troubleshooting.md

Various

See working examples examples/ directory N/A

Plugin Development Workflow

Phase 1: Plan

Before writing code:

Define your plugin's purpose

• What problem does it solve?

• Who will use it?

• What components will it need?

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

• Simple plugin with one skill?

• MCP integration with guidance?

• Command collection?

• Full-featured platform?

Review examples

• examples/simple-greeter-plugin/

• Minimal plugin

• examples/full-featured-plugin/

• All components

• Installed plugins in ~/.claude/plugins/

Phase 2: Create Structure

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

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.

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

Install for testing:

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

Then restart Claude Code.

Test each component:

• Skills: Ask for tasks matching skill descriptions

• Commands: Run /your-command

• MCP servers: Check tools are available

• Hooks: Trigger relevant events

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

Write README with:

• What the plugin does

• Installation instructions

• Usage examples

• Component descriptions

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)

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

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"} } } }

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

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

.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

Use ${CLAUDE_PLUGIN_ROOT} for all paths in config files

• Makes plugin portable across systems

• Required for hooks, MCP servers, scripts

Use relative paths in plugin.json

• Start with ./

• Relative to plugin root

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

• Start simple - Begin with minimal structure, add complexity when needed

• Test frequently - Install → test → uninstall → modify → repeat

• Use examples - Copy patterns from working plugins

• Follow conventions - Match style of existing plugins

• Document everything - Clear README helps users and future you

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