zhongwei/gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:42 +08:00
commit cc49e355bc
37 changed files with 10917 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

793
skills/plugin-builder/reference/best-practices.md Normal file
View File

@@ -0,0 +1,793 @@
# Plugin Development Best Practices
Comprehensive guide to creating high-quality, maintainable Claude Code plugins.
## Development Workflow
### Starting a New Plugin
**Step 1: Plan Your Plugin**
- Define clear purpose and scope
- Decide what components you need
- Choose appropriate plugin pattern
- Identify target users and use cases
**Step 2: Create Basic Structure**
```bash
mkdir my-plugin
mkdir my-plugin/.claude-plugin
```
**Step 3: Create Minimal Manifest**
Start with only required fields:
```json
{
"name": "my-plugin",
"version": "0.1.0"
}
```
**Step 4: Add First Component**
Start with one component type, test it, then add more.
**Step 5: Test Locally**
```bash
/plugin install /path/to/my-plugin
```
**Step 6: Iterate**
- Test each component
- Refine based on usage
- Add documentation
- Increment version
### Local Development Setup
**Option 1: Standalone Plugin Directory**
```bash
mkdir ~/my-plugins
cd ~/my-plugins
mkdir my-plugin
# Develop plugin
/plugin install ~/my-plugins/my-plugin
```
**Option 2: Personal Marketplace**
```bash
mkdir ~/my-marketplace
cd ~/my-marketplace
mkdir .claude-plugin
# Create marketplace.json
mkdir my-plugin
# Develop plugin
/plugin marketplace add ~/my-marketplace
/plugin install my-plugin@my-marketplace
```
**Recommended:** Use personal marketplace for managing multiple plugins.
### Iterative Development
1. **Make changes** to plugin files
2. **Update** the plugin using one of these methods:
- **Easiest**: Run `/plugin` and select the plugin to update (Claude Code will reload it)
- **Manual**: `/plugin uninstall my-plugin@marketplace-name` then `/plugin install my-plugin@marketplace-name`
3. **Restart Claude Code** if prompted to apply changes
4. **Test** the changes
5. **Repeat** until satisfied
**Tips:**
- The `/plugin` menu command is the easiest way to update during development
- Restart Claude Code to reload all plugins without manual uninstall/reinstall
- For marketplaces, changes are picked up when reinstalling from the marketplace
## Versioning
### Semantic Versioning
Follow semantic versioning strictly: `MAJOR.MINOR.PATCH`
**MAJOR version** (e.g., 1.0.0 → 2.0.0)
- Breaking changes to existing functionality
- Removing components
- Changing component behavior in incompatible ways
- Renaming plugin
**MINOR version** (e.g., 1.0.0 → 1.1.0)
- New features added
- New components added
- Backward-compatible enhancements
- New optional parameters
**PATCH version** (e.g., 1.0.0 → 1.0.1)
- Bug fixes
- Documentation updates
- Performance improvements
- No functionality changes
### Version Examples
**Breaking change (MAJOR):**
```json
// Version 1.0.0
{
"name": "data-processor",
"version": "1.0.0",
"skills": ["./skills"]
}
// Version 2.0.0 - Removed commands, renamed skills directory
{
"name": "data-processor",
"version": "2.0.0",
"skills": ["./processors"]
}
```
**New feature (MINOR):**
```json
// Version 1.0.0
{
"name": "toolkit",
"version": "1.0.0",
"skills": ["./skills"]
}
// Version 1.1.0 - Added commands
{
"name": "toolkit",
"version": "1.1.0",
"skills": ["./skills"],
"commands": ["./commands"]
}
```
**Bug fix (PATCH):**
```json
// Version 1.0.0 - Has a bug in skill logic
{
"name": "analyzer",
"version": "1.0.0",
"skills": ["./skills"]
}
// Version 1.0.1 - Fixed skill logic, no API changes
{
"name": "analyzer",
"version": "1.0.1",
"skills": ["./skills"]
}
```
### Pre-release Versions
For development and testing:
```json
{
"version": "0.1.0" // Initial development
}
{
"version": "0.9.0" // Feature complete, testing
}
{
"version": "1.0.0" // Stable release
}
```
**Convention:**
- `0.x.x` = Under development, breaking changes allowed
- `1.0.0` = First stable release
- `1.x.x+` = Maintain backward compatibility
## Naming Conventions
### Plugin Names
**Format:** kebab-case
**Good names:**
- `git-workflow` - Descriptive, clear purpose
- `data-analyzer` - Indicates functionality
- `react-toolkit` - Shows what it helps with
- `security-scanner` - Obvious use case
**Bad names:**
- `helpers` - Too vague
- `utils` - Doesn't indicate purpose
- `my_plugin` - Wrong case (use kebab-case)
- `MyPlugin` - Wrong case (use kebab-case)
- `stuff` - Not descriptive
**Guidelines:**
- Use 2-3 words typically
- Be specific about functionality
- Avoid generic terms (utils, helpers, tools)
- Make it discoverable by name alone
### Component Names
**Commands:** Action verbs
- `deploy-app.md`
- `run-tests.md`
- `generate-report.md`
**Skills:** Gerund form (verb + -ing)
- `processing-data/`
- `analyzing-code/`
- `generating-reports/`
**Agents:** Role-based
- `code-reviewer.md`
- `security-auditor.md`
- `test-generator.md`
## Documentation
### Plugin Description
Write descriptions that:
- Clearly state purpose
- Include key terms for discoverability
- Are concise (1-2 sentences)
- Help users understand when to use it
**Good examples:**
```json
{
"description": "Tools for processing and analyzing CSV and JSON data files with validation and transformation capabilities"
}
```
```json
{
"description": "Git workflow automation including branch management, PR creation, and commit formatting"
}
```
**Bad examples:**
```json
{
"description": "Helpful stuff" // Too vague
}
```
```json
{
"description": "This plugin provides various utilities and tools that can help you with different tasks in your workflow and make things easier when working with data and files" // Too verbose
}
```
### Keywords
Choose keywords that:
- Describe functionality
- Match user search terms
- Are specific and relevant
- Help with discovery
**Example:**
```json
{
"name": "react-toolkit",
"keywords": ["react", "components", "typescript", "testing", "hooks"]
}
```
**Guidelines:**
- Include 3-7 keywords
- Use specific terms, not generic ones
- Think about how users would search
- Include technology names when relevant
### README Files
Include README.md for complex plugins:
**Essential sections:**
1. **Overview**: What does the plugin do?
2. **Installation**: How to install it
3. **Components**: What's included
4. **Usage**: How to use each component
5. **Examples**: Real-world usage examples
6. **Requirements**: Any dependencies or prerequisites
7. **License**: Licensing information
**CRITICAL: Keep README synchronized with plugin contents**
When adding or removing components (especially skills), ALWAYS update the README to reflect the changes:
- **Adding a skill**: Add it to the Components section with a brief description
- **Removing a skill**: Remove it from the Components section
- **Updating a skill**: Update its description if purpose changed
- **Adding commands/agents**: Document them in the appropriate sections
This is easy to forget but critical for discoverability. Users read the README to understand what the plugin offers.
**Example README structure:**
```markdown
# My Plugin
Brief description of what the plugin does.
## Installation
```bash
/plugin marketplace add <marketplace-url>
/plugin install my-plugin@marketplace-name
```
## Components
### Skills
- **Processing Data**: Handles CSV and JSON files
- **Validating Input**: Validates data against schemas
### Commands
- `/process-data`: Process data files
- `/validate-schema`: Validate data schema
## Usage Examples
### Processing CSV Files
...
## Requirements
- Node.js 18+
- Python 3.9+ (for validation scripts)
## License
MIT
```
## Testing
### Local Testing Workflow
**1. Installation Test**
```bash
# Install plugin
/plugin install /path/to/my-plugin
# Verify installation
/plugin
# Check for errors
claude --debug
```
**2. Component Testing**
```bash
# Verify commands appear
/help
# Test slash command
/my-command
# Test skill (use it in conversation)
# Skills are auto-discovered and invoked
# Verify agents registered
# Agents appear in specialized workflows
```
**3. Path Testing**
- Verify all component paths are relative
- Check paths start with `./`
- Ensure directories/files exist
- Test that components load correctly
**4. Manifest Validation**
```bash
# Validate JSON syntax
cat .claude-plugin/plugin.json | python -m json.tool
# Check required fields
# - name (present and kebab-case)
# - version (semantic versioning format)
```
**5. Clean Environment Testing**
Before sharing:
- Uninstall plugin
- Restart Claude Code
- Reinstall and test fresh
### Testing Checklist
Before releasing:
- [ ] Plugin installs without errors
- [ ] All components load correctly
- [ ] Commands appear in `/help`
- [ ] Skills are discoverable
- [ ] Agents work as expected
- [ ] Hooks trigger correctly
- [ ] No errors in `claude --debug`
- [ ] Documentation is accurate
- [ ] Version number is correct
- [ ] Tested in clean environment
## Code Quality
### Manifest Quality
**Required fields present:**
```json
{
"name": "my-plugin", // ✓ Required
"version": "1.0.0" // ✓ Required
}
```
**Metadata complete:**
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "...", // ✓ Recommended
"author": {
"name": "..." // ✓ Recommended
},
"keywords": [...] // ✓ Recommended
}
```
**Paths correct:**
```json
{
"skills": ["./skills"], // ✓ Relative path
"commands": ["./commands"], // ✓ Starts with ./
"hooks": "./hooks/hooks.json" // ✓ File reference
}
```
### Component Quality
**Skills:**
- Have clear SKILL.md with frontmatter
- Include name and description in frontmatter
- Keep SKILL.md under 500 lines
- Use reference files for details
**Commands:**
- Have frontmatter with name and description
- Clear, concise command prompts
- Include usage examples
- Document parameters
**Agents:**
- Clear agent descriptions
- Specific capabilities listed
- Tool restrictions if needed
**Hooks:**
- Valid hooks.json format
- Scripts exist at specified paths
- Proper permissions on scripts
- Error handling in scripts
### Error Handling
**In scripts:**
```bash
#!/bin/bash
set -e # Exit on error
# Validate inputs
if [ -z "$1" ]; then
echo "Error: Missing required parameter"
exit 1
fi
# Main logic here
```
**In MCP servers:**
```javascript
try {
// Server logic
} catch (error) {
console.error('Error:', error.message);
process.exit(1);
}
```
## Organization
### Single Responsibility
Each plugin should have ONE clear purpose.
**Good: Focused plugins**
- `git-workflow` - Git operations only
- `data-analyzer` - Data analysis only
- `react-toolkit` - React development only
**Bad: Catch-all plugins**
- `my-utils` - Vague, does everything
- `helpers` - No clear purpose
- `tools` - Too generic
### Component Organization
**By functionality:**
```
my-plugin/
├── skills/
│ ├── core-processing/ # Core functionality
│ ├── validation/ # Validation features
│ └── reporting/ # Reporting features
```
**By category:**
```
data-plugin/
├── skills/
│ ├── csv/ # CSV-specific
│ ├── json/ # JSON-specific
│ └── xml/ # XML-specific
```
**Flat structure (simple plugins):**
```
simple-plugin/
├── skills/
│ ├── skill-one/
│ └── skill-two/
```
### File Organization
**Supporting files:**
```
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── my-skill/
│ ├── SKILL.md
│ ├── reference/ # Detailed docs
│ ├── templates/ # Templates
│ └── scripts/ # Helper scripts
├── scripts/ # Plugin-level scripts
├── docs/ # Additional documentation
├── tests/ # Test files (if applicable)
├── README.md
└── LICENSE
```
## Distribution
### Via Marketplace
**Best for:**
- Sharing with teams
- Publishing to community
- Managing multiple plugins
- Versioning and updates
**Steps:**
1. Create/add to marketplace
2. Add entry to marketplace.json
3. Share marketplace URL
4. Users add marketplace once
5. Users install/update plugins easily
**Example marketplace.json entry:**
```json
{
"plugins": [
{
"name": "my-plugin",
"source": "./my-plugin",
"description": "Plugin description"
}
]
}
```
### Direct Installation
**Best for:**
- Quick testing
- Private plugins
- One-off sharing
**Methods:**
```bash
# Local path
/plugin install /path/to/plugin
# Git repository
/plugin install https://github.com/user/plugin
# GitHub shorthand
/plugin install github:user/plugin
```
## Common Pitfalls
### Absolute Paths
**Problem:**
```json
{
"skills": "/Users/me/plugins/my-plugin/skills" // ✗ Absolute
}
```
**Solution:**
```json
{
"skills": ["./skills"] // ✓ Relative
}
```
### Missing Plugin Directory
**Problem:**
```
my-plugin/
└── plugin.json // ✗ Wrong location
```
**Solution:**
```
my-plugin/
└── .claude-plugin/
└── plugin.json // ✓ Correct location
```
### Invalid Version Format
**Problem:**
```json
{
"version": "1" // ✗ Invalid
}
{
"version": "v1.0.0" // ✗ Don't include 'v'
}
```
**Solution:**
```json
{
"version": "1.0.0" // ✓ Semantic versioning
}
```
### Overly Generic Names
**Problem:**
```json
{
"name": "utils" // ✗ Too vague
}
```
**Solution:**
```json
{
"name": "data-utils" // ✓ More specific
}
```
### Missing Component Files
**Problem:**
```json
{
"skills": ["./skills"]
}
// But no skills/ directory exists
```
**Solution:**
- Create directory before referencing
- Or remove reference from plugin.json
### Wrong Component Format
**Problem:**
```markdown
# My Skill
Content without frontmatter
```
**Solution:**
```markdown
---
name: My Skill
description: Skill description
---
# My Skill
Content
```
## Maintenance
### Keeping Plugins Updated
**Regular maintenance:**
- Fix bugs promptly
- Update documentation
- Respond to user feedback
- Test with new Claude Code versions
**Version updates:**
- Follow semantic versioning
- Document changes in CHANGELOG.md
- Test before releasing
- Update marketplace.json
### Deprecation Strategy
When removing features:
**1. Announce deprecation** (MINOR version)
```json
{
"version": "1.5.0",
"description": "Note: feature X deprecated, will be removed in 2.0.0"
}
```
**2. Remove feature** (MAJOR version)
```json
{
"version": "2.0.0",
"description": "Breaking: feature X removed"
}
```
**3. Document migration** in README
### Backward Compatibility
**Maintain in MINOR versions:**
- Keep existing component paths
- Don't remove components
- Don't break existing functionality
- Add, don't replace
**Break only in MAJOR versions:**
- Remove components
- Change component behavior
- Rename paths
- Require new dependencies
## Security Considerations
### Script Safety
- Validate all inputs
- Use proper permissions
- Avoid executing untrusted code
- Document security requirements
### Sensitive Data
- Don't hardcode credentials
- Use environment variables
- Document required secrets
- Provide examples, not real values
### MCP Server Security
- Validate external inputs
- Use HTTPS for remote connections
- Handle errors gracefully
- Log security-relevant events
## Summary
**Key Best Practices:**
1. **Plan before building** - Clear purpose, right components
2. **Start minimal** - plugin.json only, add as needed
3. **Use relative paths** - Always start with `./`
4. **Follow semantic versioning** - MAJOR.MINOR.PATCH strictly
5. **Test thoroughly** - Install, test, debug before sharing
6. **Document well** - Clear descriptions, examples, README
7. **Organize logically** - Single responsibility, clear structure
8. **Maintain actively** - Fix bugs, respond to feedback
9. **Version carefully** - Don't break backward compatibility
10. **Secure by default** - Validate inputs, protect secrets
Follow these practices to create high-quality, maintainable plugins that users will trust and enjoy using.

606
skills/plugin-builder/reference/plugin-structure.md Normal file
View File

@@ -0,0 +1,606 @@
# Plugin Directory Structure
Complete reference for organizing Claude Code plugin directories and files.
## Complete Structure Example
```
my-plugin/
├── .claude-plugin/
│ └── plugin.json # REQUIRED: Plugin manifest
├── commands/ # Optional: Custom slash commands
│ ├── command-one.md
│ └── command-two.md
├── agents/ # Optional: Custom agents
│ ├── agent-one.md
│ └── agent-two.md
├── skills/ # Optional: Agent skills
│ ├── skill-one/
│ │ ├── SKILL.md
│ │ ├── reference/
│ │ │ └── details.md
│ │ └── templates/
│ │ └── template.md
│ └── skill-two/
│ └── SKILL.md
├── hooks/ # Optional: Event handlers
│ └── hooks.json
├── .mcp.json # Optional: MCP server config
├── scripts/ # Optional: Helper scripts
│ └── setup.sh
└── README.md # Optional: Documentation
```
## Required Files
### Plugin Manifest (.claude-plugin/plugin.json)
This is the ONLY required file. Every plugin must have this.
**Minimal example:**
```json
{
"name": "my-plugin",
"version": "1.0.0"
}
```
**Complete example:**
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Brief description of plugin purpose",
"author": {
"name": "Your Name",
"email": "email@example.com"
},
"homepage": "https://docs.example.com",
"repository": "https://github.com/username/repo",
"license": "MIT",
"keywords": ["tag1", "tag2", "tag3"],
"commands": ["./commands"],
"agents": ["./agents"],
"skills": ["./skills"],
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json"
}
```
### Field Definitions
**Required fields:**
- `name` (string): Unique plugin identifier in kebab-case
- `version` (string): Semantic version (MAJOR.MINOR.PATCH)
**Optional metadata:**
- `description` (string): Brief plugin purpose for discoverability
- `author` (object): Author information
- `name` (string, required): Author's name
- `email` (string, optional): Author's email
- `homepage` (string): URL to documentation
- `repository` (string): URL to source code
- `license` (string): Open source license identifier (e.g., "MIT", "Apache-2.0")
- `keywords` (array of strings): Tags for marketplace discovery
**Component paths:**
- `commands` (string or array): Path(s) to command directories
- `agents` (string or array): Path(s) to agent directories
- `skills` (string or array): Path(s) to skill directories
- `hooks` (string): Path to hooks.json file
- `mcpServers` (string): Path to .mcp.json file
## Path Resolution
### Path Rules
1. **Must be relative** to plugin root
2. **Should start with** `./`
3. **Can use variable** `${CLAUDE_PLUGIN_ROOT}` for flexibility
4. **Can be arrays** for multiple component directories
### Path Examples
**Single directory:**
```json
{
"skills": "./skills"
}
```
**Multiple directories:**
```json
{
"skills": ["./skills", "./shared-skills"]
}
```
**With variable (advanced):**
```json
{
"skills": "${CLAUDE_PLUGIN_ROOT}/skills"
}
```
**File reference:**
```json
{
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json"
}
```
## Component Directories
### Commands Directory
Contains custom slash command definitions.
**Structure:**
```
commands/
├── my-command.md
├── another-command.md
└── nested/
└── sub-command.md
```
**File format:**
Each command is a Markdown file with frontmatter:
```markdown
---
name: my-command
description: Command description
---
Command prompt content here.
```
**Usage:** Users invoke with `/my-command`
### Agents Directory
Contains custom agent definitions.
**Structure:**
```
agents/
├── my-agent.md
└── specialized-agent.md
```
**File format:**
Markdown files describing agent capabilities and behavior.
### Skills Directory
Contains agent skills (most common component type).
**Structure:**
```
skills/
├── skill-one/
│ ├── SKILL.md # Required
│ ├── reference/ # Optional: detailed docs
│ │ └── details.md
│ └── templates/ # Optional: templates
│ └── output.json
└── skill-two/
└── SKILL.md # Minimal skill
```
**Requirements:**
- Each skill is a directory
- Must contain `SKILL.md` with YAML frontmatter
- Can include supporting files (reference docs, templates, scripts)
### Hooks Directory
Contains event handler configuration.
**Structure:**
```
hooks/
└── hooks.json
```
**hooks.json format:**
```json
{
"hooks": [
{
"event": "PreToolUse",
"command": "./scripts/pre-tool.sh"
},
{
"event": "PostToolUse",
"command": "./scripts/post-tool.sh"
},
{
"event": "UserPromptSubmit",
"command": "./scripts/on-submit.sh"
}
]
}
```
**Supported events:**
- `PreToolUse`: Before tool execution
- `PostToolUse`: After tool execution
- `UserPromptSubmit`: When user submits prompt
### MCP Servers Configuration
Model Context Protocol server integration.
**File location:** `.mcp.json` in plugin root
**Format:**
```json
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["./path/to/server.js"],
"env": {
"API_KEY": "value"
}
}
}
}
```
## Common Plugin Patterns
### Pattern 1: Skills-Only Plugin (Most Common)
Simplest and most common plugin pattern.
```
my-skills-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
├── skill-one/
│ └── SKILL.md
└── skill-two/
└── SKILL.md
```
**plugin.json:**
```json
{
"name": "my-skills-plugin",
"version": "1.0.0",
"description": "Collection of helpful skills",
"skills": ["./skills"]
}
```
**Use when:** You want to share reusable capabilities that agents can invoke.
### Pattern 2: Commands-Only Plugin
For user-invoked custom commands.
```
my-commands-plugin/
├── .claude-plugin/
│ └── plugin.json
└── commands/
├── deploy.md
└── test.md
```
**plugin.json:**
```json
{
"name": "my-commands-plugin",
"version": "1.0.0",
"description": "Custom deployment and testing commands",
"commands": ["./commands"]
}
```
**Use when:** You want custom slash commands for specific workflows.
### Pattern 3: Agent-Focused Plugin
For specialized agent behaviors.
```
my-agent-plugin/
├── .claude-plugin/
│ └── plugin.json
└── agents/
└── code-reviewer.md
```
**plugin.json:**
```json
{
"name": "my-agent-plugin",
"version": "1.0.0",
"description": "Specialized code review agent",
"agents": ["./agents"]
}
```
**Use when:** You need specialized agent behaviors.
### Pattern 4: MCP Integration Plugin
For external tool integrations.
```
mcp-integration-plugin/
├── .claude-plugin/
│ └── plugin.json
├── .mcp.json
└── servers/
└── custom-server.js
```
**plugin.json:**
```json
{
"name": "mcp-integration",
"version": "1.0.0",
"description": "Custom MCP server integration",
"mcpServers": "./.mcp.json"
}
```
**Use when:** Integrating external data sources or tools.
### Pattern 5: Workflow Plugin (Multi-Component)
Combines multiple component types for complete workflow.
```
workflow-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ └── start-workflow.md
├── skills/
│ ├── process-data/
│ │ └── SKILL.md
│ └── generate-report/
│ └── SKILL.md
└── hooks/
└── hooks.json
```
**plugin.json:**
```json
{
"name": "workflow-plugin",
"version": "1.0.0",
"description": "Complete data processing workflow",
"commands": ["./commands"],
"skills": ["./skills"],
"hooks": "./hooks/hooks.json"
}
```
**Use when:** Building complete workflows with commands, skills, and hooks.
### Pattern 6: Enterprise Plugin (Full-Featured)
Comprehensive plugin with all component types.
```
enterprise-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── deploy.md
│ └── rollback.md
├── agents/
│ └── security-scanner.md
├── skills/
│ ├── compliance-check/
│ │ └── SKILL.md
│ └── audit-log/
│ └── SKILL.md
├── hooks/
│ └── hooks.json
├── .mcp.json
├── scripts/
│ ├── pre-deploy.sh
│ └── post-deploy.sh
└── README.md
```
**plugin.json:**
```json
{
"name": "enterprise-plugin",
"version": "2.1.0",
"description": "Enterprise deployment and compliance toolkit",
"author": {
"name": "Enterprise Team",
"email": "team@enterprise.com"
},
"homepage": "https://docs.enterprise.com/plugin",
"repository": "https://github.com/enterprise/plugin",
"license": "MIT",
"keywords": ["enterprise", "deployment", "compliance", "security"],
"commands": ["./commands"],
"agents": ["./agents"],
"skills": ["./skills"],
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json"
}
```
**Use when:** Building comprehensive tooling for enterprise workflows.
## Multi-Directory Support
You can specify multiple directories for component types.
**Example:**
```json
{
"name": "multi-source-plugin",
"version": "1.0.0",
"skills": ["./skills", "./shared-skills", "./experimental-skills"],
"commands": ["./commands", "./admin-commands"]
}
```
**Directory structure:**
```
multi-source-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── core-skill/
│ └── SKILL.md
├── shared-skills/
│ └── shared-skill/
│ └── SKILL.md
├── experimental-skills/
│ └── experimental-skill/
│ └── SKILL.md
├── commands/
│ └── user-command.md
└── admin-commands/
└── admin-command.md
```
**Use when:**
- Organizing components by category
- Separating stable from experimental features
- Sharing components across multiple plugins
## Supporting Files
### Scripts Directory
Optional directory for helper scripts.
```
scripts/
├── setup.sh
├── validate.py
└── hooks/
├── pre-tool.sh
└── post-tool.sh
```
**Use for:**
- Installation scripts
- Validation scripts
- Hook implementations
- Utility scripts
### Documentation Files
Optional documentation in plugin root.
```
my-plugin/
├── .claude-plugin/
├── README.md # Main documentation
├── CHANGELOG.md # Version history
└── LICENSE # License file
```
**Recommended:**
- README.md: Installation, usage, examples
- CHANGELOG.md: Version history and changes
- LICENSE: License text for open source plugins
## Best Practices
### Organization
- Group related components together
- Use clear, descriptive directory names
- Keep supporting files in logical locations
- Don't mix component types in same directory
### File Naming
- Use kebab-case for file names
- Be descriptive: `generate-report.md` not `gen.md`
- Match component names to file names when possible
### Component Placement
- Commands: User-facing, workflow-oriented
- Skills: Agent-invoked, reusable capabilities
- Agents: Specialized behaviors
- Hooks: Event-driven actions
- MCP: External integrations
### Path Management
- Always use relative paths
- Start paths with `./`
- Test all paths after creating manifest
- Verify paths work after installation
### Documentation
- Include README.md for complex plugins
- Document each component's purpose
- Provide usage examples
- List any requirements or dependencies
## Troubleshooting
### Plugin Not Found
**Symptom:** Plugin doesn't appear after installation
**Check:**
- `.claude-plugin/plugin.json` exists
- JSON is valid (use linter)
- Plugin directory is in correct location
### Components Not Loaded
**Symptom:** Commands/skills don't appear after install
**Check:**
- Paths in plugin.json are relative and correct
- Paths start with `./`
- Component files have correct format (frontmatter, etc.)
- Use `claude --debug` to see loading details
### Invalid Manifest
**Symptom:** Error when installing plugin
**Check:**
- Required fields present (name, version)
- Version follows semantic versioning (x.y.z)
- JSON syntax is valid
- Paths exist and are relative
### Path Resolution Issues
**Symptom:** Components not found
**Check:**
- Paths are relative, not absolute
- Paths start with `./`
- Directories/files exist at specified paths
- No typos in path strings
## Validation Checklist
Before sharing your plugin:
- [ ] `.claude-plugin/plugin.json` exists and is valid JSON
- [ ] Required fields present: `name`, `version`
- [ ] Version follows semantic versioning (x.y.z)
- [ ] All paths are relative and start with `./`
- [ ] All referenced paths exist
- [ ] Component files have correct format
- [ ] Plugin installs without errors
- [ ] Components appear and work correctly
- [ ] Tested with `claude --debug`
- [ ] Documentation is clear and complete
## Summary
**Key Takeaways:**
1. Only `.claude-plugin/plugin.json` is required
2. All other components are optional
3. Use relative paths starting with `./`
4. Choose patterns that match your needs
5. Start simple, add complexity as needed
6. Test thoroughly before sharing

137
skills/plugin-builder/reference/review-checklist.md Normal file
View File

@@ -0,0 +1,137 @@
# Plugin Review Checklist
This comprehensive checklist helps ensure plugins follow best practices before being shared or added to marketplaces.
## Detailed Review Checklist
### 1. Manifest Validation
- [ ] `plugin.json` exists at `.claude-plugin/plugin.json` (not at root)
- [ ] `name` field is present and uses kebab-case
- [ ] `version` field follows semantic versioning (MAJOR.MINOR.PATCH)
- [ ] `description` is clear and concise (if present)
- [ ] `author.name` is specified (if author field exists)
- [ ] `keywords` are relevant for discoverability (if present)
- [ ] JSON syntax is valid (no trailing commas, proper quotes)
### 2. Path Validation
- [ ] All component paths are relative (start with `./`)
- [ ] No absolute paths in plugin.json
- [ ] Component paths reference directories/files that actually exist
- [ ] No use of `../` to reference files outside plugin directory
- [ ] Paths use forward slashes (not backslashes)
- [ ] `${CLAUDE_PLUGIN_ROOT}` variable is used correctly if present
### 3. Structure and Organization
- [ ] Plugin follows a clear structural pattern (single-purpose, skills-focused, or full-featured)
- [ ] Related functionality is grouped together
- [ ] Directory names are descriptive and consistent
- [ ] No unnecessary files or directories
- [ ] Plugin has single, cohesive purpose (not a catch-all)
### 4. Component Quality
**For Skills:**
- [ ] Each skill has `SKILL.md` in its directory
- [ ] Skill frontmatter includes `name` and `description`
- [ ] Skill descriptions clearly indicate when to use the skill
- [ ] Skills provide actionable guidance, not just information dumps
- [ ] Skills use progressive disclosure (start simple, reveal detail as needed)
**For Commands:**
- [ ] Command files use `.md` extension
- [ ] Command names are descriptive and follow naming conventions
- [ ] Commands include usage examples
- [ ] Commands document required vs optional parameters
**For Agents:**
- [ ] Agent files clearly describe agent purpose and capabilities
- [ ] Agent tools and behaviors are well-defined
- [ ] Agent use cases are documented
**For Hooks:**
- [ ] `hooks.json` has valid structure
- [ ] Hook events are valid (PreToolUse, PostToolUse, UserPromptSubmit)
- [ ] Hook scripts/commands are tested
**For MCP Servers:**
- [ ] `.mcp.json` configuration is valid
- [ ] Server dependencies are documented
- [ ] Installation instructions are provided
### 5. Documentation
- [ ] README.md exists and explains plugin purpose
- [ ] Installation instructions are clear
- [ ] Usage examples are provided
- [ ] Requirements and dependencies are documented
- [ ] License is specified (in plugin.json or LICENSE file)
- [ ] Each component has adequate documentation
### 6. Naming Conventions
- [ ] Plugin name is descriptive and indicates purpose
- [ ] Plugin name doesn't conflict with common/existing plugins
- [ ] Avoid generic names like `utils`, `helpers`, `misc`
- [ ] Skill names clearly indicate their purpose
- [ ] Command names are intuitive and follow slash-command conventions
### 7. Versioning
- [ ] Version number is appropriate for current state
- [ ] Breaking changes increment MAJOR version
- [ ] New features increment MINOR version
- [ ] Bug fixes increment PATCH version
- [ ] Version matches expected maturity (1.0.0+ for production-ready)
### 8. Security and Safety
- [ ] No hardcoded credentials or API keys
- [ ] No references to private/internal systems in public plugins
- [ ] Hook commands don't execute unsafe operations
- [ ] MCP servers use secure connection methods
- [ ] No malicious or obfuscated code
## Common Issues to Flag
### Critical Issues (must fix before sharing)
- Missing or malformed plugin.json
- Invalid JSON syntax
- Absolute paths instead of relative paths
- Missing required component files
- Security vulnerabilities (hardcoded secrets, unsafe code)
- Invalid semantic versioning
### Important Issues (should fix)
- Missing or inadequate description
- Poor or generic naming
- Missing documentation
- Untested components
- Paths that don't start with `./`
- No version or author information
### Minor Issues (nice to fix)
- Missing keywords for discoverability
- No homepage or repository link
- Could benefit from more examples
- Documentation could be clearer
- Directory structure could be more intuitive
## Review Decision Criteria
### Ready to Share
Plugin is ready to share if:
- All critical issues resolved
- Plugin installs and works correctly
- Documentation is adequate
- Follows best practices
- Has clear, single purpose
### Needs Revision
Plugin needs revision if:
- Any critical issues present
- Important issues significantly impact usability
- Testing reveals functionality problems
- Documentation is insufficient
### Reject
Plugin should be rejected if:
- Security vulnerabilities present
- Malicious or deceptive functionality
- Violates plugin system requirements
- Cannot be fixed to meet minimum standards