zhongwei/gh-dhofheinz-open-plugins-plugins-plugin-quickstart-generator
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:20:31 +08:00
commit 6bee51f8ec
20 changed files with 4266 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
commands/plugin-design/analyze-requirements.md Normal file
View File

@@ -0,0 +1,230 @@
---
description: Analyze user requirements and suggest optimal plugin architecture with component recommendations
---
# Analyze Plugin Requirements
## Parameters
**Required**:
- `requirements`: Description of what the plugin should do (format: quoted string)
**Optional**:
- `target_users`: Who will use this plugin (default: "developers")
- `use_case`: Primary use case category (default: "general")
## Workflow
### Step 1: Parse Requirements
Extract key information from the requirements string:
- **Core Functionality**: What is the primary purpose?
- **Operations Needed**: What specific actions will users perform?
- **Automation vs Manual**: Does it need proactive behavior or on-demand invocation?
- **External Dependencies**: Does it need external tools or APIs?
- **Complexity Indicators**: How many operations? State management needed?
### Step 2: Domain Classification
Classify the plugin into one of the OpenPlugins categories:
- `development`: Code generation, scaffolding, refactoring
- `testing`: Test generation, coverage analysis, quality assurance
- `deployment`: CI/CD, infrastructure, release automation
- `documentation`: Documentation generation, API docs
- `security`: Vulnerability scanning, secret detection
- `database`: Schema design, migrations, queries
- `monitoring`: Performance analysis, logging, observability
- `productivity`: Workflow automation, task management
- `quality`: Linting, formatting, code review
- `collaboration`: Team tools, communication integration
### Step 3: Component Analysis
Determine which components are needed:
**Commands Needed If**:
- Users need on-demand functionality
- Operations are explicitly invoked
- Simple slash command interface is sufficient
**Agents Needed If**:
- Domain expertise is required
- Automatic invocation based on context is desired
- Specialized analysis or decision-making is needed
- Conversational guidance would help users
**Hooks Needed If**:
- Automation on specific events is required
- Workflow enforcement is desired
- Actions should trigger on tool usage (Write, Edit, Bash, etc.)
- Session lifecycle management is beneficial
**MCP Servers Needed If**:
- External tool integration is required
- Custom data sources must be accessed
- API wrappers are needed
- Real-time data streaming is beneficial
### Step 4: Pattern Recognition
Match requirements to architectural patterns:
**Simple Pattern** (Single command, no orchestration):
- 1-2 operations
- Stateless execution
- No complex workflows
- Direct functionality
**Moderate Pattern** (Multiple related commands):
- 3-5 operations
- Some shared context
- Light orchestration
- May benefit from namespace organization
**Complex Pattern** (Orchestrated workflow with skill.md):
- 5+ operations
- Shared state management
- Complex argument parsing needed
- Workflows that compose multiple operations
- Benefits from intelligent routing
### Step 5: Template Selection
Recommend appropriate template:
**simple-crud Template**:
- Operations: create, read, update, delete, list
- Stateless resource management
- Minimal external dependencies
**workflow-orchestration Template**:
- Operations: start, execute, monitor, pause/resume, complete, rollback
- State machine with transitions
- Multi-step processes
**script-enhanced Template**:
- Complex logic better expressed in Python/Bash
- Performance-critical operations
- Integration with external CLI tools
**mcp-integration Template**:
- Primary purpose is exposing MCP server capabilities
- Thin wrapper with convenience arguments
- Direct mapping to MCP tools
### Step 6: Generate Analysis Report
Provide comprehensive analysis with:
- Recommended architecture pattern
- Component breakdown with rationale
- Suggested operations list
- MCP tool dependencies
- Script requirements
- Complexity assessment
- Implementation effort estimate
- Example usage patterns
## Output Format
```markdown
## Plugin Architecture Analysis
### Requirements Summary
**Core Purpose**: {extracted purpose}
**Primary Operations**: {list of operations}
**Target Category**: {OpenPlugins category}
### Recommended Architecture
**Pattern**: {Simple|Moderate|Complex}
**Template**: {template name}
### Component Breakdown
**Commands** (Required/Optional):
- {command-name}: {rationale}
**Agents** (Required/Optional):
- {agent-name}: {rationale}
**Hooks** (Required/Optional):
- {hook-event}: {rationale}
**MCP Servers** (Required/Optional):
- {server-name}: {rationale}
### Operations Design
1. **{operation-name}**: {description}
- Parameters: {params}
- Complexity: {low|medium|high}
### Script Requirements
**Utility Scripts Needed**:
- {script-name}.{ext}: {purpose}
### Implementation Estimate
- **Complexity**: {Low|Medium|High}
- **Estimated Time**: {time range}
- **Operations Count**: {number}
- **Scripts Needed**: {number}
### Next Steps
1. {actionable step 1}
2. {actionable step 2}
3. {actionable step 3}
### Example Usage After Creation
```bash
/{plugin-name} {example operation}
```
```
## Error Handling
- **Missing requirements** → Request detailed description of plugin purpose
- **Vague requirements** → Ask clarifying questions about specific functionality
- **Conflicting requirements** → Highlight conflicts and suggest resolution
- **Too broad scope** → Suggest breaking into multiple focused plugins
## Examples
### Example 1: Database Backup Plugin
**Input**:
```
requirements:"Need to automate PostgreSQL database backups with compression, encryption, and restore capabilities"
```
**Analysis**:
- Category: database
- Pattern: Complex (workflow orchestration)
- Template: workflow-orchestration
- Components: Commands (4 ops), Scripts (3 utilities)
- Operations: backup, restore, list, verify
- Scripts: connection-test.sh, compress-encrypt.py, integrity-check.sh
- Complexity: Medium
- Time: 20-30 minutes
### Example 2: Code Formatter Plugin
**Input**:
```
requirements:"Simple code formatting for Python and JavaScript files"
```
**Analysis**:
- Category: quality
- Pattern: Simple
- Template: simple-crud (adapted)
- Components: Commands (2 ops)
- Operations: format, check
- Scripts: None needed
- Complexity: Low
- Time: 10-15 minutes
**Request**: $ARGUMENTS

315
commands/plugin-design/estimate-complexity.md Normal file
View File

@@ -0,0 +1,315 @@
---
description: Assess plugin implementation complexity and estimate development effort
---
# Estimate Plugin Complexity
## Parameters
**Required**:
- `operations`: Number of operations/commands (format: integer)
**Optional**:
- `has_scripts`: Whether utility scripts are needed (format: true|false, default: false)
- `has_agents`: Whether agents are included (format: true|false, default: false)
- `has_hooks`: Whether hooks are included (format: true|false, default: false)
- `has_mcp`: Whether MCP servers are needed (format: true|false, default: false)
- `external_apis`: Number of external API integrations (format: integer, default: 0)
## Workflow
### Step 1: Calculate Base Complexity
**Operation Complexity Score**:
- 1-2 operations: Base score = 1 (Simple)
- 3-5 operations: Base score = 2 (Moderate)
- 6-8 operations: Base score = 3 (Complex)
- 9+ operations: Base score = 4 (Very Complex)
### Step 2: Apply Component Multipliers
**Complexity Multipliers**:
**Scripts** (+0.5 per script type):
- Shell scripts (.sh): +0.5
- Python scripts (.py): +0.5
- JavaScript scripts (.js): +0.5
- Average scripts needed: operations / 3 (rounded up)
**Agents** (+1.0 per agent):
- Agent design and prompting: +0.5
- Agent capabilities definition: +0.3
- Agent tool configuration: +0.2
- Testing and refinement: +0.3
- Total per agent: +1.3
**Hooks** (+0.5 per hook event):
- Hook configuration: +0.2
- Event matcher design: +0.2
- Hook script implementation: +0.3
- Testing hook triggers: +0.3
- Total per hook: +1.0
**MCP Servers** (+2.0 per server):
- Server design: +0.5
- Tool implementation: +0.8
- Configuration setup: +0.3
- Testing and debugging: +0.4
- Total per MCP server: +2.0
**External API Integrations** (+0.8 per API):
- Authentication setup: +0.3
- API wrapper implementation: +0.3
- Error handling: +0.2
- Total per API: +0.8
### Step 3: Calculate Total Complexity
**Formula**:
```
Total Complexity = Base Score
+ (script_count * 0.5)
+ (agent_count * 1.3)
+ (hook_count * 1.0)
+ (mcp_count * 2.0)
+ (api_count * 0.8)
```
**Complexity Bands**:
- 0-2: Very Low
- 2.1-4: Low
- 4.1-6: Moderate
- 6.1-8: High
- 8+: Very High
### Step 4: Estimate Time Investment
**Time Per Complexity Band**:
**Very Low (0-2)**:
- Planning: 5-10 minutes
- Implementation: 10-15 minutes
- Testing: 5-10 minutes
- Documentation: 10-15 minutes
- Total: 30-50 minutes
**Low (2.1-4)**:
- Planning: 10-15 minutes
- Implementation: 20-30 minutes
- Testing: 10-15 minutes
- Documentation: 15-20 minutes
- Total: 55-80 minutes
**Moderate (4.1-6)**:
- Planning: 15-20 minutes
- Implementation: 40-60 minutes
- Testing: 20-30 minutes
- Documentation: 20-30 minutes
- Total: 95-140 minutes (1.5-2.5 hours)
**High (6.1-8)**:
- Planning: 20-30 minutes
- Implementation: 80-120 minutes
- Testing: 30-45 minutes
- Documentation: 30-40 minutes
- Total: 160-235 minutes (2.5-4 hours)
**Very High (8+)**:
- Planning: 30-45 minutes
- Implementation: 120-180+ minutes
- Testing: 45-60 minutes
- Documentation: 40-60 minutes
- Total: 235-345+ minutes (4-6+ hours)
### Step 5: Identify Complexity Drivers
**Major Complexity Drivers**:
- High operation count (6+)
- MCP server integration (highest impact)
- Complex state management
- Multiple external APIs
- Custom hooks with sophisticated matchers
- Agent with extensive capabilities
**Risk Factors**:
- First-time MCP server development: +50% time
- Complex authentication: +30% time
- Unfamiliar external APIs: +40% time
- Testing infrastructure setup: +20% time
### Step 6: Generate Estimate Report
Provide comprehensive estimate with:
- Complexity score and band
- Time estimate with breakdown
- Complexity drivers
- Risk factors
- Recommendations for scope management
- Phased implementation plan
## Output Format
```markdown
## Plugin Complexity Estimate
### Input Parameters
- **Operations**: {count}
- **Scripts**: {yes/no} ({estimated count})
- **Agents**: {yes/no} ({count})
- **Hooks**: {yes/no} ({count})
- **MCP Servers**: {yes/no} ({count})
- **External APIs**: {count}
### Complexity Analysis
**Base Complexity**: {score} ({Simple|Moderate|Complex|Very Complex})
**Component Adjustments**:
- Scripts: +{score} ({count} scripts)
- Agents: +{score} ({count} agents)
- Hooks: +{score} ({count} hooks)
- MCP Servers: +{score} ({count} servers)
- External APIs: +{score} ({count} APIs)
**Total Complexity Score**: {total} / 10
**Complexity Band**: {Very Low|Low|Moderate|High|Very High}
### Time Estimate
**Breakdown**:
- Planning & Design: {time range}
- Implementation: {time range}
- Testing & Debugging: {time range}
- Documentation: {time range}
**Total Estimated Time**: {time range}
**Confidence Level**: {High|Medium|Low}
(Based on requirements clarity and risk factors)
### Complexity Drivers
**Major Drivers** (Highest Impact):
1. {driver 1}: {impact explanation}
2. {driver 2}: {impact explanation}
3. {driver 3}: {impact explanation}
**Minor Drivers**:
- {driver}: {impact}
### Risk Factors
**Technical Risks**:
- {risk 1}: {mitigation strategy}
- {risk 2}: {mitigation strategy}
**Time Risks**:
- {risk}: Potential +{percentage}% time increase
### Recommendations
**Scope Management**:
{Recommendations for managing complexity}
**Simplification Opportunities**:
- {opportunity 1}: Could reduce complexity by {amount}
- {opportunity 2}: Could reduce complexity by {amount}
**Phased Implementation**:
**Phase 1 (MVP)**: {time estimate}
- {core component 1}
- {core component 2}
- {core component 3}
**Phase 2 (Enhanced)**: {time estimate}
- {enhancement 1}
- {enhancement 2}
**Phase 3 (Full-Featured)**: {time estimate}
- {advanced feature 1}
- {advanced feature 2}
### Comparison to Similar Plugins
**Similar Complexity**:
- {example plugin 1}: {comparison}
- {example plugin 2}: {comparison}
**Reference Implementation Time**:
- Simple plugin (e.g., hello-world): 30-45 minutes
- Moderate plugin (e.g., code-formatter): 1-2 hours
- Complex plugin (e.g., deployment-automation): 3-5 hours
- Very complex plugin (e.g., test-framework): 5-8+ hours
### Success Factors
**To Stay On Track**:
1. {factor 1}
2. {factor 2}
3. {factor 3}
**Red Flags to Watch**:
- {warning sign 1}
- {warning sign 2}
```
## Error Handling
- **Invalid operation count** → Request valid positive integer
- **Unrealistic parameters** → Clarify actual requirements
- **Missing critical info** → Ask about components planned
- **Scope creep indicators** → Warn about complexity explosion
## Examples
### Example 1: Simple Plugin
**Input**:
```
operations:2 has_scripts:false has_agents:false has_hooks:false has_mcp:false
```
**Estimate**:
- Complexity: 1.0 (Very Low)
- Time: 30-50 minutes
- Band: Very Low
- Confidence: High
### Example 2: Moderate Plugin
**Input**:
```
operations:5 has_scripts:true has_agents:true has_hooks:false has_mcp:false
```
**Estimate**:
- Base: 2.0
- Scripts: +1.5 (3 scripts estimated)
- Agents: +1.3 (1 agent)
- Total: 4.8 (Moderate)
- Time: 90-120 minutes
- Confidence: Medium
### Example 3: Complex Plugin
**Input**:
```
operations:7 has_scripts:true has_agents:true has_hooks:true has_mcp:true external_apis:2
```
**Estimate**:
- Base: 3.0
- Scripts: +2.0 (4 scripts)
- Agents: +1.3 (1 agent)
- Hooks: +1.0 (1 hook)
- MCP: +2.0 (1 server)
- APIs: +1.6 (2 APIs)
- Total: 10.9 (Very High)
- Time: 4-6+ hours
- Confidence: Medium-Low (high complexity)
**Recommendation**: Consider phased approach, starting with core 3-4 operations
**Request**: $ARGUMENTS

389
commands/plugin-design/recommend-patterns.md Normal file
View File

@@ -0,0 +1,389 @@
---
description: Suggest architectural patterns based on plugin complexity and requirements
---
# Recommend Architectural Patterns
## Parameters
**Required**:
- `complexity`: Plugin complexity level (format: low|moderate|high)
- `features`: Number of main features/operations (format: integer)
**Optional**:
- `state_management`: Whether state management is needed (format: true|false)
- `workflows`: Whether multi-step workflows are needed (format: true|false)
- `external_integration`: Whether external tools are involved (format: true|false)
## Workflow
### Step 1: Assess Complexity Level
**Complexity Classification**:
**Low Complexity**:
- 1-2 operations
- Stateless execution
- Simple input/output
- No external dependencies
- Direct functionality
**Moderate Complexity**:
- 3-5 operations
- Some state tracking
- Light orchestration needed
- Few external dependencies
- May have related operations
**High Complexity**:
- 6+ operations
- State management required
- Complex workflows
- Multiple external dependencies
- Operations compose together
### Step 2: Pattern Matching
**Pattern 1: Simple Plugin (Single Command)**
**When to Use**:
- Complexity: Low
- Features: 1-2
- State management: No
- Workflows: No
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ └── command.md
└── README.md
```
**Characteristics**:
- Single .md file in commands/
- No skill.md router
- Direct invocation: /{command-name}
- Straightforward implementation
**Example Use Cases**:
- Hello World plugin
- Simple formatters
- Basic converters
- Quick utilities
**Pattern 2: Namespace Plugin (Multiple Independent Commands)**
**When to Use**:
- Complexity: Low to Moderate
- Features: 3-5
- State management: No or minimal
- Workflows: Independent operations
- Commands don't need orchestration
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ ├── operation1.md
│ ├── operation2.md
│ ├── operation3.md
│ └── operation4.md
└── README.md
```
**Characteristics**:
- Multiple .md files, NO skill.md
- Each command independently invokable
- Namespace prefix: /{plugin-name}:operation
- Grouped by domain but independent
**Example Use Cases**:
- Multiple formatters (format-python, format-js, format-css)
- Independent utilities collection
- Toolbox plugins
**Pattern 3: Skill Plugin (Orchestrated Operations)**
**When to Use**:
- Complexity: Moderate to High
- Features: 5+
- State management: Yes
- Workflows: Operations share context
- Need intelligent routing
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ ├── skill.md (router)
│ ├── operation1.md
│ ├── operation2.md
│ ├── operation3.md
│ └── operation4.md
└── README.md
```
**Characteristics**:
- skill.md acts as intelligent router
- Sub-commands are instruction modules (not directly invokable)
- Single entry point: /{plugin-name} operation args
- Parses arguments and routes internally
**Example Use Cases**:
- Database management (backup, restore, migrate, verify)
- Deployment pipelines (build, test, deploy, rollback)
- Multi-step workflows
**Pattern 4: Script-Enhanced Plugin**
**When to Use**:
- Complexity: Moderate to High
- Features: Any number
- External tools: Yes
- Performance critical: Yes
- Complex logic better in scripts
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ ├── skill.md (if orchestrated)
│ ├── operation1.md
│ ├── operation2.md
│ └── .scripts/
│ ├── utility1.sh
│ ├── utility2.py
│ └── utility3.js
└── README.md
```
**Characteristics**:
- Commands leverage utility scripts
- Scripts handle complex/repeated logic
- Better performance for intensive tasks
- Reusable across operations
**Example Use Cases**:
- Database operations with connection pooling
- File processing pipelines
- External tool integrations
**Pattern 5: Agent-Enhanced Plugin**
**When to Use**:
- Complexity: Any
- Domain expertise needed: Yes
- Guidance beneficial: Yes
- Proactive behavior desired: Yes
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ └── {command files}
├── agents/
│ └── specialist.md
└── README.md
```
**Characteristics**:
- Agent provides domain expertise
- Proactive invocation based on context
- Conversational guidance
- Works alongside commands
**Example Use Cases**:
- Code review automation
- Security analysis
- Performance optimization
- Architecture guidance
**Pattern 6: Full-Featured Plugin**
**When to Use**:
- Complexity: High
- Features: 6+
- All capabilities needed: Yes
**Structure**:
```
plugin-name/
├── plugin.json
├── commands/
│ ├── skill.md
│ ├── {operations}
│ └── .scripts/
│ └── {utilities}
├── agents/
│ └── specialist.md
├── hooks/
│ └── hooks.json
└── README.md
```
**Characteristics**:
- Complete plugin with all components
- Commands + Agent + Hooks + Scripts
- Maximum functionality
- Production-grade plugin
**Example Use Cases**:
- Comprehensive testing frameworks
- Full deployment automation
- Complete quality assurance systems
### Step 3: Template Mapping
**Map pattern to template**:
- **Simple Plugin** → No template needed (direct implementation)
- **Namespace Plugin** → No template needed (direct implementation)
- **Skill Plugin (CRUD-like)** → simple-crud template
- **Skill Plugin (Workflow)** → workflow-orchestration template
- **Script-Enhanced** → script-enhanced template
- **MCP Integration** → mcp-integration template
### Step 4: Provide Recommendations
Generate recommendations with:
- Recommended pattern with justification
- Alternative patterns with trade-offs
- Template to use (if applicable)
- Structure diagram
- Implementation guidance
- Example usage
## Output Format
```markdown
## Architectural Pattern Recommendations
### Analysis
**Complexity Level**: {low|moderate|high}
**Features Count**: {number}
**State Management**: {needed|not needed}
**Workflows**: {needed|not needed}
**External Integration**: {needed|not needed}
### Recommended Pattern: {Pattern Name}
**Why This Pattern**:
{Detailed justification based on requirements}
**Template**: {template-name or "Direct implementation"}
**Structure**:
```
{Directory structure diagram}
```
**Key Characteristics**:
- {characteristic 1}
- {characteristic 2}
- {characteristic 3}
**Implementation Steps**:
1. {step 1}
2. {step 2}
3. {step 3}
**Usage After Implementation**:
```bash
{Example commands}
```
### Alternative Patterns
#### Alternative 1: {Pattern Name}
**When to Consider**:
{Conditions where this might be better}
**Trade-offs**:
- Pros: {advantages}
- Cons: {disadvantages}
#### Alternative 2: {Pattern Name}
**When to Consider**:
{Conditions where this might be better}
**Trade-offs**:
- Pros: {advantages}
- Cons: {disadvantages}
### Pattern Comparison
| Aspect | Recommended | Alt 1 | Alt 2 |
|--------|------------|-------|-------|
| Complexity | {rating} | {rating} | {rating} |
| Maintainability | {rating} | {rating} | {rating} |
| Extensibility | {rating} | {rating} | {rating} |
| Learning Curve | {rating} | {rating} | {rating} |
### Migration Path
**If Requirements Change**:
- **Scale Up**: {How to add more features}
- **Scale Down**: {How to simplify}
- **Pivot**: {How to change direction}
### Best Practices for This Pattern
1. {Best practice 1}
2. {Best practice 2}
3. {Best practice 3}
```
## Error Handling
- **Invalid complexity level** → Request valid value: low|moderate|high
- **Features count unrealistic** → Clarify actual feature count
- **Conflicting parameters** → Highlight conflicts and suggest resolution
- **Unclear requirements** → Ask clarifying questions
## Examples
### Example 1: Low Complexity, Few Features
**Input**:
```
complexity:low features:2 state_management:false workflows:false
```
**Recommendation**:
- **Pattern**: Simple Plugin (Single Command) or Namespace
- **Template**: Direct implementation
- **Rationale**: Few features, no orchestration needed
### Example 2: Moderate Complexity, Workflow
**Input**:
```
complexity:moderate features:5 state_management:true workflows:true
```
**Recommendation**:
- **Pattern**: Skill Plugin with skill.md router
- **Template**: workflow-orchestration
- **Rationale**: Multiple operations sharing state, needs orchestration
### Example 3: High Complexity, External Tools
**Input**:
```
complexity:high features:7 external_integration:true workflows:true
```
**Recommendation**:
- **Pattern**: Full-Featured Plugin (Commands + Scripts + Agent)
- **Template**: script-enhanced + workflow-orchestration
- **Rationale**: Complex workflows with external integration needs utility scripts and expert guidance
**Request**: $ARGUMENTS

286
commands/plugin-design/select-components.md Normal file
View File

@@ -0,0 +1,286 @@
---
description: Determine which plugin components to use based on functionality requirements
---
# Select Plugin Components
## Parameters
**Required**:
- `purpose`: Plugin's primary purpose (format: quoted string)
- `features`: Comma-separated list of features (format: "feat1,feat2,feat3")
**Optional**:
- `automation`: Whether proactive behavior is needed (format: true|false, default: false)
- `external_tools`: External tools/APIs needed (format: "tool1,tool2")
## Workflow
### Step 1: Feature Analysis
Parse the features list and categorize each feature:
- **User-Initiated Actions**: Operations triggered by explicit user command
- **Proactive Behaviors**: Actions that should happen automatically
- **Background Tasks**: Long-running or scheduled operations
- **Interactive Workflows**: Multi-step conversational processes
### Step 2: Commands Assessment
**Evaluate Need for Commands**:
Commands are appropriate when:
- Users need explicit control over when operations execute
- Functionality is invoked via slash commands
- Operations are discrete and independent
- Simple input/output pattern
**Command Organization**:
- **Single Command**: 1-2 simple operations
- **Namespace**: 3-5 independent operations
- **Skill with skill.md**: 5+ operations needing intelligent routing
**Recommendation Logic**:
```
IF features_count <= 2 AND simple_operations:
RECOMMEND: Single command
ELSE IF features_count <= 5 AND independent_operations:
RECOMMEND: Namespace (commands directory without skill.md)
ELSE:
RECOMMEND: Skill with skill.md router
```
### Step 3: Agents Assessment
**Evaluate Need for Agents**:
Agents are appropriate when:
- Domain expertise would benefit users
- Automatic invocation based on context is valuable
- Guidance and recommendations are needed
- Analysis and decision-making support users
**Agent Design Questions**:
1. Does the plugin domain require specialized knowledge?
2. Would users benefit from conversational guidance?
3. Should the plugin proactively suggest actions?
4. Is there a workflow that needs expert orchestration?
**Recommendation**:
- **Yes to 2+ questions** → Include agent
- **Yes to 1 question** → Consider optional agent
- **No to all** → Commands only sufficient
**Agent Capabilities Mapping**:
Map features to agent capabilities:
- Code analysis → code-review, security-analysis
- Testing → test-generation, coverage-analysis
- Deployment → deployment-orchestration, rollback-management
- Documentation → doc-generation, api-documentation
### Step 4: Hooks Assessment
**Evaluate Need for Hooks**:
Hooks are appropriate when:
- Automation should trigger on specific events
- Workflow enforcement is needed
- Actions should happen transparently
- Quality gates need to be enforced
**Hook Event Mapping**:
- **PostToolUse**: After Write, Edit, Bash, etc.
- **PreToolUse**: Before Write, Edit, etc. (for validation)
- **SessionStart**: Plugin initialization
- **SessionEnd**: Cleanup and reporting
**Common Hook Patterns**:
- **Auto-format on Write**: PostToolUse with Write matcher
- **Lint before commit**: PreToolUse with Bash(git commit) matcher
- **Auto-test on code change**: PostToolUse with Edit matcher
- **Session report**: SessionEnd hook
**Recommendation Logic**:
```
IF automation == true OR workflow_enforcement_needed:
IDENTIFY triggering events
RECOMMEND appropriate hooks
ELSE:
RECOMMEND: Hooks not needed
```
### Step 5: MCP Servers Assessment
**Evaluate Need for MCP Servers**:
MCP servers are appropriate when:
- Plugin needs to integrate external tools not available in Claude Code
- Custom data sources must be accessed
- Specialized APIs need to be wrapped
- Real-time data or streaming is required
- Complex state management across sessions
**MCP Use Cases**:
- **Database Operations**: Dedicated database MCP server
- **Cloud Services**: AWS, GCP, Azure API wrappers
- **Custom Tools**: Internal tools integration
- **Data Processing**: Specialized data pipelines
- **Monitoring**: Metrics and logging services
**Recommendation Logic**:
```
IF external_tools specified:
FOR each tool:
CHECK if native Claude Code tool exists
IF not:
RECOMMEND MCP server
ELSE IF complex_external_integration:
RECOMMEND MCP server design
ELSE:
RECOMMEND: MCP servers not needed
```
### Step 6: Generate Component Recommendations
Create comprehensive component selection report with:
- Recommended components with justification
- Component interaction diagram
- Implementation priority
- Alternative approaches
- Trade-offs and considerations
## Output Format
```markdown
## Component Selection Recommendations
### Plugin Purpose
**Primary Goal**: {purpose}
**Features**: {features list}
**Automation Needed**: {yes/no}
**External Tools**: {tools list}
### Recommended Components
#### Commands ✅ Recommended / ❌ Not Needed
**Decision**: {Recommended|Not Needed}
**Rationale**: {explanation}
**Organization**:
- {Single Command|Namespace|Skill with Router}
**Operations**:
1. **{operation-name}**: {description}
- Invocation: `/{plugin-name} {operation} {args}`
- Complexity: {low|medium|high}
#### Agents ✅ Recommended / ⚠️ Optional / ❌ Not Needed
**Decision**: {Recommended|Optional|Not Needed}
**Rationale**: {explanation}
**Agent Design**:
- **Name**: {agent-name}
- **Description**: {when to invoke description}
- **Capabilities**: {capabilities list}
- **Proactive Triggers**: {trigger conditions}
#### Hooks ✅ Recommended / ❌ Not Needed
**Decision**: {Recommended|Not Needed}
**Rationale**: {explanation}
**Hook Configuration**:
- **Event**: {PostToolUse|PreToolUse|SessionStart|SessionEnd}
- **Matcher**: {regex pattern}
- **Action**: {what happens}
#### MCP Servers ✅ Recommended / ❌ Not Needed
**Decision**: {Recommended|Not Needed}
**Rationale**: {explanation}
**Server Design**:
- **Server Name**: {server-name}
- **Purpose**: {what it provides}
- **Tools Exposed**: {tool list}
### Component Interaction Flow
```
{Describe how components interact}
Example:
1. User invokes /{plugin-name} {operation}
2. Command validates input
3. Agent provides guidance if complex
4. Hook triggers on completion
5. MCP server performs external integration
```
### Implementation Priority
1. **Phase 1**: {Core components to build first}
2. **Phase 2**: {Enhancement components}
3. **Phase 3**: {Optional components}
### Alternative Approaches
**If simpler**: {simpler alternative}
**If more robust**: {more complex alternative}
### Trade-offs
**Pros**:
- {advantage 1}
- {advantage 2}
**Cons**:
- {consideration 1}
- {consideration 2}
```
## Error Handling
- **Unclear purpose** → Request clearer description of plugin goal
- **Feature list too broad** → Suggest focusing on core functionality
- **Conflicting requirements** → Highlight conflicts and suggest resolution
- **Missing critical info** → Ask targeted questions
## Examples
### Example 1: Code Quality Plugin
**Input**:
```
purpose:"Automated code quality enforcement"
features:"lint,format,security-scan,complexity-analysis"
automation:true
```
**Recommendations**:
- **Commands**: Yes (Skill with skill.md router, 4 operations)
- **Agents**: Yes (code-reviewer agent for proactive analysis)
- **Hooks**: Yes (PostToolUse on Write/Edit for auto-lint)
- **MCP Servers**: No (native tools sufficient)
### Example 2: Simple Greeting Plugin
**Input**:
```
purpose:"Greet users with personalized messages"
features:"greet"
automation:false
```
**Recommendations**:
- **Commands**: Yes (Single command)
- **Agents**: No (too simple)
- **Hooks**: No (user-initiated only)
- **MCP Servers**: No (no external integration)
**Request**: $ARGUMENTS

52
commands/plugin-design/skill.md Normal file
View File

@@ -0,0 +1,52 @@
---
description: Guide users through plugin architecture decisions and component selection for Claude Code plugins
---
# Plugin Design Skill
Expert guidance for designing Claude Code plugin architecture with optimal component selection and pattern recommendations.
## Operations
- **analyze** - Analyze requirements and suggest optimal architecture
- **select-components** - Determine which components to use (commands, agents, hooks, MCP)
- **recommend** - Suggest architectural patterns based on complexity
- **estimate** - Assess implementation complexity and effort
## Usage Examples
```bash
# Analyze requirements
/plugin-design analyze requirements:"Need to automate database backups with scheduling"
# Get component recommendations
/plugin-design select-components purpose:"Code quality automation" features:"lint,format,review"
# Get pattern recommendations
/plugin-design recommend complexity:moderate features:3
# Estimate implementation effort
/plugin-design estimate operations:5 has_scripts:true has_agents:true
```
## Router Logic
Parse the first word of $ARGUMENTS to determine the requested operation:
1. Extract operation from first word of $ARGUMENTS
2. Parse remaining arguments as key:value parameters
3. Route to appropriate operation file:
- "analyze" → Read and execute `{plugin-path}/commands/plugin-design/analyze-requirements.md`
- "select-components" → Read and execute `{plugin-path}/commands/plugin-design/select-components.md`
- "recommend" → Read and execute `{plugin-path}/commands/plugin-design/recommend-patterns.md`
- "estimate" → Read and execute `{plugin-path}/commands/plugin-design/estimate-complexity.md`
**Error Handling**:
- If operation unknown → List available operations with usage examples
- If parameters missing → Request parameters with expected format
- If requirements unclear → Ask clarifying questions
**Base directory**: Plugin commands directory
**Current request**: $ARGUMENTS
Parse operation and route to appropriate instruction file now.

37
commands/plugin-metadata/.scripts/validate-semver.sh Executable file
View File

@@ -0,0 +1,37 @@
#!/bin/bash
# Script: validate-semver.sh
# Purpose: Validate semantic versioning format
# Version: 1.0.0
#
# Usage: ./validate-semver.sh <version>
# Returns: 0 - Valid semver, 1 - Invalid format
VERSION="$1"
if [ -z "$VERSION" ]; then
echo "ERROR: Version required"
exit 2
fi
# Semantic versioning pattern: MAJOR.MINOR.PATCH with optional pre-release and build metadata
SEMVER_PATTERN='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$'
if echo "$VERSION" | grep -Eq "$SEMVER_PATTERN"; then
echo "✅ Valid semantic version: $VERSION"
exit 0
else
echo "❌ Invalid semantic version: $VERSION"
echo ""
echo "Semantic versioning format: MAJOR.MINOR.PATCH"
echo " - MAJOR: Breaking changes"
echo " - MINOR: New features (backwards compatible)"
echo " - PATCH: Bug fixes"
echo ""
echo "Valid examples:"
echo " - 1.0.0"
echo " - 2.1.3"
echo " - 1.0.0-alpha"
echo " - 1.0.0-beta.1"
echo " - 1.0.0+20250113"
exit 1
fi

40
commands/plugin-metadata/skill.md Normal file
View File

@@ -0,0 +1,40 @@
---
description: Create, validate, and update plugin metadata including plugin.json and marketplace entries
---
# Plugin Metadata Skill
Expert metadata management for Claude Code plugins with validation, versioning, and marketplace entry generation.
## Operations
- **validate** - Validate plugin.json completeness and correctness
- **update-version** - Update version with semantic versioning validation
- **add-keywords** - Add or update keywords for plugin discoverability
- **marketplace-entry** - Generate marketplace.json plugin entry
## Usage Examples
```bash
# Validate metadata
/plugin-metadata validate plugin:my-plugin
# Update version
/plugin-metadata update-version plugin:my-plugin version:1.1.0
# Add keywords
/plugin-metadata add-keywords plugin:my-plugin keywords:"testing,automation,python"
# Generate marketplace entry
/plugin-metadata marketplace-entry plugin:my-plugin source:"github:username/plugin-name"
```
## Router Logic
Parse operation from $ARGUMENTS and route to appropriate instruction file:
- "validate" → `{plugin-path}/commands/plugin-metadata/validate-metadata.md`
- "update-version" → `{plugin-path}/commands/plugin-metadata/update-version.md`
- "add-keywords" → `{plugin-path}/commands/plugin-metadata/add-keywords.md`
- "marketplace-entry" → `{plugin-path}/commands/plugin-metadata/create-marketplace-entry.md`
**Current request**: $ARGUMENTS

58
commands/plugin-quality/.scripts/secret-scanner.sh Executable file
View File

@@ -0,0 +1,58 @@
#!/bin/bash
# Script: secret-scanner.sh
# Purpose: Scan plugin files for hardcoded secrets and credentials
# Version: 1.0.0
#
# Usage: ./secret-scanner.sh <plugin-path>
# Returns: 0 - No secrets found, 1 - Secrets detected
PLUGIN_PATH="$1"
if [ -z "$PLUGIN_PATH" ]; then
echo "ERROR: Plugin path required"
exit 2
fi
ISSUES_FOUND=0
# Patterns to search for
declare -a PATTERNS=(
"api[_-]?key['\"]?\s*[:=]"
"apikey['\"]?\s*[:=]"
"secret[_-]?key['\"]?\s*[:=]"
"password['\"]?\s*[:=]\s*['\"][^'\"]{8,}"
"token['\"]?\s*[:=]\s*['\"][a-zA-Z0-9]{20,}"
"AKIA[0-9A-Z]{16}" # AWS Access Key
"AIza[0-9A-Za-z\\-_]{35}" # Google API Key
"sk-[a-zA-Z0-9]{48}" # OpenAI API Key
"ghp_[a-zA-Z0-9]{36}" # GitHub Personal Access Token
"-----BEGIN.*PRIVATE KEY-----" # Private keys
"mongodb://.*:.*@" # MongoDB connection strings
"postgres://.*:.*@" # PostgreSQL connection strings
)
echo "🔍 Scanning for hardcoded secrets..."
echo ""
for pattern in "${PATTERNS[@]}"; do
matches=$(grep -r -i -E "$pattern" "$PLUGIN_PATH" --exclude-dir=.git --exclude="*.log" 2>/dev/null | grep -v "secret-scanner.sh" || true)
if [ -n "$matches" ]; then
echo "⚠️ Potential secret found matching pattern: $pattern"
echo "$matches"
echo ""
ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
done
if [ $ISSUES_FOUND -eq 0 ]; then
echo "✅ No hardcoded secrets detected"
exit 0
else
echo "❌ Found $ISSUES_FOUND potential secret(s)"
echo ""
echo "Recommendations:"
echo " - Use environment variables for sensitive data"
echo " - Store secrets in .env files (add to .gitignore)"
echo " - Use secure credential management"
exit 1
fi

267
commands/plugin-quality/full-audit.md Normal file
View File

@@ -0,0 +1,267 @@
---
description: Run comprehensive quality audit on plugin with scoring and recommendations
---
# Full Plugin Quality Audit
## Parameters
**Required**:
- `plugin`: Plugin name or path to plugin directory
**Optional**:
- `strict`: Enable strict mode for marketplace submission (format: true|false, default: false)
- `report_format`: Output format (format: text|json|markdown, default: markdown)
## Workflow
### Step 1: File Structure Validation
Check directory structure compliance:
```bash
.scripts/structure-checker.sh "{plugin_path}"
```
**Checks**:
- ✅ `plugin.json` exists at plugin root
- ✅ `README.md` exists and not empty
- ✅ `LICENSE` file exists
- ✅ `commands/` directory exists
- ✅ At least one command file present
- ✅ Proper naming: lowercase-hyphen format
- ✅ No invalid file types in root
**Score**: 0-20 points
### Step 2: Metadata Validation
Validate plugin.json completeness:
```bash
python3 -m json.tool "{plugin_path}/plugin.json"
```
**Checks**:
- ✅ Valid JSON syntax
- ✅ Required fields present: name, version, description, author, license
- ✅ Name format correct (lowercase-hyphen)
- ✅ Version valid semver
- ✅ Description 50-200 characters
- ✅ Author has name (email optional)
- ✅ License is standard (MIT, Apache-2.0, etc.)
- ✅ Keywords present (3-7 recommended)
- ✅ Category valid (one of 10 categories)
- ✅ Repository URL if provided is valid
**Score**: 0-25 points
### Step 3: Security Scan
Scan for security issues:
```bash
.scripts/secret-scanner.sh "{plugin_path}"
```
**Checks**:
- ✅ No hardcoded API keys
- ✅ No exposed passwords or tokens
- ✅ No AWS/GCP credentials
- ✅ No private keys
- ✅ No database connection strings
- ✅ Environment variables used for secrets
- ✅ No eval() or exec() in scripts
- ✅ No unvalidated user input
- ✅ HTTPS for external URLs
- ✅ Safe file path handling
**Score**: 0-25 points (Critical: -50 if secrets found)
### Step 4: Documentation Quality
Validate documentation completeness:
```bash
.scripts/doc-validator.py "{plugin_path}/README.md"
```
**Checks**:
- ✅ README has title matching plugin name
- ✅ Description section present
- ✅ Installation instructions (at least one method)
- ✅ Usage section with examples
- ✅ No placeholder text ("TODO", "Add description here")
- ✅ Concrete examples (not generic)
- ✅ Parameters documented
- ✅ License referenced
- ✅ Links are valid (no 404s)
- ✅ Code blocks properly formatted
**Score**: 0-20 points
### Step 5: Functional Validation
Check command/agent functionality:
**Commands**:
- ✅ All commands have description frontmatter
- ✅ Clear usage instructions
- ✅ Parameter documentation
- ✅ Error handling mentioned
- ✅ Examples provided
**Agents** (if present):
- ✅ Name field present
- ✅ Description describes when to invoke
- ✅ Capabilities listed
- ✅ Tools specified or inherited
**Score**: 0-10 points
### Step 6: Calculate Overall Score
**Total Score**: 0-100 points
**Grade Bands**:
- 90-100: Excellent (A) - Marketplace ready
- 80-89: Good (B) - Minor improvements needed
- 70-79: Satisfactory (C) - Several improvements needed
- 60-69: Needs Work (D) - Major issues to address
- 0-59: Failing (F) - Not ready for submission
### Step 7: Generate Audit Report
Provide comprehensive report with:
- Overall score and grade
- Category scores breakdown
- Passed checks list
- Failed checks list
- Warnings
- Recommendations prioritized
- Pre-submission checklist status
## Output Format
```markdown
# Plugin Quality Audit Report
## Overall Score: {score}/100 ({grade})
**Status**: {Marketplace Ready|Needs Minor Improvements|Needs Major Improvements|Not Ready}
---
## Category Scores
### File Structure: {score}/20 ✅|⚠️|❌
{Detailed findings}
### Metadata Quality: {score}/25 ✅|⚠️|❌
{Detailed findings}
### Security: {score}/25 ✅|⚠️|❌
{Detailed findings}
### Documentation: {score}/20 ✅|⚠️|❌
{Detailed findings}
### Functionality: {score}/10 ✅|⚠️|❌
{Detailed findings}
---
## Validation Results
### ✅ Passed Checks ({count})
- {check 1}
- {check 2}
...
### ❌ Failed Checks ({count})
- {check 1}: {issue description}
- **Fix**: {how to fix}
- {check 2}: {issue description}
- **Fix**: {how to fix}
### ⚠️ Warnings ({count})
- {warning 1}: {description}
- {warning 2}: {description}
---
## Recommendations
### Critical (Fix Before Submission)
1. {critical issue 1}
- Current: {what's wrong}
- Required: {what's needed}
- Example: {how to fix}
### Important (Strongly Recommended)
1. {important issue 1}
- Impact: {why it matters}
- Suggestion: {how to improve}
### Nice to Have (Optional Enhancements)
1. {enhancement 1}
- Benefit: {what it adds}
---
## Pre-Submission Checklist
- [{✅|❌}] Plugin name follows lowercase-hyphen format
- [{✅|❌}] Description is 50-200 characters and specific
- [{✅|❌}] All required metadata fields present
- [{✅|❌}] README has real content (no placeholders)
- [{✅|❌}] LICENSE file included
- [{✅|❌}] At least one functional command
- [{✅|❌}] No hardcoded secrets or credentials
- [{✅|❌}] Examples are concrete and realistic
- [{✅|❌}] Documentation complete and accurate
- [{✅|❌}] Category correctly selected
---
## Next Steps
{Prioritized action items based on audit results}
1. **Immediate**: {must-do items}
2. **Short-term**: {should-do items}
3. **Enhancement**: {nice-to-have items}
---
## Resources
- Fix Common Issues: https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md
- Quality Standards: https://github.com/dhofheinz/open-plugins/blob/main/QUALITY.md
- Examples: Browse OpenPlugins marketplace for reference implementations
---
**Audit completed**: {timestamp}
**Plugin**: {plugin_name} v{version}
**Auditor**: plugin-quality skill
```
## Error Handling
- **Plugin not found** → Check path and plugin name
- **Invalid plugin structure** → Must have plugin.json at plugin root
- **Permission errors** → Check file permissions
- **Script execution fails** → Report specific script and error
## Examples
### Example 1: High Quality Plugin
**Input**: `/plugin-quality full-audit plugin:test-generator`
**Output**: Score 92/100 (A) - Marketplace ready with minor suggestions
### Example 2: Plugin Needs Work
**Input**: `/plugin-quality full-audit plugin:my-plugin strict:true`
**Output**: Score 65/100 (D) - Multiple issues identified with detailed fixes
**Request**: $ARGUMENTS

45
commands/plugin-quality/skill.md Normal file
View File

@@ -0,0 +1,45 @@
---
description: Validate plugins against OpenPlugins quality standards with security scanning and documentation checks
---
# Plugin Quality Assurance Skill
Comprehensive quality validation for Claude Code plugins ensuring OpenPlugins marketplace standards.
## Operations
- **security** - Scan for hardcoded secrets and unsafe practices
- **docs** - Validate README completeness and documentation quality
- **structure** - Validate directory structure and file organization
- **metadata** - Lint JSON and frontmatter validation
- **full-audit** - Run complete quality audit with scoring
## Usage Examples
```bash
# Security scan
/plugin-quality security plugin:my-plugin
# Documentation check
/plugin-quality docs plugin:my-plugin
# Structure validation
/plugin-quality structure plugin:my-plugin
# Metadata validation
/plugin-quality metadata plugin:my-plugin
# Full quality audit
/plugin-quality full-audit plugin:my-plugin
```
## Router Logic
Parse operation from $ARGUMENTS and route to appropriate instruction file:
- "security" → `{plugin-path}/commands/plugin-quality/check-security.md`
- "docs" → `{plugin-path}/commands/plugin-quality/validate-documentation.md`
- "structure" → `{plugin-path}/commands/plugin-quality/check-structure.md`
- "metadata" → `{plugin-path}/commands/plugin-quality/lint-metadata.md`
- "full-audit" → `{plugin-path}/commands/plugin-quality/full-audit.md`
**Current request**: $ARGUMENTS

223
commands/plugin-scaffold/.scripts/generate-metadata.py Executable file
View File

@@ -0,0 +1,223 @@
#!/usr/bin/env python3
"""
Script: generate-metadata.py
Purpose: Generate plugin.json metadata from parameters
Version: 1.0.0
Last Modified: 2025-10-13
Usage:
./generate-metadata.py --name <name> --author <author> --description <desc> --license <license>
Returns:
0 - Success, JSON written to stdout
1 - Validation error
2 - Missing required arguments
Dependencies:
- python3 (3.7+)
- json module (standard library)
"""
import json
import sys
import argparse
import re
from datetime import datetime
# OpenPlugins standard categories
VALID_CATEGORIES = [
"development", "testing", "deployment", "documentation",
"security", "database", "monitoring", "productivity",
"quality", "collaboration"
]
VALID_LICENSES = ["MIT", "Apache-2.0", "GPL-3.0", "BSD-3-Clause", "ISC", "LGPL-3.0"]
def parse_author(author_string):
"""Parse author string into name and email components."""
# Pattern: "Name <email>" or "Name" or "Name (email)"
email_pattern = r'<([^>]+)>'
paren_pattern = r'\(([^\)]+)\)'
name = author_string
email = None
# Check for <email> format
email_match = re.search(email_pattern, author_string)
if email_match:
email = email_match.group(1)
name = author_string[:email_match.start()].strip()
else:
# Check for (email) format
paren_match = re.search(paren_pattern, author_string)
if paren_match:
email = paren_match.group(1)
name = author_string[:paren_match.start()].strip()
result = {"name": name}
if email:
result["email"] = email
return result
def generate_keywords(name, description, category):
"""Generate relevant keywords from name, description, and category."""
keywords = []
# Add category
keywords.append(category)
# Extract keywords from name
name_parts = name.split('-')
for part in name_parts:
if len(part) > 3 and part not in ['plugin', 'claude', 'code']:
keywords.append(part)
# Extract keywords from description (simple approach)
desc_words = re.findall(r'\b[a-z]{4,}\b', description.lower())
common_words = {'with', 'from', 'this', 'that', 'have', 'will', 'your', 'for'}
for word in desc_words[:3]: # Take first 3 meaningful words
if word not in common_words and word not in keywords:
keywords.append(word)
# Ensure 3-7 keywords
return keywords[:7]
def validate_name(name):
"""Validate plugin name format."""
pattern = r'^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$'
if not re.match(pattern, name):
return False, "Plugin name must be lowercase with hyphens only"
if '--' in name:
return False, "Plugin name cannot contain consecutive hyphens"
if len(name) < 3 or len(name) > 50:
return False, "Plugin name must be 3-50 characters"
return True, None
def validate_description(description):
"""Validate description length and content."""
length = len(description)
if length < 50:
return False, f"Description too short ({length} chars, minimum 50)"
if length > 200:
return False, f"Description too long ({length} chars, maximum 200)"
return True, None
def generate_metadata(args):
"""Generate complete plugin.json metadata."""
# Validate name
valid, error = validate_name(args.name)
if not valid:
print(f"ERROR: {error}", file=sys.stderr)
return None
# Validate description
valid, error = validate_description(args.description)
if not valid:
print(f"ERROR: {error}", file=sys.stderr)
return None
# Validate license
if args.license not in VALID_LICENSES:
print(f"ERROR: Invalid license. Must be one of: {', '.join(VALID_LICENSES)}", file=sys.stderr)
return None
# Validate category
if args.category not in VALID_CATEGORIES:
print(f"ERROR: Invalid category. Must be one of: {', '.join(VALID_CATEGORIES)}", file=sys.stderr)
return None
# Parse author
author = parse_author(args.author)
# Generate or use provided keywords
if args.keywords:
keywords = [k.strip() for k in args.keywords.split(',')]
else:
keywords = generate_keywords(args.name, args.description, args.category)
# Build metadata object
metadata = {
"name": args.name,
"version": args.version,
"description": args.description,
"author": author,
"license": args.license
}
# Add optional fields if provided
if args.repository:
metadata["repository"] = {
"type": "git",
"url": args.repository
}
elif args.github_username:
metadata["repository"] = {
"type": "git",
"url": f"https://github.com/{args.github_username}/{args.name}"
}
metadata["homepage"] = f"https://github.com/{args.github_username}/{args.name}"
if args.homepage:
metadata["homepage"] = args.homepage
if keywords:
metadata["keywords"] = keywords
if args.category:
metadata["category"] = args.category
return metadata
def main():
parser = argparse.ArgumentParser(
description='Generate plugin.json metadata',
formatter_class=argparse.RawDescriptionHelpFormatter
)
# Required arguments
parser.add_argument('--name', required=True, help='Plugin name (lowercase-hyphen)')
parser.add_argument('--author', required=True, help='Author name or "Name <email>"')
parser.add_argument('--description', required=True, help='Plugin description (50-200 chars)')
parser.add_argument('--license', required=True, help='License type (MIT, Apache-2.0, etc.)')
# Optional arguments
parser.add_argument('--version', default='1.0.0', help='Initial version (default: 1.0.0)')
parser.add_argument('--category', default='development', help='Plugin category')
parser.add_argument('--keywords', help='Comma-separated keywords')
parser.add_argument('--repository', help='Repository URL')
parser.add_argument('--homepage', help='Homepage URL')
parser.add_argument('--github-username', help='GitHub username (auto-generates repo URL)')
parser.add_argument('--output', help='Output file path (default: stdout)')
parser.add_argument('--pretty', action='store_true', help='Pretty-print JSON')
args = parser.parse_args()
# Generate metadata
metadata = generate_metadata(args)
if metadata is None:
return 1
# Format JSON
if args.pretty:
json_output = json.dumps(metadata, indent=2, ensure_ascii=False)
else:
json_output = json.dumps(metadata, ensure_ascii=False)
# Output
if args.output:
try:
with open(args.output, 'w', encoding='utf-8') as f:
f.write(json_output)
print(f"✅ Metadata written to {args.output}", file=sys.stderr)
except IOError as e:
print(f"ERROR: Could not write to {args.output}: {e}", file=sys.stderr)
return 1
else:
print(json_output)
return 0
if __name__ == '__main__':
sys.exit(main())

91
commands/plugin-scaffold/.scripts/validate-name.sh Executable file
View File

@@ -0,0 +1,91 @@
#!/bin/bash
# Script: validate-name.sh
# Purpose: Validate plugin name follows Claude Code conventions
# Version: 1.0.0
# Last Modified: 2025-10-13
#
# Usage:
# ./validate-name.sh <plugin-name>
#
# Arguments:
# plugin-name: Name to validate
#
# Returns:
# 0 - Valid name
# 1 - Invalid name format
# 2 - Missing argument
#
# Dependencies:
# - grep (for regex matching)
# Check for argument
if [ $# -eq 0 ]; then
echo "ERROR: Plugin name required"
echo "Usage: $0 <plugin-name>"
exit 2
fi
PLUGIN_NAME="$1"
# Validation pattern: lowercase letters, numbers, hyphens
# Must start with letter, cannot end with hyphen
VALID_PATTERN='^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$'
# Check pattern match
if echo "$PLUGIN_NAME" | grep -Eq "$VALID_PATTERN"; then
# Additional checks
# Check for consecutive hyphens
if echo "$PLUGIN_NAME" | grep -q '\-\-'; then
echo "ERROR: Plugin name cannot contain consecutive hyphens"
echo "Invalid: $PLUGIN_NAME"
echo "Try: $(echo "$PLUGIN_NAME" | sed 's/--/-/g')"
exit 1
fi
# Check length (reasonable limit)
NAME_LENGTH=${#PLUGIN_NAME}
if [ $NAME_LENGTH -gt 50 ]; then
echo "ERROR: Plugin name too long ($NAME_LENGTH characters, max 50)"
echo "Consider a shorter name"
exit 1
fi
if [ $NAME_LENGTH -lt 3 ]; then
echo "ERROR: Plugin name too short ($NAME_LENGTH characters, min 3)"
echo "Use a more descriptive name"
exit 1
fi
# Check for common mistakes
if echo "$PLUGIN_NAME" | grep -iq 'plugin$'; then
echo "WARNING: Plugin name ends with 'plugin' - this is redundant"
echo "Consider: $(echo "$PLUGIN_NAME" | sed 's/-plugin$//' | sed 's/plugin$//')"
fi
# Success
echo "✅ Valid plugin name: $PLUGIN_NAME"
exit 0
else
# Invalid format
echo "ERROR: Invalid plugin name format: $PLUGIN_NAME"
echo ""
echo "Plugin names must:"
echo " - Start with a lowercase letter"
echo " - Contain only lowercase letters, numbers, and hyphens"
echo " - Not end with a hyphen"
echo " - Be between 3-50 characters"
echo ""
echo "Valid examples:"
echo " - code-formatter"
echo " - test-generator"
echo " - deploy-automation"
echo ""
echo "Invalid examples:"
echo " - CodeFormatter (uppercase)"
echo " - test_generator (underscores)"
echo " - -my-plugin (starts with hyphen)"
echo " - plugin- (ends with hyphen)"
exit 1
fi

445
commands/plugin-scaffold/complete-scaffold.md Normal file
View File

@@ -0,0 +1,445 @@
---
description: Generate complete plugin structure with all necessary files in one operation
---
# Complete Plugin Scaffolding
## Parameters
**Required**:
- `name`: Plugin name in lowercase-hyphen format
- `description`: Brief description (50-200 characters)
- `author`: Author name or "name:email" format
- `license`: License type (MIT|Apache-2.0|GPL-3.0|BSD-3-Clause)
**Optional**:
- `category`: OpenPlugins category (default: "development")
- `keywords`: Comma-separated keywords (default: auto-generated)
- `version`: Initial version (default: "1.0.0")
- `with_agent`: Include agent template (format: true|false, default: false)
- `with_hooks`: Include hooks template (format: true|false, default: false)
## Workflow
### Step 1: Validate Parameters
**Plugin Name Validation**:
- Must match pattern: `^[a-z][a-z0-9-]*$`
- Must be lowercase with hyphens only
- Cannot start with numbers
- Should be descriptive and memorable
Execute validation script:
```bash
.scripts/validate-name.sh "{name}"
```
**Description Validation**:
- Length: 50-200 characters
- Must be specific and actionable
- Should answer "What does this do?"
**Author Format**:
- Simple: "John Doe"
- With email: "John Doe <john@example.com>"
- Object format: handled automatically
### Step 2: Create Directory Structure
**Base Structure**:
```bash
mkdir -p {name}/.claude-plugin
mkdir -p {name}/commands
mkdir -p {name}/agents # if with_agent:true
mkdir -p {name}/hooks # if with_hooks:true
```
**Subdirectories Based on Pattern**:
- Simple plugin: No subdirectories needed
- Moderate plugin: May create command namespace directories
- Complex plugin: Create skill directories with .scripts/
### Step 3: Generate plugin.json
Create `plugin.json` at the plugin root with complete metadata:
```json
{
"name": "{name}",
"version": "{version}",
"description": "{description}",
"author": {
"name": "{author_name}",
"email": "{author_email}"
},
"license": "{license}",
"repository": {
"type": "git",
"url": "https://github.com/{username}/{name}"
},
"homepage": "https://github.com/{username}/{name}",
"keywords": [{keywords}],
"category": "{category}"
}
```
Execute metadata generation script:
```bash
.scripts/generate-metadata.py --name "{name}" --author "{author}" --description "{description}" --license "{license}" --category "{category}"
```
### Step 4: Create README.md
Generate comprehensive README with sections:
1. **Title and Badge**
2. **Description** (expanded from metadata)
3. **Features** (bullet list)
4. **Installation** (multiple methods)
5. **Usage** (with examples)
6. **Configuration** (if applicable)
7. **Commands** (document each command)
8. **Agents** (if with_agent:true)
9. **Hooks** (if with_hooks:true)
10. **Examples** (multiple real scenarios)
11. **Troubleshooting**
12. **Development** (testing, contributing)
13. **Changelog** (link to CHANGELOG.md)
14. **License**
15. **Resources**
### Step 5: Add LICENSE File
Based on license parameter, add appropriate LICENSE file:
**MIT**:
```
MIT License
Copyright (c) {year} {author}
Permission is hereby granted, free of charge, to any person obtaining a copy...
```
**Apache-2.0**:
```
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
...
```
**GPL-3.0**:
```
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
...
```
**BSD-3-Clause**:
```
BSD 3-Clause License
Copyright (c) {year}, {author}
...
```
### Step 6: Create CHANGELOG.md
Initialize changelog with version 1.0.0:
```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] - {date}
### Added
- Initial release
- {feature 1}
- {feature 2}
```
### Step 7: Create .gitignore
Add plugin development .gitignore:
```
# OS files
.DS_Store
Thumbs.db
# Editor directories
.vscode/
.idea/
*.swp
*.swo
*~
# Logs
*.log
npm-debug.log*
# Environment
.env
.env.local
# Dependencies
node_modules/
__pycache__/
*.pyc
# Build outputs
dist/
build/
*.egg-info/
# Test coverage
coverage/
.coverage
.nyc_output
# Temporary files
tmp/
temp/
*.tmp
```
### Step 8: Create Template Files
**If with_agent:true**, create `agents/specialist.md`:
```markdown
---
name: {name}-specialist
description: Expert in {domain}. Use when users need guidance with {functionality}.
capabilities: [capability1, capability2, capability3]
tools: Read, Write, Bash, Grep, Glob
model: inherit
---
# {Name} Specialist Agent
You are an expert in {domain}. Your role is to provide guidance and automation for {functionality}.
## When to Invoke
This agent is automatically invoked when users:
- {trigger condition 1}
- {trigger condition 2}
## Approach
{Agent's methodology and best practices}
```
**If with_hooks:true**, create `hooks/hooks.json`:
```json
{
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "echo 'Hook triggered after file modification'"
}
]
}
]
}
```
**Create sample command** in `commands/example.md`:
```markdown
---
description: Example command demonstrating plugin functionality
---
# Example Command
This is a sample command. Replace with your actual implementation.
## Usage
/{name} [arguments]
## Parameters
- `arg1`: Description
- `arg2`: Description (optional)
## Implementation
{Implementation instructions}
```
### Step 9: Verify Structure
Run structure validation:
```bash
# Check all required files exist
test -f {name}/plugin.json && echo "✅ plugin.json" || echo "❌ plugin.json missing"
test -f {name}/README.md && echo "✅ README.md" || echo "✅ README.md" || echo "❌ README.md missing"
test -f {name}/LICENSE && echo "✅ LICENSE" || echo "❌ LICENSE missing"
test -f {name}/CHANGELOG.md && echo "✅ CHANGELOG.md" || echo "❌ CHANGELOG.md missing"
test -d {name}/commands && echo "✅ commands/" || echo "❌ commands/ missing"
```
### Step 10: Generate Success Report
Provide comprehensive report with:
- Structure created confirmation
- Files generated list
- Next steps for development
- Testing instructions
- Marketplace submission readiness checklist
## Output Format
```markdown
## ✅ Plugin Scaffolding Complete
### Generated Structure
```
{name}/
├── .claude-plugin/
│ └── plugin.json ✅
├── .gitignore ✅
├── CHANGELOG.md ✅
├── LICENSE ({license}) ✅
├── README.md ✅
├── commands/
│ └── example.md ✅
├── agents/ {if applicable}
│ └── specialist.md ✅
└── hooks/ {if applicable}
└── hooks.json ✅
```
### Files Created
- ✅ **plugin.json**: Complete metadata with all required fields
- ✅ **README.md**: Comprehensive documentation template
- ✅ **LICENSE**: {license} license file
- ✅ **CHANGELOG.md**: Initialized with version 1.0.0
- ✅ **.gitignore**: Plugin development exclusions
- ✅ **commands/example.md**: Sample command template
{Additional files if created}
### Metadata Summary
**Name**: {name}
**Version**: {version}
**Description**: {description}
**Author**: {author}
**License**: {license}
**Category**: {category}
**Keywords**: {keywords}
### Next Steps
1. **Implement Functionality**
- Edit `commands/example.md` with your actual implementation
- Add more commands as needed
- Implement agent logic if included
2. **Update Documentation**
- Customize README.md with real examples
- Document all parameters and usage
- Add troubleshooting section
3. **Local Testing**
```bash
# Create test marketplace
mkdir -p test-marketplace/.claude-plugin
# Add marketplace.json
# Install and test plugin
```
4. **Prepare for Release**
- Update CHANGELOG.md with features
- Verify all documentation is complete
- Run quality checks
- Test all functionality
5. **Submit to OpenPlugins**
- Fork OpenPlugins repository
- Add plugin entry to marketplace.json
- Create pull request
### Quality Checklist
Before submission, ensure:
- ✅ Plugin name follows lowercase-hyphen format
- ✅ Description is 50-200 characters
- ✅ All required metadata fields present
- ✅ README has real content (no placeholders)
- ✅ LICENSE file included
- ✅ At least one functional command
- ✅ No hardcoded secrets
- ✅ Examples are concrete and realistic
### Testing Commands
```bash
# Navigate to plugin directory
cd {name}
# Validate plugin.json
python3 -m json.tool plugin.json
# Check file structure
ls -la
# Initialize git repository
git init
git add .
git commit -m "Initial plugin structure"
```
### Resources
- Plugin Documentation: https://docs.claude.com/en/docs/claude-code/plugins
- OpenPlugins Guide: https://github.com/dhofheinz/open-plugins
- Submit Plugin: Fork repository and add to marketplace.json
---
**Plugin scaffolding complete!** Your plugin is ready for implementation.
```
## Error Handling
- **Invalid plugin name** → Show valid pattern and suggest correction
- **Directory exists** → Ask for confirmation to overwrite or use different name
- **Invalid license type** → List supported licenses: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
- **Missing required parameter** → Request parameter with expected format
- **Git not available** → Skip git initialization, provide manual instructions
- **File creation fails** → Report specific file and error, provide recovery steps
## Examples
### Example 1: Simple Plugin
**Input**:
```
/plugin-scaffold complete name:hello-world author:"Jane Smith" license:MIT description:"Simple greeting plugin for Claude Code"
```
**Output**: Complete plugin structure with all files
### Example 2: Plugin with Agent
**Input**:
```
/plugin-scaffold complete name:code-reviewer author:"John Doe <john@example.com>" license:Apache-2.0 description:"Automated code review with security analysis" with_agent:true category:quality
```
**Output**: Plugin structure including agent template
**Request**: $ARGUMENTS

58
commands/plugin-scaffold/skill.md Normal file
View File

@@ -0,0 +1,58 @@
---
description: Generate complete plugin directory structures with all necessary files and proper scaffolding
---
# Plugin Scaffold Skill
Expert plugin structure generation with complete directory scaffolding, metadata creation, and file templates.
## Operations
- **create** - Generate complete plugin directory structure
- **manifest** - Create or update plugin.json with validation
- **readme** - Generate comprehensive README template
- **license** - Add LICENSE file with selected license type
- **complete** - All-in-one: create full plugin structure with all files
## Usage Examples
```bash
# Generate complete structure
/plugin-scaffold create name:my-plugin author:"John Doe"
# Create plugin.json
/plugin-scaffold manifest name:my-plugin version:1.0.0 description:"Plugin description" license:MIT
# Generate README
/plugin-scaffold readme name:my-plugin description:"Full description"
# Add license
/plugin-scaffold license type:MIT plugin:my-plugin
# All-in-one scaffolding
/plugin-scaffold complete name:my-plugin author:"John Doe" license:MIT description:"Complete plugin"
```
## Router Logic
Parse the first word of $ARGUMENTS to determine the requested operation:
1. Extract operation from first word of $ARGUMENTS
2. Parse remaining arguments as key:value parameters
3. Route to appropriate operation file:
- "create" → Read and execute `{plugin-path}/commands/plugin-scaffold/create-structure.md`
- "manifest" → Read and execute `{plugin-path}/commands/plugin-scaffold/generate-manifest.md`
- "readme" → Read and execute `{plugin-path}/commands/plugin-scaffold/create-readme.md`
- "license" → Read and execute `{plugin-path}/commands/plugin-scaffold/add-license.md`
- "complete" → Read and execute `{plugin-path}/commands/plugin-scaffold/complete-scaffold.md`
**Error Handling**:
- If operation unknown → List available operations with usage
- If required parameters missing → Request with expected format
- If plugin name invalid → Suggest valid naming pattern (lowercase-hyphen)
- If directory exists → Warn and ask for confirmation to overwrite
**Base directory**: Plugin commands directory
**Current request**: $ARGUMENTS
Parse operation and route to appropriate instruction file now.

40
commands/plugin-test/skill.md Normal file
View File

@@ -0,0 +1,40 @@
---
description: Create test marketplaces and guide local plugin testing workflows
---
# Plugin Testing Skill
Expert plugin testing guidance with test marketplace creation and validation workflows.
## Operations
- **create-marketplace** - Generate test marketplace structure for local testing
- **install** - Guide local plugin installation process
- **validate-install** - Verify plugin installed correctly
- **test-commands** - Test plugin commands and verify functionality
## Usage Examples
```bash
# Create test marketplace
/plugin-test create-marketplace name:test-market plugin:my-plugin
# Install locally
/plugin-test install plugin:my-plugin@test-market
# Validate installation
/plugin-test validate-install plugin:my-plugin
# Test commands
/plugin-test test-commands plugin:my-plugin
```
## Router Logic
Parse operation from $ARGUMENTS and route to appropriate instruction file:
- "create-marketplace" → `{plugin-path}/commands/plugin-test/create-test-marketplace.md`
- "install" → `{plugin-path}/commands/plugin-test/install-locally.md`
- "validate-install" → `{plugin-path}/commands/plugin-test/validate-installation.md`
- "test-commands" → `{plugin-path}/commands/plugin-test/test-commands.md`
**Current request**: $ARGUMENTS

996
commands/quickstart-plugin.md Normal file
View 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.