gh-dhofheinz-open-plugins-plugins-plugin-quickstart-generator/commands/quickstart-plugin.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Generate production-ready Claude Code plugin structures for OpenPlugins marketplace	<plugin-name> [category]	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:

{
  "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:

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

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

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

/plugin marketplace add github:<username>/<plugin-name>
/plugin install <plugin-name>@<marketplace-name>

From Local Directory

# For development and testing
/plugin marketplace add ./<plugin-name>-test-marketplace
/plugin install <plugin-name>@<plugin-name>-test

Usage

Commands

#### /

Syntax: /<command-name> [arguments]

Example:

/<command-name> arg1 arg2

Options:

• arg1: Description of first argument
• arg2: Description of second argument </For each>

### Agent

This plugin includes the <agent-name> agent for specialized assistance.

Invocation: The agent is automatically invoked when , or you can invoke explicitly:

Use the <agent-name> agent to <example-task>

Capabilities: </If agent included>

Examples

Example 1:

/<command-name> example-input

Output:

Expected output example

Example 2:

/<command-name> --option value

Configuration

This plugin supports configuration via: - Plugin-specific settings - Environment variables - Configuration files This plugin requires no additional configuration. It works out of the box.

Troubleshooting

Common Issues

Issue:

Symptoms:

Solution:

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:

mkdir -p <plugin-name>-test-marketplace/.claude-plugin

2. Create test marketplace.json:

{
  "name": "<plugin-name>-test",
  "owner": {"name": "Test User"},
  "plugins": [{
    "name": "<plugin-name>",
    "source": "./<plugin-name>",
    "description": "<description>"
  }]
}

3. Test installation:

/plugin marketplace add ./<plugin-name>-test-marketplace
/plugin install <plugin-name>@<plugin-name>-test

4. Verify functionality:

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

Changelog

See CHANGELOG.md for version history.

License

- see LICENSE file for details.

Resources

• Claude Code Plugin Documentation
• OpenPlugins Marketplace
• Plugin Development Guide

Support

• Issues: GitHub Issues
• Discussions: OpenPlugins Discussions
• Documentation: Plugin README

---

Made for OpenPlugins - 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:

{
  "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.