obra avatar

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

Run it inside Claude Code after adding the marketplace with /plugin marketplace add obra/superpowers-developing-for-claude-code.

Contents

Discovered from source

Skills 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 ThisOfficial Docs
Understand directory structurereferences/plugin-structure.mdplugins.md
Choose a plugin patternreferences/common-patterns.mdplugins.md
Make hooks work cross-platformreferences/polyglot-hooks.mdhooks.md
Debug plugin issuesreferences/troubleshooting.mdVarious
See working examplesexamples/ directoryN/A

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

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

TaskRead This File
Create a pluginplugins.md then plugins-reference.md
Set up MCP servermcp.md
Configure hookshooks.md then hooks-guide.md
Write a skillskills.md
CLI commandscli-reference.md
Troubleshoot issuestroubleshooting.md
General setupsetup.md or quickstart.md
Configuration optionssettings.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

  1. Identify the relevant documentation file from the list above
  2. Use Read tool to load: @references/filename.md
  3. Find the answer in the official documentation
  4. 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, or mcp.md
  • Configuration: Start with settings.md or setup.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:

  1. Fetches llms.txt from docs.claude.com
  2. Extracts all Claude Code documentation URLs
  3. Downloads each page to references/
  4. 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-code skill (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