gh-obra-superpowers-developing-for-claude-code/skills/developing-claude-code-plugins/references/common-patterns.md

Common Plugin Patterns

Pattern: Simple Plugin with One Skill

Use when: Creating a focused plugin with documentation/reference material

Structure:

my-plugin/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/
│   └── my-skill/
│       ├── SKILL.md
│       ├── scripts/           # Optional - Executable helpers
│       └── references/        # Optional - Documentation files
└── README.md

Real example: superpowers-developing-for-claude-code

• Single skill with comprehensive documentation
• Scripts for self-updating
• 40+ reference files
• No MCP servers, commands, or hooks

When to use:

• Teaching Claude about a specific topic/domain
• Providing process workflows (TDD, debugging, code review)
• Bundling documentation for easy reference
• Creating reusable knowledge bases

---

Pattern: MCP Plugin with Skill

Use when: Providing both a tool integration (MCP) and guidance on using it (skill)

Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Includes mcpServers config
├── skills/
│   └── using-the-tools/
│       └── SKILL.md             # How to use the MCP tools
├── mcp/
│   └── dist/
│       └── index.js             # MCP server implementation
└── README.md

Real example: superpowers-chrome

• MCP server provides browser control tools
• Skill teaches Claude how to use those tools effectively
• Skill includes patterns, examples, workflows

When to use:

• Adding new tools/capabilities to Claude
• Integrating external APIs or services
• Tools need guidance on when/how to use them
• Want Claude to use tools idiomatically, not just technically

Key insight: MCP provides capability, skill provides judgment. The MCP server exposes click(), the skill teaches "await elements before clicking them".

---

Pattern: Command Collection

Use when: Providing multiple custom slash commands for common tasks

Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── status.md
│   ├── logs.md
│   ├── deploy.md
│   └── rollback.md
└── README.md

When to use:

• Project-specific workflows (deploy, test, build)
• Common task shortcuts
• Standardized responses (greetings, status reports)
• Quick context injection

Example use cases:

• /deploy-staging - Step-by-step deployment workflow
• /incident-report - Template for incident documentation
• /code-review - Checklist for reviewing PRs
• /security-check - Security audit workflow

---

Pattern: Hook-Enhanced Workflow

Use when: Automating actions in response to Claude's behavior

Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   └── hooks.json
├── scripts/
│   ├── format-code.sh
│   ├── run-linter.sh
│   └── update-docs.sh
└── README.md

Common hooks:

• PostToolUse[Write|Edit] → Auto-format code
• SessionStart → Load project context
• UserPromptSubmit → Enforce conventions
• PreCompact → Save conversation summaries

When to use:

• Enforcing code style automatically
• Injecting project-specific context
• Running validations or checks
• Maintaining project conventions

Warning: Hooks that block operations can disrupt workflow. Use sparingly and make failure messages clear.

---

Pattern: Full-Featured Plugin

Use when: Building a comprehensive plugin with multiple integration points

Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── main-workflow/
│   └── advanced-techniques/
├── commands/
│   ├── start.md
│   └── help.md
├── hooks/
│   └── hooks.json
├── agents/
│   └── specialist.md
├── mcp/
│   └── dist/
│       └── server.js
└── README.md

Real example: See examples/full-featured-plugin/ in this repo

When to use:

• Complete domain coverage (e.g., "the definitive AWS plugin")
• Multiple related workflows
• Tools + guidance + automation all needed
• Building a "platform" plugin

Caution: Start simple, add complexity only when justified. Most plugins don't need all components.

---

Pattern: Skill with Bundled Resources

Use when: A skill needs reference material, scripts, or templates

Structure:

skills/my-skill/
├── SKILL.md                    # Main skill instructions
├── scripts/
│   ├── helper.py              # Executable utilities
│   └── generator.js
├── references/
│   ├── api-docs.md            # Documentation to load
│   ├── examples.md
│   └── cheatsheet.md
└── assets/
    ├── template.txt           # Files for output
    └── config-example.json

How resources are used:

• SKILL.md tells Claude to "read references/api-docs.md for complete API reference"
• Scripts can be executed via Bash tool
• Assets can be copied/modified for output
• References are loaded into context when skill is invoked

When to use:

• Skill needs detailed technical reference
• Want to separate workflow (SKILL.md) from reference (docs)
• Need executable helpers
• Providing templates or examples

---

Choosing the Right Pattern

Your Goal	Use This Pattern
Teach Claude a process/workflow	Simple Plugin with One Skill
Add new tools + guidance	MCP Plugin with Skill
Provide project shortcuts	Command Collection
Enforce conventions automatically	Hook-Enhanced Workflow
Comprehensive domain coverage	Full-Featured Plugin
Skill needs reference docs	Skill with Bundled Resources

Combining Patterns

Patterns are composable:

Example: "superpowers" plugin

• Multiple skills (brainstorming, TDD, debugging) ← Skill collection
• Each skill has references/ ← Bundled resources
• Could add hooks for enforcement ← Add hooks pattern
• Could add MCP for new tools ← Add MCP pattern

Start simple, grow intentionally. Add components when you have a clear reason, not because they exist.