CC Plugin Forge

Purpose

Build and manage AI coding agent plugins with correct structure, manifests, and marketplace integration. Includes workflows, automation scripts, and reference docs.

When to Use

• Creating new plugins for a marketplace

• Adding/modifying plugin components (commands, skills, agents, hooks)

• Updating plugin versions

• Working with plugin or marketplace manifests

• Setting up local plugin testing

• Publishing plugins

Getting Started

Create New Plugin

Use create_plugin.py to generate plugin structure:

python scripts/create_plugin.py plugin-name \

  --marketplace-root /path/to/marketplace \

  --author-name "Your Name" \

  --author-email "your.email@example.com" \

  --description "Plugin description" \

  --keywords "keyword1,keyword2" \

  --category "productivity"

This automatically:

• Creates plugin directory structure

• Generates plugin.json manifest

• Creates README template

• Updates marketplace.json

Bump Version

Use bump_version.py to update versions in both manifests:

python scripts/bump_version.py plugin-name major|minor|patch \

  --marketplace-root /path/to/marketplace

Semantic versioning:

• major: Breaking changes (1.0.0 → 2.0.0)

• minor: New features, refactoring (1.0.0 → 1.1.0)

• patch: Bug fixes, docs (1.0.0 → 1.0.1)

Development Workflow

1. Create Structure

Manual approach (if not using script):

mkdir -p plugins/plugin-name/.claude-plugin

mkdir -p plugins/plugin-name/commands

mkdir -p plugins/plugin-name/skills

2. Plugin Manifest

File: plugins/plugin-name/.claude-plugin/plugin.json

{

  "name": "plugin-name",

  "version": "0.1.0",

  "description": "Plugin description",

  "author": {

    "name": "Your Name",

    "email": "your.email@example.com"

  },

  "keywords": ["keyword1", "keyword2"]

}

3. Register in Marketplace

Update .claude-plugin/marketplace.json:

{

  "name": "plugin-name",

  "source": "./plugins/plugin-name",

  "description": "Plugin description",

  "version": "0.1.0",

  "keywords": ["keyword1", "keyword2"],

  "category": "productivity"

}

4. Add Components

Create in respective directories:

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

5. Local Testing

# Add marketplace

/plugin marketplace add /path/to/marketplace-root



# Install plugin

/plugin install plugin-name@marketplace-name



# After changes: reinstall

/plugin uninstall plugin-name@marketplace-name

/plugin install plugin-name@marketplace-name

Plugin Patterns

Framework Plugin

For framework-specific guidance (React, Vue, etc.):

plugins/framework-name/

├── .claude-plugin/plugin.json

├── skills/

│   └── framework-name/

│       ├── SKILL.md

│       └── references/

├── commands/

│   └── prime/

│       ├── components.md

│       └── framework.md

└── README.md

Utility Plugin

For tools and commands:

plugins/utility-name/

├── .claude-plugin/plugin.json

├── commands/

│   ├── action1.md

│   └── action2.md

└── README.md

Domain Plugin

For domain-specific knowledge:

plugins/domain-name/

├── .claude-plugin/plugin.json

├── skills/

│   └── domain-name/

│       ├── SKILL.md

│       ├── references/

│       └── scripts/

└── README.md

Command Naming

Subdirectory-based namespacing with : separator:

• commands/namespace/command.md → /namespace:command

• commands/simple.md → /simple

Examples:

• commands/prime/vue.md → /prime:vue

• commands/docs/generate.md → /docs:generate

Version Management

Important: Update version in BOTH locations:

1. plugins/<name>/.claude-plugin/plugin.json

2. .claude-plugin/marketplace.json

Use bump_version.py to automate.

Git Commits

Use conventional commits:

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"

Reference Docs

Detailed documentation included:

| Reference | Content |

|-----------|---------|

| references/plugin-structure.md | Directory structure, manifest schema, components |

| references/marketplace-schema.md | Marketplace format, plugin entries, distribution |

| references/workflows.md | Step-by-step workflows, patterns, publishing |

Scripts

| Script | Purpose |

|--------|---------|

| scripts/create_plugin.py | Scaffold new plugin |

| scripts/bump_version.py | Update versions |

Anti-Patterns

| Avoid | Why | Instead |

|-------|-----|---------|

| Uppercase namespace folder names | Breaks CLI routing parameters | Use lowercase characters and : delimiters |

| Raw commits without checks | Syntax errors block local install workflows | Run validation checks on plugin.json schemas before committing |

References & Loading Triggers

MANDATORY - LOADING TRIGGERS:

• Before modifying marketplace properties, you MUST read marketplace-schema.md fully.

• Before restructuring directories or adding hooks, you MUST read plugin-structure.md.

• Do NOT load workflows reference guides if you are only running simple version bumps.