997 lines
26 KiB
Markdown
997 lines
26 KiB
Markdown
---
|
|
description: Generate production-ready Claude Code plugin structures for OpenPlugins marketplace
|
|
argument-hint: <plugin-name> [category]
|
|
allowed-tools: Bash(mkdir:*), Bash(git:*), Write, Read, Grep
|
|
---
|
|
|
|
# Plugin Quickstart Generator
|
|
|
|
Generate a complete, production-ready Claude Code plugin structure following OpenPlugins marketplace standards.
|
|
|
|
## Mission
|
|
|
|
Create a fully-structured plugin with all required files, metadata, documentation, and templates that meets OpenPlugins quality standards and is ready for local testing and marketplace submission.
|
|
|
|
## Arguments
|
|
|
|
- **$1 (plugin-name)**: Required. Plugin name in lowercase-hyphen format (e.g., `code-formatter`)
|
|
- **$2 (category)**: Optional. One of: development, testing, deployment, documentation, security, database, monitoring, productivity, quality, collaboration
|
|
|
|
## Process
|
|
|
|
### 1. Validate Plugin Name
|
|
|
|
**CRITICAL**: Plugin name MUST be in lowercase-hyphen format (e.g., `my-plugin-name`).
|
|
|
|
If the plugin name contains uppercase letters, underscores, spaces, or other invalid characters, STOP and provide clear error message with examples of valid names.
|
|
|
|
Valid format: `^[a-z][a-z0-9-]*[a-z0-9]$`
|
|
|
|
Examples:
|
|
- ✅ Valid: `code-formatter`, `test-runner`, `deploy-tool`, `my-plugin`
|
|
- ❌ Invalid: `Code-Formatter`, `test_runner`, `Deploy Tool`, `My Plugin`, `plugin-`
|
|
|
|
### 2. Interactive Metadata Collection
|
|
|
|
Gather the following information from the user:
|
|
|
|
**Description** (Required, 50-200 characters):
|
|
- Prompt: "Enter a brief description of your plugin (50-200 characters):"
|
|
- Validate length and provide feedback
|
|
- Ensure it's informative and specific (not generic like "A useful plugin")
|
|
|
|
**Author Information**:
|
|
- Name (Default: from `git config user.name` or prompt)
|
|
- Email (Default: from `git config user.email` or prompt)
|
|
- URL (Optional: GitHub profile or website)
|
|
|
|
**License** (Default: MIT):
|
|
- Show options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
|
|
- Prompt: "Choose license (default: MIT):"
|
|
- Validate against list
|
|
|
|
**Category** (Use $2 if provided, otherwise prompt):
|
|
- Show all 10 categories:
|
|
- development: Code generation, scaffolding, refactoring
|
|
- testing: Test generation, coverage, quality assurance
|
|
- deployment: CI/CD, infrastructure, release automation
|
|
- documentation: Docs generation, API documentation
|
|
- security: Vulnerability scanning, secret detection
|
|
- database: Schema design, migrations, queries
|
|
- monitoring: Performance analysis, logging
|
|
- productivity: Workflow automation, task management
|
|
- quality: Linting, formatting, code review
|
|
- collaboration: Team tools, communication
|
|
- Prompt: "Choose category:"
|
|
- Validate selection
|
|
|
|
**Keywords** (3-7 keywords, comma-separated):
|
|
- Prompt: "Enter 3-7 relevant keywords (comma-separated):"
|
|
- Examples: testing, automation, python, docker, ci-cd
|
|
- Validate count (3-7 keywords)
|
|
- Avoid generic terms: plugin, tool, utility
|
|
|
|
**Agent Option**:
|
|
- Prompt: "Include a specialist agent? (y/n, default: n):"
|
|
- If yes, prompt for agent capabilities (comma-separated)
|
|
|
|
### 3. Generate Plugin Structure
|
|
|
|
Create the following directory structure in the current working directory:
|
|
|
|
```
|
|
<plugin-name>/
|
|
├── plugin.json # At plugin root
|
|
├── commands/
|
|
│ └── example.md
|
|
├── agents/ # Only if user requested agent
|
|
│ └── example-agent.md
|
|
├── README.md
|
|
├── LICENSE
|
|
├── CHANGELOG.md
|
|
└── .gitignore
|
|
```
|
|
|
|
### 4. Generate plugin.json
|
|
|
|
Create `plugin.json` at the plugin root with complete metadata:
|
|
|
|
```json
|
|
{
|
|
"name": "<plugin-name>",
|
|
"version": "1.0.0",
|
|
"description": "<user-provided-description>",
|
|
"author": {
|
|
"name": "<author-name>",
|
|
"email": "<author-email>"
|
|
// Include "url" field if user provided it
|
|
},
|
|
"license": "<selected-license>",
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "https://github.com/<username>/<plugin-name>"
|
|
},
|
|
"homepage": "https://github.com/<username>/<plugin-name>",
|
|
"keywords": [
|
|
// User-provided keywords as array
|
|
]
|
|
}
|
|
```
|
|
|
|
**Important**:
|
|
- Try to infer GitHub username from git config or author URL
|
|
- If not available, use placeholder: "yourusername"
|
|
- Ensure valid JSON with proper escaping
|
|
|
|
### 5. Generate Example Command
|
|
|
|
Create `commands/example.md`:
|
|
|
|
```markdown
|
|
---
|
|
description: Example command for <plugin-name>
|
|
---
|
|
|
|
# Example Command
|
|
|
|
This is a template command for your plugin. Replace this with your actual functionality.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
/example [arguments]
|
|
```
|
|
|
|
## Implementation
|
|
|
|
**TODO**: Add your command logic here.
|
|
|
|
### Example Implementation Steps
|
|
|
|
1. Parse the arguments from $ARGUMENTS
|
|
2. Validate inputs
|
|
3. Execute core functionality
|
|
4. Provide clear output with results
|
|
5. Handle errors gracefully
|
|
|
|
### Accessing Arguments
|
|
|
|
- **All arguments**: `$ARGUMENTS`
|
|
- **First argument**: `$1`
|
|
- **Second argument**: `$2`
|
|
- And so on...
|
|
|
|
### Using Tools
|
|
|
|
If your command needs specific tools, add them to frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
description: Example command
|
|
allowed-tools: Bash(npm:*), Read, Write
|
|
---
|
|
```
|
|
|
|
### Best Practices
|
|
|
|
- Be specific in your description
|
|
- Validate user inputs
|
|
- Provide helpful error messages
|
|
- Include usage examples
|
|
- Document expected behavior
|
|
|
|
## Error Handling
|
|
|
|
Handle common error cases:
|
|
- Missing required arguments
|
|
- Invalid input formats
|
|
- File not found
|
|
- Permission issues
|
|
- External command failures
|
|
|
|
Provide clear, actionable error messages.
|
|
|
|
## Output Format
|
|
|
|
Define what users should expect:
|
|
- Success messages
|
|
- Error messages
|
|
- Data format (JSON, text, tables)
|
|
- Next steps or recommendations
|
|
```
|
|
|
|
### 6. Generate Agent (If Requested)
|
|
|
|
If user requested an agent, create `agents/example-agent.md`:
|
|
|
|
```markdown
|
|
---
|
|
name: <plugin-name-base>
|
|
description: Expert specialist for <plugin-purpose>. Use proactively when <invocation-triggers>.
|
|
capabilities: [<user-provided-capabilities>]
|
|
tools: Read, Write, Bash, Grep, Glob
|
|
model: inherit
|
|
---
|
|
|
|
# <Plugin Name> Agent
|
|
|
|
You are a specialized agent for <plugin-purpose>.
|
|
|
|
## Role and Expertise
|
|
|
|
**Primary Capabilities**:
|
|
<For each capability>
|
|
- **<Capability>**: <Brief description>
|
|
</For each>
|
|
|
|
## When to Invoke
|
|
|
|
This agent should be used proactively when:
|
|
1. <Trigger scenario 1>
|
|
2. <Trigger scenario 2>
|
|
3. <Trigger scenario 3>
|
|
|
|
Users can also invoke explicitly with: "Use the <agent-name> agent to..."
|
|
|
|
## Approach and Methodology
|
|
|
|
When invoked, follow this process:
|
|
|
|
### 1. Analysis Phase
|
|
- Understand the user's request and context
|
|
- Identify relevant files and components
|
|
- Assess scope and complexity
|
|
|
|
### 2. Planning Phase
|
|
- Determine optimal approach
|
|
- Identify potential issues
|
|
- Plan step-by-step execution
|
|
|
|
### 3. Execution Phase
|
|
- Implement solution systematically
|
|
- Validate each step
|
|
- Handle errors gracefully
|
|
|
|
### 4. Verification Phase
|
|
- Test the results
|
|
- Verify completeness
|
|
- Provide clear summary
|
|
|
|
## Best Practices
|
|
|
|
- **Be Proactive**: Start working immediately when conditions match
|
|
- **Be Thorough**: Don't skip steps or make assumptions
|
|
- **Be Clear**: Explain what you're doing and why
|
|
- **Be Efficient**: Use appropriate tools for each task
|
|
- **Be Helpful**: Provide context and recommendations
|
|
|
|
## Tools Usage
|
|
|
|
- **Read**: For examining file contents
|
|
- **Write**: For creating new files
|
|
- **Edit**: For modifying existing files
|
|
- **Bash**: For executing commands and scripts
|
|
- **Grep**: For searching patterns in files
|
|
- **Glob**: For finding files by pattern
|
|
|
|
## Error Handling
|
|
|
|
When encountering errors:
|
|
1. Identify the root cause
|
|
2. Explain the issue clearly
|
|
3. Provide specific solutions
|
|
4. Offer alternatives if needed
|
|
|
|
## Output Format
|
|
|
|
Always provide:
|
|
- Clear summary of actions taken
|
|
- Results or outcomes
|
|
- Next steps or recommendations
|
|
- Any warnings or considerations
|
|
```
|
|
|
|
### 7. Generate Comprehensive README.md
|
|
|
|
Create `README.md` with all required sections:
|
|
|
|
```markdown
|
|
# <plugin-name>
|
|
|
|
<user-provided-description>
|
|
|
|
## Overview
|
|
|
|
<Expanded description explaining what the plugin does, why it's useful, and key features>
|
|
|
|
## Installation
|
|
|
|
### From OpenPlugins Marketplace
|
|
|
|
```bash
|
|
/plugin marketplace add dhofheinz/open-plugins
|
|
/plugin install <plugin-name>@open-plugins
|
|
```
|
|
|
|
### From GitHub
|
|
|
|
```bash
|
|
/plugin marketplace add github:<username>/<plugin-name>
|
|
/plugin install <plugin-name>@<marketplace-name>
|
|
```
|
|
|
|
### From Local Directory
|
|
|
|
```bash
|
|
# For development and testing
|
|
/plugin marketplace add ./<plugin-name>-test-marketplace
|
|
/plugin install <plugin-name>@<plugin-name>-test
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Commands
|
|
|
|
<For each command>
|
|
#### /<command-name>
|
|
|
|
<Description>
|
|
|
|
**Syntax**: `/<command-name> [arguments]`
|
|
|
|
**Example**:
|
|
```bash
|
|
/<command-name> arg1 arg2
|
|
```
|
|
|
|
**Options**:
|
|
- `arg1`: Description of first argument
|
|
- `arg2`: Description of second argument
|
|
</For each>
|
|
|
|
<If agent included>
|
|
### Agent
|
|
|
|
This plugin includes the `<agent-name>` agent for specialized assistance.
|
|
|
|
**Invocation**: The agent is automatically invoked when <triggers>, or you can invoke explicitly:
|
|
|
|
```
|
|
Use the <agent-name> agent to <example-task>
|
|
```
|
|
|
|
**Capabilities**:
|
|
<List capabilities>
|
|
</If agent included>
|
|
|
|
## Examples
|
|
|
|
### Example 1: <Use Case Name>
|
|
|
|
```bash
|
|
/<command-name> example-input
|
|
```
|
|
|
|
**Output**:
|
|
```
|
|
Expected output example
|
|
```
|
|
|
|
### Example 2: <Another Use Case>
|
|
|
|
```bash
|
|
/<command-name> --option value
|
|
```
|
|
|
|
## Configuration
|
|
|
|
<If plugin has configuration options>
|
|
This plugin supports configuration via:
|
|
- Plugin-specific settings
|
|
- Environment variables
|
|
- Configuration files
|
|
|
|
<Detail configuration options>
|
|
<Otherwise>
|
|
This plugin requires no additional configuration. It works out of the box.
|
|
</Otherwise>
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Issue: <Common Problem>
|
|
|
|
**Symptoms**: <Description>
|
|
|
|
**Solution**: <Step-by-step fix>
|
|
|
|
#### Issue: Command not found
|
|
|
|
**Symptoms**: `/command` returns "command not found"
|
|
|
|
**Solution**:
|
|
1. Verify plugin is installed: `/plugin list`
|
|
2. Check plugin is enabled: `/plugin info <plugin-name>`
|
|
3. Restart Claude Code to reload plugins
|
|
|
|
#### Issue: Permission denied
|
|
|
|
**Symptoms**: Operations fail with permission errors
|
|
|
|
**Solution**:
|
|
1. Check file permissions
|
|
2. Verify plugin has necessary tool access
|
|
3. Review `allowed-tools` in command frontmatter
|
|
|
|
## Development
|
|
|
|
### Local Testing
|
|
|
|
1. Create test marketplace structure:
|
|
```bash
|
|
mkdir -p <plugin-name>-test-marketplace/.claude-plugin
|
|
```
|
|
|
|
2. Create test marketplace.json:
|
|
```json
|
|
{
|
|
"name": "<plugin-name>-test",
|
|
"owner": {"name": "Test User"},
|
|
"plugins": [{
|
|
"name": "<plugin-name>",
|
|
"source": "./<plugin-name>",
|
|
"description": "<description>"
|
|
}]
|
|
}
|
|
```
|
|
|
|
3. Test installation:
|
|
```bash
|
|
/plugin marketplace add ./<plugin-name>-test-marketplace
|
|
/plugin install <plugin-name>@<plugin-name>-test
|
|
```
|
|
|
|
4. Verify functionality:
|
|
```bash
|
|
/<command-name> test-args
|
|
```
|
|
|
|
### Contributing
|
|
|
|
Contributions are welcome! To contribute:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test thoroughly
|
|
5. Submit a pull request
|
|
|
|
Please follow the [OpenPlugins Contributing Guide](https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md).
|
|
|
|
## Changelog
|
|
|
|
See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
|
|
## License
|
|
|
|
<selected-license> - see [LICENSE](LICENSE) file for details.
|
|
|
|
## Resources
|
|
|
|
- [Claude Code Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
|
- [OpenPlugins Marketplace](https://github.com/dhofheinz/open-plugins)
|
|
- [Plugin Development Guide](https://docs.claude.com/en/docs/claude-code/plugins/plugins-reference)
|
|
|
|
## Support
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/<username>/<plugin-name>/issues)
|
|
- **Discussions**: [OpenPlugins Discussions](https://github.com/dhofheinz/open-plugins/discussions)
|
|
- **Documentation**: [Plugin README](README.md)
|
|
|
|
---
|
|
|
|
**Made for [OpenPlugins](https://github.com/dhofheinz/open-plugins)** - Fostering a vibrant ecosystem of Claude Code plugins
|
|
```
|
|
|
|
### 8. Generate CHANGELOG.md
|
|
|
|
Create `CHANGELOG.md`:
|
|
|
|
```markdown
|
|
# Changelog
|
|
|
|
All notable changes to this project will be documented in this file.
|
|
|
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
|
## [1.0.0] - <current-date-YYYY-MM-DD>
|
|
|
|
### Added
|
|
- Initial release
|
|
- Core functionality for <brief-description>
|
|
<If commands>
|
|
- Command: /<command-name> - <description>
|
|
</If commands>
|
|
<If agent>
|
|
- Agent: <agent-name> - Specialized assistant for <purpose>
|
|
</If agent>
|
|
- Comprehensive documentation
|
|
- Usage examples
|
|
- MIT License
|
|
|
|
### Documentation
|
|
- README with installation and usage guide
|
|
- Example commands and configurations
|
|
- Troubleshooting section
|
|
|
|
### Quality
|
|
- Follows OpenPlugins standards
|
|
- Complete metadata in plugin.json
|
|
- No hardcoded secrets
|
|
- Input validation
|
|
```
|
|
|
|
### 9. Generate LICENSE File
|
|
|
|
Based on selected license, generate appropriate LICENSE file:
|
|
|
|
**MIT License** (default):
|
|
```
|
|
MIT License
|
|
|
|
Copyright (c) <YEAR> <author-name>
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in all
|
|
copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
SOFTWARE.
|
|
```
|
|
|
|
**Apache-2.0**: Use standard Apache 2.0 license text
|
|
**GPL-3.0**: Use standard GPL 3.0 license text
|
|
**BSD-3-Clause**: Use standard BSD 3-Clause license text
|
|
|
|
### 10. Generate .gitignore
|
|
|
|
Create `.gitignore`:
|
|
|
|
```
|
|
# Node modules (if using MCP servers)
|
|
node_modules/
|
|
package-lock.json
|
|
|
|
# Python (if using Python scripts)
|
|
__pycache__/
|
|
*.py[cod]
|
|
*$py.class
|
|
venv/
|
|
.env
|
|
|
|
# IDE
|
|
.vscode/
|
|
.idea/
|
|
*.swp
|
|
*.swo
|
|
*~
|
|
|
|
# OS
|
|
.DS_Store
|
|
Thumbs.db
|
|
|
|
# Test artifacts
|
|
test-marketplace/
|
|
*.test.md
|
|
.tmp/
|
|
|
|
# Secrets
|
|
*.key
|
|
*.pem
|
|
.env.local
|
|
secrets.json
|
|
credentials.json
|
|
|
|
# Build artifacts
|
|
dist/
|
|
build/
|
|
*.log
|
|
```
|
|
|
|
### 11. Generate Test Marketplace
|
|
|
|
Create test marketplace structure:
|
|
|
|
```
|
|
<plugin-name>-test-marketplace/
|
|
├── .claude-plugin/
|
|
│ └── marketplace.json
|
|
```
|
|
|
|
marketplace.json content:
|
|
```json
|
|
{
|
|
"name": "<plugin-name>-test",
|
|
"owner": {
|
|
"name": "<author-name>",
|
|
"email": "<author-email>"
|
|
},
|
|
"description": "Test marketplace for <plugin-name> development",
|
|
"plugins": [
|
|
{
|
|
"name": "<plugin-name>",
|
|
"version": "1.0.0",
|
|
"description": "<user-provided-description>",
|
|
"author": {
|
|
"name": "<author-name>",
|
|
"email": "<author-email>"
|
|
},
|
|
"source": "../<plugin-name>",
|
|
"license": "<selected-license>",
|
|
"keywords": [<keywords-array>],
|
|
"category": "<selected-category>"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 12. Validation
|
|
|
|
After generation, validate:
|
|
|
|
1. **JSON Syntax**: Verify plugin.json and marketplace.json are valid JSON
|
|
2. **Required Fields**: Ensure all required fields present in plugin.json
|
|
3. **File Existence**: Verify all expected files were created
|
|
4. **Name Format**: Confirm plugin name is lowercase-hyphen
|
|
5. **Category**: Validate category is one of 10 standard categories
|
|
6. **Version Format**: Confirm version follows semver (1.0.0)
|
|
|
|
If any validation fails, report the issue clearly and suggest fixes.
|
|
|
|
### 13. Output Comprehensive Instructions
|
|
|
|
Provide detailed next steps:
|
|
|
|
```
|
|
✅ Plugin "<plugin-name>" generated successfully!
|
|
|
|
📁 Plugin Location: ./<plugin-name>/
|
|
📁 Test Marketplace: ./<plugin-name>-test-marketplace/
|
|
|
|
📦 Generated Files:
|
|
✅ plugin.json - Complete metadata at plugin root
|
|
✅ commands/example.md - Template command
|
|
<If agent>✅ agents/example-agent.md - Specialized agent</If agent>
|
|
✅ README.md - Comprehensive documentation
|
|
✅ LICENSE - <license-type> license
|
|
✅ CHANGELOG.md - Version history
|
|
✅ .gitignore - Standard exclusions
|
|
✅ Test marketplace structure
|
|
|
|
📋 Next Steps:
|
|
|
|
1. 📝 Review Generated Files
|
|
- Examine plugin.json metadata
|
|
- Review command templates
|
|
<If agent>- Check agent configuration</If agent>
|
|
- Read through README
|
|
|
|
2. 💻 Implement Plugin Logic
|
|
- Edit commands/example.md with actual functionality
|
|
- Add more commands in commands/ directory as needed
|
|
<If agent>- Customize agents/example-agent.md system prompt</If agent>
|
|
- Add hooks in hooks/hooks.json if needed (optional)
|
|
- Configure MCP servers in .mcp.json if needed (optional)
|
|
|
|
3. 📖 Update Documentation
|
|
- Replace README placeholders with actual information
|
|
- Add real usage examples
|
|
- Document all command options
|
|
- Update troubleshooting section with known issues
|
|
|
|
4. 🧪 Test Locally
|
|
cd <plugin-name>-test-marketplace
|
|
|
|
# Add test marketplace
|
|
/plugin marketplace add .
|
|
|
|
# Install plugin
|
|
/plugin install <plugin-name>@<plugin-name>-test
|
|
|
|
# Test commands
|
|
/<example> test-args
|
|
|
|
# Verify agent invocation (if applicable)
|
|
<If agent>"Use the <agent-name> agent to test functionality"</If agent>
|
|
|
|
5. ✅ Validate Quality
|
|
- Test all commands work correctly
|
|
- Verify error handling is robust
|
|
- Check documentation is complete and accurate
|
|
- Ensure no hardcoded secrets
|
|
- Test on different scenarios
|
|
|
|
6. 📤 Prepare for Distribution
|
|
|
|
A. Initialize Git Repository:
|
|
cd <plugin-name>
|
|
git init
|
|
git add .
|
|
git commit -m "feat: initial plugin implementation"
|
|
git branch -M main
|
|
|
|
B. Create GitHub Repository:
|
|
gh repo create <plugin-name> --public --source=. --remote=origin
|
|
git push -u origin main
|
|
|
|
C. Tag Version:
|
|
git tag v1.0.0
|
|
git push origin v1.0.0
|
|
|
|
7. 🚀 Submit to OpenPlugins Marketplace
|
|
|
|
A. Fork OpenPlugins Repository:
|
|
gh repo fork dhofheinz/open-plugins --clone
|
|
cd open-plugins
|
|
|
|
B. Add Your Plugin Entry:
|
|
Edit .claude-plugin/marketplace.json
|
|
Add your plugin to the "plugins" array:
|
|
|
|
{
|
|
"name": "<plugin-name>",
|
|
"version": "1.0.0",
|
|
"description": "<description>",
|
|
"author": {
|
|
"name": "<author-name>",
|
|
"email": "<author-email>"<If url>,
|
|
"url": "<author-url>"</If url>
|
|
},
|
|
"source": "github:<username>/<plugin-name>",
|
|
"license": "<license>",
|
|
"keywords": [<keywords>],
|
|
"category": "<category>",
|
|
"homepage": "https://github.com/<username>/<plugin-name>",
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "https://github.com/<username>/<plugin-name>"
|
|
}
|
|
}
|
|
|
|
C. Submit Pull Request:
|
|
git checkout -b add-<plugin-name>
|
|
git add .claude-plugin/marketplace.json
|
|
git commit -m "feat: add <plugin-name> to marketplace"
|
|
git push origin add-<plugin-name>
|
|
gh pr create --title "Add <plugin-name> plugin" --body "..."
|
|
|
|
📚 Resources:
|
|
|
|
- Plugin Documentation: https://docs.claude.com/en/docs/claude-code/plugins
|
|
- OpenPlugins Marketplace: https://github.com/dhofheinz/open-plugins
|
|
- Contributing Guide: https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md
|
|
- Keep a Changelog: https://keepachangelog.com/
|
|
- Semantic Versioning: https://semver.org/
|
|
|
|
💡 Pro Tips:
|
|
|
|
- Start simple: Implement core functionality first, add features iteratively
|
|
- Test early: Use test marketplace to catch issues before submission
|
|
- Document well: Clear documentation increases adoption
|
|
- Follow standards: Adherence to OpenPlugins guidelines speeds approval
|
|
- Engage community: Share in discussions, help others, contribute back
|
|
|
|
🎯 Quality Checklist:
|
|
|
|
Before submitting to OpenPlugins, ensure:
|
|
- [ ] Plugin installs without errors
|
|
- [ ] All commands execute correctly
|
|
- [ ] Agent invokes properly (if applicable)
|
|
- [ ] README has real examples (not placeholders)
|
|
- [ ] No hardcoded secrets or credentials
|
|
- [ ] Error messages are helpful
|
|
- [ ] Documentation is complete
|
|
- [ ] Tested in multiple scenarios
|
|
- [ ] Git repository is public
|
|
- [ ] Version is tagged
|
|
|
|
❓ Need Help?
|
|
|
|
- Report issues: https://github.com/dhofheinz/open-plugins/issues
|
|
- Ask questions: https://github.com/dhofheinz/open-plugins/discussions
|
|
- Plugin docs: https://docs.claude.com/en/docs/claude-code/plugins/plugins-reference
|
|
|
|
---
|
|
|
|
🎉 Happy plugin development! Your contribution helps grow the Claude Code ecosystem.
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Invalid Plugin Name
|
|
|
|
If plugin name doesn't match `^[a-z][a-z0-9-]*[a-z0-9]$`:
|
|
|
|
```
|
|
❌ Error: Invalid plugin name "<provided-name>"
|
|
|
|
Plugin names must:
|
|
- Start with a lowercase letter
|
|
- Contain only lowercase letters, numbers, and hyphens
|
|
- End with a lowercase letter or number
|
|
- Not contain consecutive hyphens
|
|
- Not start or end with a hyphen
|
|
|
|
✅ Valid examples:
|
|
- code-formatter
|
|
- test-runner
|
|
- my-plugin
|
|
- plugin-v2
|
|
|
|
❌ Invalid examples:
|
|
- Code-Formatter (uppercase)
|
|
- test_runner (underscore)
|
|
- My Plugin (spaces)
|
|
- -plugin (starts with hyphen)
|
|
- plugin- (ends with hyphen)
|
|
|
|
Please provide a valid plugin name and try again.
|
|
```
|
|
|
|
### Description Too Short/Long
|
|
|
|
```
|
|
❌ Error: Description must be between 50 and 200 characters.
|
|
|
|
Current length: <actual-length> characters
|
|
|
|
Your description: "<provided-description>"
|
|
|
|
Tip: Be specific about what your plugin does. Avoid generic phrases.
|
|
|
|
✅ Good examples:
|
|
- "Automate code formatting using Prettier with project-specific configurations"
|
|
- "Generate comprehensive test suites for Python functions with pytest integration"
|
|
|
|
❌ Avoid:
|
|
- "A useful plugin" (too vague)
|
|
- "Plugin for stuff" (not descriptive)
|
|
```
|
|
|
|
### Invalid Category
|
|
|
|
```
|
|
❌ Error: Invalid category "<provided-category>"
|
|
|
|
Valid categories:
|
|
1. development - Code generation, scaffolding, refactoring
|
|
2. testing - Test generation, coverage, quality assurance
|
|
3. deployment - CI/CD, infrastructure, release automation
|
|
4. documentation - Docs generation, API documentation
|
|
5. security - Vulnerability scanning, secret detection
|
|
6. database - Schema design, migrations, queries
|
|
7. monitoring - Performance analysis, logging
|
|
8. productivity - Workflow automation, task management
|
|
9. quality - Linting, formatting, code review
|
|
10. collaboration - Team tools, communication
|
|
|
|
Please choose a category number (1-10) or name.
|
|
```
|
|
|
|
### Insufficient Keywords
|
|
|
|
```
|
|
❌ Error: Please provide 3-7 keywords (you provided <count>)
|
|
|
|
Keywords help users discover your plugin in the marketplace.
|
|
|
|
Guidelines:
|
|
- Use 3-7 keywords
|
|
- Focus on functionality, technology, and use cases
|
|
- Avoid generic terms (plugin, tool, utility)
|
|
- Use lowercase, comma-separated
|
|
|
|
Examples:
|
|
✅ "testing, automation, python, pytest, ci-cd"
|
|
✅ "linting, javascript, eslint, code-quality"
|
|
❌ "plugin, tool, awesome" (too generic)
|
|
❌ "test" (insufficient)
|
|
```
|
|
|
|
### File Creation Failures
|
|
|
|
If directory creation or file writing fails:
|
|
|
|
```
|
|
❌ Error: Failed to create <file-path>
|
|
|
|
Reason: <error-message>
|
|
|
|
Possible causes:
|
|
- Insufficient permissions
|
|
- Directory already exists
|
|
- Disk space full
|
|
- Invalid path
|
|
|
|
Solutions:
|
|
1. Check directory permissions: ls -la
|
|
2. Verify disk space: df -h
|
|
3. Try a different location
|
|
4. Remove existing directory if safe: rm -rf <plugin-name>
|
|
|
|
Need help? Check the troubleshooting guide:
|
|
https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md
|
|
```
|
|
|
|
### JSON Validation Failures
|
|
|
|
If generated JSON is invalid:
|
|
|
|
```
|
|
❌ Error: Generated plugin.json has invalid syntax
|
|
|
|
Location: <file-path>
|
|
|
|
Issue: <json-error>
|
|
|
|
This is likely a bug in the generator. Please:
|
|
1. Report this issue: https://github.com/dhofheinz/open-plugins/issues
|
|
2. Manually fix the JSON syntax
|
|
3. Validate with: cat plugin.json | python3 -m json.tool
|
|
|
|
We'll fix this in the next update!
|
|
```
|
|
|
|
## Implementation Notes
|
|
|
|
1. **Interactive Prompts**: Use natural language to collect user input
|
|
2. **Defaults**: Provide sensible defaults from git config when available
|
|
3. **Validation**: Validate all inputs before generating files
|
|
4. **Error Recovery**: If generation partially fails, report which files succeeded
|
|
5. **Idempotency**: Warn if plugin directory already exists, offer to overwrite
|
|
6. **Current Date**: Use actual current date for CHANGELOG.md and LICENSE
|
|
7. **Git Config**: Try to read author info from git config for better UX
|
|
8. **Relative Paths**: Generate all paths relative to current working directory
|
|
9. **Cross-Platform**: Ensure generated files work on Linux, macOS, and Windows
|
|
10. **Character Escaping**: Properly escape special characters in JSON strings
|
|
|
|
## Success Output
|
|
|
|
After successful generation, output should:
|
|
- Clearly indicate success with visual markers (✅, 📁, 📋, etc.)
|
|
- List all generated files with brief descriptions
|
|
- Provide numbered, sequential next steps
|
|
- Include both local testing AND marketplace submission workflows
|
|
- Reference relevant documentation
|
|
- Offer pro tips for success
|
|
- Include a quality checklist
|
|
- Provide links to get help
|
|
|
|
## Best Practices
|
|
|
|
1. **User Experience**: Make the process feel guided and supportive
|
|
2. **Error Messages**: Always explain WHY something failed and HOW to fix it
|
|
3. **Examples**: Provide concrete examples in all prompts
|
|
4. **Validation**: Catch errors early before generating files
|
|
5. **Documentation**: Generate comprehensive, helpful documentation
|
|
6. **Standards Compliance**: Ensure all generated files meet OpenPlugins standards
|
|
7. **Testing Support**: Make local testing easy with test marketplace
|
|
8. **Community Integration**: Guide users to OpenPlugins resources and community
|
|
|
|
---
|
|
|
|
**Remember**: This plugin generates the FIRST plugin for OpenPlugins marketplace. Quality and attention to detail are critical for setting the right standard for the entire ecosystem.
|