# CC Plugin Forge

A comprehensive skill for building and managing Claude Code plugins with proper structure, manifests, and marketplace integration.

## Purpose

Plugin Forge streamlines the entire lifecycle of Claude Code plugin development. It provides automation scripts, reference documentation, and structured workflows to help you create professional-quality plugins that integrate seamlessly with the Claude Code plugin ecosystem.

Whether you're building a framework-specific plugin for React or Vue, a utility plugin for common tasks, or a domain-specific knowledge plugin, Plugin Forge guides you through the correct structure and patterns.

## When to Use

Use this skill when you need to:

- **Create new plugins** - "Create a new Claude Code plugin for my project"
- **Add plugin components** - "Add a new command to my plugin", "Create a skill for this plugin"
- **Manage versions** - "Bump the plugin version", "Update plugin to 2.0.0"
- **Work with manifests** - "Update plugin.json", "Register plugin in marketplace"
- **Set up local testing** - "Test my plugin locally", "Install plugin for development"
- **Publish plugins** - "Publish plugin to marketplace", "Distribute my plugin"

**Trigger phrases:**
- "Create a Claude Code plugin"
- "Build a plugin for marketplace"
- "Add command/skill/agent/hook to plugin"
- "Bump plugin version"
- "Update plugin.json"
- "Set up plugin testing"

## How It Works

### Plugin Creation Flow

1. **Scaffold Structure** - The `create_plugin.py` script generates the correct directory hierarchy with all required files
2. **Generate Manifests** - Creates `plugin.json` with metadata and updates `marketplace.json` with the plugin entry
3. **Create Templates** - Generates a README template for your plugin documentation
4. **Guide Next Steps** - Provides instructions for adding components and testing

### Version Management Flow

1. **Parse Current Version** - Reads version from `plugin.json`
2. **Calculate New Version** - Applies semantic versioning rules (major/minor/patch)
3. **Sync Both Manifests** - Updates version in both `plugin.json` and `marketplace.json`
4. **Confirm Success** - Reports the version change

## Key Features

### Automation Scripts

| Script | Purpose |
|--------|---------|
| `create_plugin.py` | Scaffold new plugins with complete structure and manifests |
| `bump_version.py` | Update versions across all manifest files consistently |

### Reference Documentation

| Document | Content |
|----------|---------|
| `plugin-structure.md` | Directory hierarchy, manifest schema, component types |
| `marketplace-schema.md` | Marketplace format, plugin entries, source specifications |
| `workflows.md` | Development workflows, testing patterns, publishing guide |

### Plugin Patterns

- **Framework Plugin** - For framework-specific guidance (React, Vue, Nuxt)
- **Utility Plugin** - For tools and command collections
- **Domain Plugin** - For domain-specific knowledge with scripts

### Component Support

| Component | Location | Format |
|-----------|----------|--------|
| Commands | `commands/` | Markdown with frontmatter |
| Skills | `skills/<name>/` | Directory with `SKILL.md` |
| Agents | `agents/` | Markdown definitions |
| Hooks | `hooks/hooks.json` | Event handlers |
| MCP Servers | `.mcp.json` | External integrations |

## Usage Examples

### Create a New Plugin

```bash
python scripts/create_plugin.py my-awesome-plugin \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "you@example.com" \
  --description "A plugin that does awesome things" \
  --keywords "awesome,utility,productivity" \
  --category "productivity"
```

This creates:
```
plugins/my-awesome-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── skills/
└── README.md
```

### Bump Version

```bash
# Patch bump (bug fixes): 1.0.0 → 1.0.1
python scripts/bump_version.py my-plugin patch --marketplace-root /path/to/marketplace

# Minor bump (new features): 1.0.0 → 1.1.0
python scripts/bump_version.py my-plugin minor --marketplace-root /path/to/marketplace

# Major bump (breaking changes): 1.0.0 → 2.0.0
python scripts/bump_version.py my-plugin major --marketplace-root /path/to/marketplace
```

### Local Testing

```bash
# Add your marketplace
/plugin marketplace add /path/to/marketplace-root

# Install the plugin
/plugin install my-plugin@marketplace-name

# After making changes, reinstall
/plugin uninstall my-plugin@marketplace-name
/plugin install my-plugin@marketplace-name
```

### Create Command with Namespace

Create `commands/docs/generate.md` to get `/docs:generate` command:

```markdown
---
description: Generate documentation for the current project
---

# Generate Documentation

Instructions for the command...
```

## Prerequisites

- **Python 3.10+** - Required for running automation scripts
- **Existing Marketplace** - A marketplace with `.claude-plugin/marketplace.json` must exist before creating plugins
- **Claude Code** - For testing and using plugins

## Output

### create_plugin.py Output

```
✅ Created plugin manifest: plugins/my-plugin/.claude-plugin/plugin.json
✅ Created README: plugins/my-plugin/README.md
✅ Updated marketplace manifest: .claude-plugin/marketplace.json

🎉 Plugin 'my-plugin' created successfully!

Next steps:
1. Add commands to: plugins/my-plugin/commands
2. Add skills to: plugins/my-plugin/skills
3. Test with: /plugin install my-plugin@marketplace-name
```

### bump_version.py Output

```
✅ Updated plugin.json: 1.0.0 → 1.1.0
✅ Updated marketplace.json: 1.0.0 → 1.1.0

🎉 Version bumped successfully: 1.0.0 → 1.1.0
```

## Best Practices

### Naming Conventions

- **Plugin names**: Use `kebab-case` (e.g., `vue-components`, `api-testing`)
- **Command files**: Use `kebab-case.md` (e.g., `generate-docs.md`)
- **Command namespaces**: Use subdirectories for grouping (e.g., `commands/prime/vue.md` becomes `/prime:vue`)

### Version Management

- Always use semantic versioning
- **Major (x.0.0)**: Breaking changes that require user action
- **Minor (0.x.0)**: New features, significant refactoring
- **Patch (0.0.x)**: Bug fixes, documentation updates
- Always bump versions in both `plugin.json` and `marketplace.json` - use `bump_version.py` to automate this

### Plugin Structure

- Keep the plugin manifest in `.claude-plugin/plugin.json` (required location)
- Place components at the plugin root, not inside `.claude-plugin/`
- Use `${CLAUDE_PLUGIN_ROOT}` for dynamic path resolution in hooks and MCP configs

### Git Commits

Use conventional commits for clear history:
```bash
git commit -m "feat: add new plugin"
git commit -m "fix: correct plugin manifest"
git commit -m "docs: update plugin README"
git commit -m "feat!: breaking change"
```

### Testing

- Always test locally before publishing
- Restart Claude Code after reinstalling to ensure changes take effect
- Claude Code caches plugin files, so reinstallation is needed for updates

## Plugin Directory Structure Reference

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin metadata manifest
├── commands/                 # Optional: Custom slash commands
│   ├── simple.md            # → /simple
│   └── namespace/
│       └── action.md        # → /namespace:action
├── agents/                   # Optional: Agent definitions
├── skills/                   # Optional: Agent Skills
│   └── skill-name/
│       ├── SKILL.md         # Required for each skill
│       ├── scripts/         # Optional: Executable code
│       ├── references/      # Optional: Documentation
│       └── assets/          # Optional: Output files
├── hooks/                    # Optional: Event handlers
│   └── hooks.json
├── .mcp.json                # Optional: MCP server integrations
└── README.md                # Recommended: Plugin documentation
```

## Troubleshooting

### Plugin directory already exists

The `create_plugin.py` script will not overwrite existing plugins. Either:
- Delete the existing directory if you want to start fresh
- Manually update the existing plugin

### Plugin not found in marketplace manifest

When using `bump_version.py`, ensure:
- The plugin name matches exactly (case-sensitive)
- The plugin entry exists in `.claude-plugin/marketplace.json`

### Changes not taking effect after reinstall

Claude Code caches plugin files. After reinstalling:
1. Restart Claude Code completely
2. Verify the plugin is listed with `/plugin list`

### Marketplace manifest not found

Ensure you're running scripts from the correct directory or provide the full path with `--marketplace-root`.