Initial commit
This commit is contained in:
Zhongwei Li
996
commands/quickstart-plugin.md
Normal file
996
commands/quickstart-plugin.md
Normal file
@@ -0,0 +1,996 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user