zhongwei/gh-geoffjay-claude-plugins-plugins-claude-plugin
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:28:02 +08:00
commit 4ea8c8d0b0
15 changed files with 4003 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
commands/create.md Normal file
View File

@@ -0,0 +1,275 @@
---
name: claude-plugin:create
description: Create a new Claude Code plugin with agents, commands, and/or skills
---
# Create Plugin Command
Create a new Claude Code plugin following granular, composable architecture principles.
## Arguments
- `$1` - Plugin name (required, hyphen-case format)
- `$2` - Plugin description (required)
- `$3` - Components to create: `agents`, `commands`, `skills`, or combinations like `agents,commands` (optional, defaults to prompting)
- `$4` - Additional configuration as JSON (optional)
## Usage
```bash
# Basic usage - will prompt for details
/claude-plugin:create my-plugin-name "Plugin description"
# Specify components
/claude-plugin:create my-plugin-name "Plugin description" agents,commands
# Full configuration
/claude-plugin:create golang-advanced "Advanced Go development tools" agents,commands,skills '{"category":"languages","model":"claude-sonnet-4"}'
```
## Workflow
This command orchestrates plugin creation by:
1. **Validating Input**
- Verify plugin name follows hyphen-case convention
- Ensure plugin doesn't already exist
- Validate component specifications
2. **Gathering Requirements**
- If components not specified, ask user what to create
- Request additional details about agents (names, purposes, models)
- Request command details (names, purposes, workflows)
- Request skill details (names, triggers, content structure)
3. **Creating Plugin Structure**
- Create plugin directory: `plugins/$PLUGIN_NAME/`
- Create component directories as needed
- Set up skill subdirectories (SKILL.md, assets/, references/)
4. **Generating Components**
- Use Task tool with subagent_type="claude-plugin" to design and implement components
- Create agent files with proper frontmatter
- Create command files with argument handling
- Create skill files with progressive disclosure
5. **Updating Marketplace**
- Invoke marketplace-update skill to add plugin entry
- Invoke documentation-update skill to update docs
---
## Implementation
**Plugin Name:** ${1:-"[REQUIRED]"}
**Description:** ${2:-"[REQUIRED]"}
**Components:** ${3:-"[PROMPT USER]"}
**Configuration:** ${4:-"{}"}
### Step 1: Validate Plugin Name
The plugin name must:
- Be in hyphen-case format (e.g., `my-plugin-name`)
- Not already exist in `plugins/` directory
- Be descriptive and focused on a single purpose
### Step 2: Determine Components
If components are not specified in `$3`, ask the user:
**"What components should this plugin include?"**
Options:
- **Agents** - Specialized domain experts with deep knowledge
- **Commands** - Tools and workflow automation
- **Skills** - Modular knowledge packages with progressive disclosure
The plugin must have at least one agent OR one command.
### Step 3: Gather Component Details
For each component type selected:
#### Agents
- Agent name (hyphen-case)
- Agent purpose and description
- Recommended model (haiku for deterministic tasks, sonnet for complex reasoning)
- Key capabilities
- Example use cases
#### Commands
- Command name (hyphen-case)
- Command purpose and description
- Expected arguments
- Workflow steps
- Integration points
#### Skills
- Skill name (hyphen-case)
- Skill description with "Use when" trigger
- Progressive disclosure structure
- Required assets (templates, examples)
- Reference documentation needs
### Step 4: Invoke Plugin Architect
Use Task tool with subagent_type="claude-plugin" to design and implement the plugin:
```
I need to create a new plugin called "$PLUGIN_NAME" with the following specifications:
Description: $PLUGIN_DESCRIPTION
Components: $COMPONENTS
Details: [collected from user]
Please design and implement this plugin following the architecture principles:
- Single responsibility
- Composability
- Context efficiency
- Spec compliance
Create all necessary files with proper frontmatter, documentation, and examples.
```
### Step 5: Update Repository
After plugin creation:
1. **Update Marketplace**
Invoke the marketplace-update skill by running the Python script:
```bash
python plugins/claude-plugin/skills/marketplace-update/marketplace_update.py add \
--name "$PLUGIN_NAME" \
--description "$PLUGIN_DESCRIPTION" \
--version "1.0.0" \
--category "$CATEGORY" \
--agents "$(ls plugins/$PLUGIN_NAME/agents/*.md 2>/dev/null | xargs -n1 basename | tr '\n' ',')" \
--commands "$(ls plugins/$PLUGIN_NAME/commands/*.md 2>/dev/null | xargs -n1 basename | tr '\n' ',')" \
--skills "$(ls -d plugins/$PLUGIN_NAME/skills/*/ 2>/dev/null | xargs -n1 basename | tr '\n' ',')"
```
2. **Update Documentation**
Invoke the documentation-update skill by running the Python script:
```bash
python plugins/claude-plugin/skills/documentation-update/doc_generator.py
```
This regenerates:
- `docs/agents.md` - Agent reference
- `docs/agent-skills.md` - Skills catalog
- `docs/plugins.md` - Plugin directory
- `docs/usage.md` - Usage guide
3. **Verify Structure**
- Check all files have proper frontmatter
- Verify naming conventions
- Ensure documentation is complete
- Confirm marketplace.json is valid
- Verify all documentation files were regenerated
### Step 6: Confirm Success
Report to the user:
- ✓ Plugin created at `plugins/$PLUGIN_NAME/`
- ✓ Components created: [list]
- ✓ Marketplace updated
- ✓ Documentation updated
- Next steps or usage instructions
## Examples
### Example 1: Create Language Plugin
```bash
/claude-plugin:create rust-development "Rust language development tools" agents,commands,skills
```
This would:
- Create `plugins/rust-development/`
- Prompt for agent details (e.g., rust-pro agent)
- Prompt for command details (e.g., rust-scaffold command)
- Prompt for skill details (e.g., rust-patterns skill)
- Generate all components with proper structure
- Update marketplace and documentation
### Example 2: Create Security Plugin
```bash
/claude-plugin:create security-scanning "Security vulnerability scanning and analysis" agents,commands
```
This would:
- Create `plugins/security-scanning/`
- Prompt for security agent details
- Prompt for scanning command details
- Generate components without skills
- Update marketplace and documentation
### Example 3: Create Minimal Plugin
```bash
/claude-plugin:create test-helper "Test generation helper utilities" commands
```
This would:
- Create `plugins/test-helper/`
- Prompt for command details only
- Generate command file
- Update marketplace and documentation
## Error Handling
Common issues and resolutions:
### Plugin Already Exists
If `plugins/$PLUGIN_NAME/` exists:
- Error: "Plugin '$PLUGIN_NAME' already exists. Use /claude-plugin:update to modify existing plugins."
- Suggest using `/claude-plugin:update` command instead
### Invalid Plugin Name
If plugin name is not hyphen-case:
- Error: "Plugin name must be in hyphen-case format (e.g., 'my-plugin-name')"
- Suggest correct format
### No Components Specified
If user doesn't specify components and doesn't respond to prompts:
- Error: "At least one component (agent or command) is required"
- Prompt again with clear options
### Missing Required Arguments
If `$1` or `$2` are not provided:
- Error: "Usage: /claude-plugin:create <plugin-name> <description> [components] [config]"
- Show examples
## Notes
- This command creates new plugins only. Use `/claude-plugin:update` to modify existing plugins.
- All generated files will include proper YAML frontmatter
- The plugin-architect agent ensures adherence to architecture principles
- Skills are invoked automatically for marketplace and documentation updates
- Generated code follows best practices and spec compliance

659
commands/documentation.md Normal file
View File

@@ -0,0 +1,659 @@
---
name: claude-plugin:documentation
description: Regenerate all documentation files from marketplace data and plugin metadata
---
# Documentation Generation Command
Regenerate all documentation files (agents.md, agent-skills.md, plugins.md, usage.md) from the marketplace catalog and plugin metadata using Jinja2 templates.
## Arguments
- `$1` - Specific file to generate: `agents`, `agent-skills`, `plugins`, `usage`, or `all` (optional, defaults to `all`)
- `$2` - Additional options as JSON (optional)
## Usage
```bash
# Regenerate all documentation files
/claude-plugin:documentation
# Regenerate specific file
/claude-plugin:documentation agents
# Dry run to preview changes
/claude-plugin:documentation all '{"dry_run": true}'
# Specify custom paths
/claude-plugin:documentation all '{"marketplace": ".claude-plugins/marketplace.json", "output": "docs"}'
```
## Workflow
This command orchestrates documentation generation by:
1. **Validating Prerequisites**
- Verify marketplace.json exists and is valid
- Check template files exist in documentation-update skill
- Ensure plugin directories are accessible
- Verify output directory exists or can be created
2. **Preparing Context**
- Load marketplace catalog
- Scan all plugin directories
- Extract agent/command/skill metadata
- Build component indexes
- Calculate statistics
3. **Generating Documentation**
- Invoke documentation-update skill
- Render Jinja2 templates with context
- Write output to docs/ directory
- Report any warnings or errors
4. **Verifying Output**
- Check all requested files were generated
- Verify file formatting and structure
- Validate links and references
- Report success and statistics
---
## Implementation
**Target File:** ${1:-"all"}
**Options:** ${2:-"{}"}
### Step 1: Validate Prerequisites
Check that all required components exist:
```bash
# Check marketplace exists
if [ ! -f .claude-plugins/marketplace.json ]; then
echo "Error: Marketplace file not found at .claude-plugins/marketplace.json"
exit 1
fi
# Check skill exists
if [ ! -f plugins/claude-plugin/skills/documentation-update/doc_generator.py ]; then
echo "Error: Documentation update skill not found"
exit 1
fi
# Check templates exist
if [ ! -d plugins/claude-plugin/skills/documentation-update/assets ]; then
echo "Error: Template directory not found"
exit 1
fi
# Create docs directory if needed
mkdir -p docs
```
### Step 2: Parse Options
Extract configuration from `$2` JSON parameter:
- `dry_run`: Preview output without writing files
- `marketplace`: Custom path to marketplace.json
- `templates`: Custom path to template directory
- `output`: Custom output directory
- `verbose`: Show detailed progress
### Step 3: Invoke Documentation Update Skill
Run the documentation generation script:
```bash
# Build command with options
PYTHON_CMD="python plugins/claude-plugin/skills/documentation-update/doc_generator.py"
# Add file filter if specified
if [ "$TARGET_FILE" != "all" ]; then
PYTHON_CMD="$PYTHON_CMD --file $TARGET_FILE"
fi
# Add custom paths if provided
if [ -n "$MARKETPLACE_PATH" ]; then
PYTHON_CMD="$PYTHON_CMD --marketplace $MARKETPLACE_PATH"
fi
if [ -n "$TEMPLATES_PATH" ]; then
PYTHON_CMD="$PYTHON_CMD --templates $TEMPLATES_PATH"
fi
if [ -n "$OUTPUT_PATH" ]; then
PYTHON_CMD="$PYTHON_CMD --output $OUTPUT_PATH"
fi
# Add dry-run flag if requested
if [ "$DRY_RUN" = "true" ]; then
PYTHON_CMD="$PYTHON_CMD --dry-run"
fi
# Add verbose flag if requested
if [ "$VERBOSE" = "true" ]; then
PYTHON_CMD="$PYTHON_CMD --verbose"
fi
# Execute command
echo "Generating documentation..."
eval $PYTHON_CMD
```
### Step 4: Report Results
After successful generation:
```
✓ Documentation generation completed
Files generated:
- docs/agents.md (25 agents across 10 plugins)
- docs/agent-skills.md (30 skills with progressive disclosure)
- docs/plugins.md (10 plugins in 4 categories)
- docs/usage.md (Usage guide and examples)
Statistics:
- Total plugins: 10
- Total agents: 25
- Total commands: 15
- Total skills: 30
All documentation files are now synchronized with the marketplace catalog.
```
If errors occurred:
```
❌ Documentation generation failed
Errors encountered:
- Template not found: assets/agents.md.j2
- Invalid frontmatter in plugins/example/agents/test.md
Please fix the errors above and run the command again.
```
## Examples
### Example 1: Full Documentation Update
```bash
/claude-plugin:documentation
```
**Output:**
```
Generating documentation...
✓ Loading marketplace.json
✓ Scanning plugin directories
✓ Extracting metadata from 10 plugins
✓ Building component indexes
✓ Rendering templates
✓ Writing docs/agents.md
✓ Writing docs/agent-skills.md
✓ Writing docs/plugins.md
✓ Writing docs/usage.md
Documentation generation completed successfully.
```
### Example 2: Generate Single File
```bash
/claude-plugin:documentation agents
```
**Output:**
```
Generating documentation...
✓ Loading marketplace.json
✓ Scanning plugin directories
✓ Extracting agent metadata
✓ Rendering agents.md.j2 template
✓ Writing docs/agents.md
Generated docs/agents.md with 25 agents.
```
### Example 3: Dry Run
```bash
/claude-plugin:documentation all '{"dry_run": true}'
```
**Output:**
```
Dry run mode - no files will be written
Preview of docs/agents.md:
===========================
# Agent Reference
This document lists all agents available across plugins in the marketplace.
## Languages
### rust-development
...
Preview of docs/agent-skills.md:
=================================
...
Dry run completed. Run without --dry-run to write files.
```
### Example 4: Custom Paths
```bash
/claude-plugin:documentation all '{"marketplace": "custom/marketplace.json", "output": "generated-docs"}'
```
**Output:**
```
Generating documentation...
✓ Loading custom/marketplace.json
✓ Using default templates
✓ Output directory: generated-docs
✓ Generating all documentation files
✓ Writing generated-docs/agents.md
✓ Writing generated-docs/agent-skills.md
✓ Writing generated-docs/plugins.md
✓ Writing generated-docs/usage.md
Documentation generation completed successfully.
```
## Generated Files
This command generates the following documentation files:
### 1. docs/agents.md
**Purpose:** Complete reference of all agents across all plugins
**Contents:**
- Agents organized by plugin and category
- Agent name, description, and model
- Links to agent files
- Agent capabilities and use cases
- Statistics on total agents
**Example Structure:**
```markdown
# Agent Reference
## Languages
### rust-development
**Agents:**
- **rust-pro** (`claude-sonnet-4`)
- Master Rust 1.75+ with modern async patterns...
- File: `plugins/rust-development/agents/rust-pro.md`
```
### 2. docs/agent-skills.md
**Purpose:** Catalog of all skills with progressive disclosure details
**Contents:**
- Skills organized by plugin
- Skill name and description
- "Use when" triggers
- Skill structure and location
- Statistics on total skills
**Example Structure:**
```markdown
# Agent Skills Reference
## Plugin Management
### claude-plugin
**Skills:**
#### documentation-update
Regenerates documentation files from marketplace data using Jinja templates. Use when plugins are added, updated, or removed.
- **Location:** `plugins/claude-plugin/skills/documentation-update/`
- **Structure:** SKILL.md + assets/ + references/
```
### 3. docs/plugins.md
**Purpose:** Directory of all plugins in the marketplace
**Contents:**
- Plugins organized by category
- Plugin name, description, and version
- List of components (agents, commands, skills)
- Installation and usage information
- Statistics on total plugins
**Example Structure:**
```markdown
# Plugin Directory
## Plugin Management
### claude-plugin (v1.0.0)
Plugin management and scaffolding tools.
**Components:**
- Agents: plugin-architect
- Commands: create, update, documentation
- Skills: marketplace-update, documentation-update
**Installation:** Available by default
```
### 4. docs/usage.md
**Purpose:** Usage guide and command reference
**Contents:**
- Getting started instructions
- Command usage examples
- Workflow patterns
- Integration guides
- Best practices
**Example Structure:**
```markdown
# Usage Guide
## Getting Started
This marketplace provides Claude Code plugins following a granular, composable architecture...
## Creating Plugins
Use the `/claude-plugin:create` command to create new plugins:
\`\`\`bash
/claude-plugin:create my-plugin "Plugin description"
\`\`\`
## Updating Documentation
After making changes to plugins, regenerate documentation:
\`\`\`bash
/claude-plugin:documentation
\`\`\`
```
## Integration with Other Commands
This command is automatically invoked by:
### /claude-plugin:create
After creating a new plugin:
```
✓ Plugin created at plugins/my-plugin/
✓ Marketplace updated
⏳ Updating documentation...
✓ Documentation updated
```
### /claude-plugin:update
After updating an existing plugin:
```
✓ Plugin updated at plugins/my-plugin/
✓ Marketplace updated
⏳ Updating documentation...
✓ Documentation updated
```
### Manual Invocation
Users can also run this command manually:
- After editing plugin files directly
- To refresh documentation after git pull
- To verify documentation is up to date
- To preview changes with dry-run
## Error Handling
Common issues and resolutions:
### Marketplace Not Found
```
Error: Marketplace file not found at .claude-plugins/marketplace.json
Suggestion:
- Verify you're in the repository root
- Check that .claude-plugins/marketplace.json exists
- Run /claude-plugin:create to create your first plugin
```
### Template Not Found
```
Error: Template file not found: assets/agents.md.j2
Suggestion:
- Verify claude-plugin plugin is properly installed
- Check that all template files exist in:
plugins/claude-plugin/skills/documentation-update/assets/
- Reinstall the claude-plugin plugin if needed
```
### Invalid Frontmatter
```
Warning: Could not parse frontmatter in plugins/my-plugin/agents/my-agent.md
Suggestion:
- Check YAML frontmatter syntax in the agent file
- Ensure frontmatter is enclosed in --- markers
- Verify required fields: name, description
- Fix syntax errors and run command again
```
### Missing Plugin Directory
```
Warning: Plugin 'my-plugin' in marketplace.json but directory not found
Suggestion:
- Verify plugins/my-plugin/ directory exists
- Remove stale entry from marketplace.json
- Recreate plugin if it was accidentally deleted
```
### Permission Denied
```
Error: Permission denied writing to docs/agents.md
Suggestion:
- Check write permissions on docs/ directory
- Ensure docs/ directory is not read-only
- Run with appropriate permissions
```
### Python Not Found
```
Error: python command not found
Suggestion:
- Install Python 3.8 or later
- Ensure python is in your PATH
- Try using python3 instead of python
```
## Template System
The documentation generation uses Jinja2 templates located in:
```
plugins/claude-plugin/skills/documentation-update/assets/
├── agents.md.j2
├── agent-skills.md.j2
├── plugins.md.j2
└── usage.md.j2
```
### Template Context
All templates receive the following context:
```python
{
"marketplace": {
"name": "marketplace-name",
"owner": {...},
"metadata": {...},
"plugins": [...]
},
"plugins_by_category": {
"category-name": [plugin1, plugin2, ...]
},
"all_agents": [...],
"all_skills": [...],
"all_commands": [...],
"stats": {
"total_plugins": 10,
"total_agents": 25,
"total_commands": 15,
"total_skills": 30
},
"now": "2025-10-17"
}
```
### Customizing Templates
To customize documentation output:
1. **Edit Existing Templates**
- Modify templates in assets/ directory
- Use Jinja2 syntax for dynamic content
- Test with dry-run before committing
2. **Add New Templates**
- Create new template file in assets/
- Update doc_generator.py to render new template
- Define output path for new file
3. **Test Changes**
- Run with --dry-run to preview
- Verify formatting and structure
- Check for template errors
## Best Practices
1. **Run After Every Plugin Change**
- Documentation should always reflect current state
- Commit documentation with plugin changes
- Include in pull request reviews
2. **Use Dry Run for Testing**
- Preview changes before writing
- Test template modifications
- Verify output structure
3. **Keep Templates Simple**
- Use clear Jinja2 syntax
- Document template variables
- Handle missing data gracefully
4. **Validate Output**
- Check generated files for correctness
- Verify all links work
- Test formatting renders properly
5. **Version Control**
- Commit documentation changes
- Include meaningful commit messages
- Tag major documentation updates
## Success Criteria
After running this command:
- ✓ All requested documentation files generated
- ✓ Content matches marketplace state
- ✓ All links are valid and correct
- ✓ Formatting is consistent
- ✓ Statistics are accurate
- ✓ No template rendering errors
- ✓ All plugins represented
- ✓ Metadata correctly extracted
## Troubleshooting
### Templates Not Rendering
**Problem:** Templates fail to render with Jinja2 errors
**Solutions:**
- Check Jinja2 syntax in templates
- Verify all variables are defined
- Use default filters for optional values
- Test templates with minimal data first
### Missing Component Data
**Problem:** Some agents/commands/skills not appearing in docs
**Solutions:**
- Verify frontmatter exists and is valid
- Check file naming follows conventions
- Ensure files have correct extensions (.md)
- Verify plugin directory structure
### Outdated Documentation
**Problem:** Documentation doesn't match current plugin state
**Solutions:**
- Run this command to regenerate
- Check marketplace.json is up to date
- Verify all plugin files exist
- Look for stale cache or old files
### Performance Issues
**Problem:** Generation takes too long with many plugins
**Solutions:**
- Use --file option to generate single files
- Optimize template complexity
- Consider caching marketplace data
- Profile doc_generator.py for bottlenecks
## Related Commands
- `/claude-plugin:create` - Create new plugin (auto-generates docs)
- `/claude-plugin:update` - Update existing plugin (auto-generates docs)
## Related Skills
- `marketplace-update` - Update marketplace.json catalog
- `documentation-update` - The skill this command invokes
## Notes
- This command is idempotent - safe to run multiple times
- Generated files should be committed to version control
- Templates use Python's built-in string formatting (no external dependencies)
- The command will create the docs/ directory if it doesn't exist
- Existing documentation files are overwritten without backup
- The documentation-update skill has no external dependencies

430
commands/update.md Normal file
View File

@@ -0,0 +1,430 @@
---
name: claude-plugin:update
description: Update an existing Claude Code plugin by adding, modifying, or removing components
---
# Update Plugin Command
Update an existing Claude Code plugin by adding new components, modifying existing ones, or removing obsolete components.
## Arguments
- `$1` - Plugin name (required, must exist in plugins/)
- `$2` - Update operation: `add`, `modify`, or `remove` (required)
- `$3` - Component type: `agent`, `command`, or `skill` (required)
- `$4` - Component name (required for modify/remove, optional for add)
- `$5` - Additional configuration as JSON (optional)
## Usage
```bash
# Add a new agent to existing plugin
/claude-plugin:update golang-development add agent golang-testing
# Modify an existing command
/claude-plugin:update golang-development modify command golang-scaffold
# Remove a skill
/claude-plugin:update golang-development remove skill golang-patterns
# Add with configuration
/claude-plugin:update rust-development add agent rust-async '{"model":"claude-sonnet-4","description":"Async Rust expert"}'
```
## Workflow
This command orchestrates plugin updates by:
1. **Validating Input**
- Verify plugin exists in `plugins/` directory
- Validate operation type (add/modify/remove)
- Ensure component type is valid
- Check component existence for modify/remove operations
2. **Gathering Requirements**
- For **add**: collect new component details
- For **modify**: identify what needs to change
- For **remove**: confirm removal and check dependencies
3. **Performing Update**
- Use Task tool with subagent_type="claude-plugin" to execute changes
- Create, modify, or remove component files
- Maintain spec compliance and naming conventions
4. **Updating Marketplace**
- Invoke marketplace-update skill to update plugin entry
- Invoke documentation-update skill to regenerate docs
---
## Implementation
**Plugin Name:** ${1:-"[REQUIRED]"}
**Operation:** ${2:-"[REQUIRED: add|modify|remove]"}
**Component Type:** ${3:-"[REQUIRED: agent|command|skill]"}
**Component Name:** ${4:-"[REQUIRED for modify/remove]"}
**Configuration:** ${5:-"{}"}
### Step 1: Validate Plugin Exists
Check that `plugins/$PLUGIN_NAME/` exists:
- If not found: Error "Plugin '$PLUGIN_NAME' not found. Use /create to create new plugins."
- If found: Continue to operation validation
### Step 2: Validate Operation
Based on `$2` operation type:
#### Add Operation
- Create new component in existing plugin
- Component name can be provided in `$4` or prompted
- Gather full component specifications
#### Modify Operation
- Update existing component
- Component name must be provided in `$4`
- Verify component file exists
- Ask what needs to be changed
#### Remove Operation
- Delete existing component
- Component name must be provided in `$4`
- Verify component file exists
- Confirm removal with user
- Check for dependencies
### Step 3: Execute Operation
Use Task tool with subagent_type="claude-plugin" to perform the update:
#### For Add Operation
```
I need to add a new $COMPONENT_TYPE to the "$PLUGIN_NAME" plugin:
Component Name: $COMPONENT_NAME
Component Type: $COMPONENT_TYPE
Configuration: $CONFIGURATION
Please design and implement this component following architecture principles:
- Single responsibility
- Spec compliance
- Proper frontmatter
- Complete documentation
Integrate it with the existing plugin structure.
```
#### For Modify Operation
```
I need to modify the $COMPONENT_TYPE named "$COMPONENT_NAME" in the "$PLUGIN_NAME" plugin:
Changes Requested: [gathered from user]
Configuration: $CONFIGURATION
Please update the component while:
- Maintaining backward compatibility
- Following spec compliance
- Updating documentation
- Preserving existing functionality where appropriate
```
#### For Remove Operation
```
I need to remove the $COMPONENT_TYPE named "$COMPONENT_NAME" from the "$PLUGIN_NAME" plugin:
Reason: [gathered from user if needed]
Please:
- Remove the component file
- Check for and warn about any dependencies
- Update plugin structure
- Clean up any orphaned assets
```
### Step 4: Update Repository
After component update:
1. **Update Marketplace**
Invoke the marketplace-update skill by running the appropriate Python command:
**For Add Operation:**
```bash
python plugins/claude-plugin/skills/marketplace-update/marketplace_update.py update \
--name "$PLUGIN_NAME" \
--add-agent "$COMPONENT_NAME.md" # if adding agent
--add-command "$COMPONENT_NAME.md" # if adding command
--add-skill "$COMPONENT_NAME" # if adding skill
```
**For Remove Operation:**
```bash
python plugins/claude-plugin/skills/marketplace-update/marketplace_update.py update \
--name "$PLUGIN_NAME" \
--remove-agent "$COMPONENT_NAME.md" # if removing agent
--remove-command "$COMPONENT_NAME.md" # if removing command
--remove-skill "$COMPONENT_NAME" # if removing skill
```
**For Modify Operation (version update):**
```bash
python plugins/claude-plugin/skills/marketplace-update/marketplace_update.py update \
--name "$PLUGIN_NAME" \
--version "1.0.1" # or appropriate version bump
```
2. **Update Documentation**
Invoke the documentation-update skill by running the Python script:
```bash
python plugins/claude-plugin/skills/documentation-update/doc_generator.py
```
This regenerates all documentation files to reflect the changes.
3. **Verify Integrity**
- Check plugin still has at least one agent or command
- Verify all references are valid
- Ensure frontmatter is correct
- Confirm marketplace.json is valid
- Verify documentation was regenerated
### Step 5: Confirm Success
Report to the user:
- ✓ Operation completed: [$OPERATION $COMPONENT_TYPE $COMPONENT_NAME]
- ✓ Plugin updated at `plugins/$PLUGIN_NAME/`
- ✓ Marketplace updated
- ✓ Documentation updated
- ✓ Current plugin structure: [list components]
## Operation Details
### Add Operation
When adding a new component:
**For Agents:**
- Prompt for agent name (hyphen-case)
- Prompt for purpose and description
- Prompt for model selection (haiku/sonnet)
- Prompt for capabilities and guidelines
- Create `plugins/$PLUGIN_NAME/agents/$AGENT_NAME.md`
**For Commands:**
- Prompt for command name (hyphen-case)
- Prompt for purpose and description
- Prompt for arguments and workflow
- Create `plugins/$PLUGIN_NAME/commands/$COMMAND_NAME.md`
**For Skills:**
- Prompt for skill name (hyphen-case)
- Prompt for description with "Use when" trigger
- Prompt for asset requirements
- Create skill directory structure:
- `plugins/$PLUGIN_NAME/skills/$SKILL_NAME/SKILL.md`
- `plugins/$PLUGIN_NAME/skills/$SKILL_NAME/assets/`
- `plugins/$PLUGIN_NAME/skills/$SKILL_NAME/references/`
### Modify Operation
When modifying an existing component:
1. **Read Current Component**
- Load existing file
- Parse frontmatter and content
- Show current structure to user
2. **Identify Changes**
- Ask user what needs to change:
- Update description
- Change model (agents only)
- Modify workflow
- Update examples
- Add/remove sections
3. **Apply Changes**
- Update file maintaining structure
- Preserve frontmatter format
- Update version if significant changes
4. **Validate**
- Ensure spec compliance
- Verify frontmatter is valid
- Check documentation completeness
### Remove Operation
When removing a component:
1. **Confirm Removal**
- Show component details
- Ask user to confirm deletion
- Warn about potential impacts
2. **Check Dependencies**
- Search for references to this component
- Warn if other plugins depend on it
- List commands that invoke this agent (if removing agent)
3. **Execute Removal**
- Delete component file
- Remove from marketplace entry
- Clean up orphaned directories
4. **Verify Plugin Integrity**
- Ensure plugin still has at least one agent or command
- If removing last component: warn and confirm plugin deletion
## Examples
### Example 1: Add New Agent
```bash
/claude-plugin:update golang-development add agent gin-expert
```
This would:
- Verify `plugins/golang-development/` exists
- Prompt for agent details (description, model, capabilities)
- Create `plugins/golang-development/agents/gin-expert.md`
- Update marketplace.json
- Update documentation
### Example 2: Modify Existing Command
```bash
/claude-plugin:update security-scanning modify command sast-scan
```
This would:
- Load existing `plugins/security-scanning/commands/sast-scan.md`
- Show current configuration
- Ask what needs to change
- Update the file
- Update documentation
### Example 3: Remove Skill
```bash
/claude-plugin:update kubernetes-operations remove skill helm-charts
```
This would:
- Confirm removal
- Check for dependencies
- Delete `plugins/kubernetes-operations/skills/helm-charts/`
- Update marketplace.json
- Update documentation
### Example 4: Add Agent with Configuration
```bash
/claude-plugin:update python-development add agent fastapi-pro '{"model":"claude-sonnet-4","description":"FastAPI framework expert"}'
```
This would:
- Use provided configuration
- Create agent with Sonnet model
- Generate comprehensive system prompt
- Update marketplace and docs
## Error Handling
Common issues and resolutions:
### Plugin Not Found
If `plugins/$PLUGIN_NAME/` doesn't exist:
- Error: "Plugin '$PLUGIN_NAME' not found. Use /claude-plugin:create to create new plugins."
- List available plugins
### Component Already Exists (Add)
If trying to add a component that exists:
- Error: "Component '$COMPONENT_NAME' already exists. Use 'modify' operation to update it."
- Show current component details
### Component Not Found (Modify/Remove)
If component doesn't exist:
- Error: "Component '$COMPONENT_NAME' not found in plugin '$PLUGIN_NAME'."
- List available components in plugin
### Invalid Operation
If `$2` is not add/modify/remove:
- Error: "Invalid operation. Must be: add, modify, or remove"
- Show usage examples
### Removing Last Component
If removing the last agent and command:
- Warning: "This is the last component in the plugin. Removing it will leave an empty plugin."
- Confirm: "Do you want to remove the entire plugin?"
### Dependencies Detected (Remove)
If other components reference the component being removed:
- Warning: "The following components reference '$COMPONENT_NAME': [list]"
- Confirm: "Proceed with removal? You may need to update dependent components."
## Version Management
When updating plugins:
### Minor Updates
- Adding new components
- Enhancing existing components
- Adding examples or documentation
- Increment patch version (1.0.0 → 1.0.1)
### Major Updates
- Modifying component interfaces
- Changing agent models
- Removing components
- Breaking changes
- Increment minor or major version (1.0.0 → 1.1.0 or 2.0.0)
## Notes
- This command updates existing plugins only. Use `/claude-plugin:create` for new plugins.
- All changes maintain spec compliance and proper frontmatter
- The plugin-architect agent ensures consistency with architecture principles
- Skills are invoked automatically for marketplace and documentation updates
- Backward compatibility should be maintained when possible
- Always test updated components before committing changes