developing-claude-code-plugins（developing Claude 代码 plugins）

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?

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

- Simple plugin with one skill? - MCP integration with guidance? - Command collection? - Full-featured platform?

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

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

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

1. 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
2. Choose distribution method: Option A: Direct GitHub distribution Option B: Marketplace distribution (recommended for multi-plugin collections) Option C: Private/team distribution

- Users add: /plugin marketplace add your-org/your-plugin-repo - Your plugin.json serves as the manifest - 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 - Configure in team's .claude/settings.json: {"extraKnownMarketplaces": {"team-tools": {"source": {"source": "github", "repo": "your-org/plugins"}}}}

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

1. Use ${CLAUDE_PLUGIN_ROOT} for all paths in config files

- Makes plugin portable across systems - Required for hooks, MCP servers, scripts

1. Use relative paths in plugin.json

- Start with ./ - Relative to plugin root

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