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:

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

bash

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

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.

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

Install for testing:

bash

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

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

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:

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

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

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

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

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.

developing-claude-code-plugins

NPX Install

Tags

SKILL.md Content

Developing Claude Code Plugins

Overview

When to Use

Quick Reference

Plugin Development Workflow

Phase 1: Plan

Phase 2: Create Structure

Phase 3: Add Components

Phase 4: Test Locally

Phase 5: Debug and Refine

Phase 6: Release and Distribute

Critical Rules

Resources in This Skill

Cross-References

Best Practices

Workflow Summary