
superpowers-developing-for-claude-code
Skills for developing Claude Code plugins, skills, and MCP servers. Includes complete official documentation with self-update.
- version
- 0.3.1
- GitHub stars
- 148
Install
/plugin install superpowers-developing-for-claude-code@superpowers-developing-for-claude-code-devRun it inside Claude Code after adding the marketplace with /plugin marketplace add obra/superpowers-developing-for-claude-code.
Contents
Discovered from sourceSkills 2
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 pluginexamples/full-featured-plugin/- All components- Installed plugins in
~/.claude/plugins/
Phase 2: Create Structure
-
Create directories (see
references/plugin-structure.mdfor 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.mdfor 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.mdfor 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-devThen 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
versionin.claude-plugin/plugin.json - Document changes in CHANGELOG.md or RELEASE-NOTES.md
- Example:
"version": "1.2.1"(major.minor.patch)
- Update
-
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.jsonwith 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"} } } }
- Users add:
-
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.jsonand optionallymarketplace.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
- Start with
-
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 syntaxreferences/common-patterns.md- When to use each plugin pattern, examplesreferences/polyglot-hooks.md- Cross-platform hook wrapper for Windows/macOS/Linuxreferences/troubleshooting.md- Debug guide for common issuesexamples/simple-greeter-plugin/- Minimal working plugin (one skill)examples/full-featured-plugin/- Complete plugin with all components (includesrun-hook.cmd)
Cross-References
For deep dives into official documentation, use the working-with-claude-code skill to access:
plugins.md- Plugin development overviewplugins-reference.md- Complete API referenceskills.md- Skill authoring guideslash-commands.md- Command formathooks.md,hooks-guide.md- Hook systemmcp.md- MCP server integrationplugin-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.
Working with Claude Code
Overview
This skill provides complete, authoritative documentation for Claude Code directly from docs.claude.com. Instead of guessing about configuration paths, API structures, or feature capabilities, read the official docs stored in this skill's references directory.
When to Use
Use this skill when:
- Creating or configuring Claude Code plugins
- Setting up MCP servers
- Working with hooks (pre-commit, session-start, etc.)
- Writing or testing skills
- Configuring Claude Code settings
- Troubleshooting Claude Code issues
- Understanding CLI commands
- Setting up integrations (VS Code, JetBrains, etc.)
- Configuring networking, security, or enterprise features
Quick Reference
| Task | Read This File |
|---|---|
| Create a plugin | plugins.md then plugins-reference.md |
| Set up MCP server | mcp.md |
| Configure hooks | hooks.md then hooks-guide.md |
| Write a skill | skills.md |
| CLI commands | cli-reference.md |
| Troubleshoot issues | troubleshooting.md |
| General setup | setup.md or quickstart.md |
| Configuration options | settings.md |
Documentation Organization
All documentation is stored as individual markdown files in references/. Use the Read tool to access specific documentation:
references/
├── overview.md # Claude Code introduction
├── quickstart.md # Getting started guide
├── setup.md # Installation and setup
├── plugins.md # Plugin development
├── plugins-reference.md # Plugin API reference
├── plugin-marketplaces.md # Plugin marketplaces
├── skills.md # Skill creation
├── mcp.md # MCP server integration
├── hooks.md # Hooks overview
├── hooks-guide.md # Hooks implementation guide
├── slash-commands.md # Slash command reference
├── sub-agents.md # Subagent usage
├── settings.md # Configuration reference
├── cli-reference.md # CLI command reference
├── common-workflows.md # Common usage patterns
├── interactive-mode.md # Interactive mode guide
├── headless.md # Headless mode guide
├── output-styles.md # Output customization
├── statusline.md # Status line configuration
├── memory.md # Memory and context management
├── checkpointing.md # Checkpointing feature
├── analytics.md # Usage analytics
├── costs.md # Cost tracking
├── monitoring-usage.md # Usage monitoring
├── data-usage.md # Data usage policies
├── security.md # Security features
├── iam.md # IAM integration
├── network-config.md # Network configuration
├── terminal-config.md # Terminal configuration
├── model-config.md # Model configuration
├── llm-gateway.md # LLM gateway setup
├── amazon-bedrock.md # AWS Bedrock integration
├── google-vertex-ai.md # Google Vertex AI integration
├── vs-code.md # VS Code integration
├── jetbrains.md # JetBrains integration
├── devcontainer.md # Dev container support
├── github-actions.md # GitHub Actions integration
├── gitlab-ci-cd.md # GitLab CI/CD integration
├── third-party-integrations.md # Other integrations
├── legal-and-compliance.md # Legal information
├── troubleshooting.md # Troubleshooting guide
└── migration-guide.md # Migration guide
Workflow
For Specific Questions
- Identify the relevant documentation file from the list above
- Use Read tool to load:
@references/filename.md - Find the answer in the official documentation
- Apply the solution
Example:
User: "How do I create a Claude Code plugin?"
→ Read @references/plugins.md
→ Follow the official plugin creation steps
For Broad Topics
When exploring a topic, start with the overview document, then drill into specific files:
- Extending Claude Code: Start with
plugins.md,skills.md, ormcp.md - Configuration: Start with
settings.mdorsetup.md - Integrations: Check relevant integration file (vs-code.md, github-actions.md, etc.)
- Troubleshooting: Start with
troubleshooting.md
For Uncertain Topics
Use Grep tool to search across all documentation:
pattern: "search term"
path: ~/.claude/skills/working-with-claude-code/references/
Updating Documentation
The skill includes scripts/update_docs.js to fetch the latest documentation from docs.claude.com.
Run when:
- Documentation seems outdated
- New Claude Code features are released
- Official docs have been updated
node ~/.claude/skills/working-with-claude-code/scripts/update_docs.js
The script:
- Fetches llms.txt from docs.claude.com
- Extracts all Claude Code documentation URLs
- Downloads each page to
references/ - Reports success/failures
Common Patterns
Plugin Development
Read plugins.md for overview, then plugins-reference.md for API details.
MCP Server Setup
Read mcp.md for configuration format and examples.
Hook Configuration
Read hooks.md for overview, then hooks-guide.md for implementation details.
Skill Creation
Read skills.md for the complete skill authoring guide.
What This Skill Does NOT Do
- This skill provides documentation access, not procedural guidance
- For workflows on how to build plugins/skills, use the
extending-claude-codeskill (when available) - This skill is a reference library, not a tutorial
Red Flags
If you find yourself:
- Guessing about configuration file locations → Read
settings.md - Speculating about API structures → Read relevant reference doc
- Unsure about hook names → Read
hooks.md - Making assumptions about features → Search the docs first
Always consult the official documentation before guessing.
Sponsors
Details
- Marketplace
- obra/superpowers-developing-for-claude-code
- Author
- Jesse Vincent
- Category
- Community