Plugin Forge

CC Plugin Forge

Purpose

Build and manage Claude Code 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:

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:

Scripts

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

Reference Documentation

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

Usage Examples

Create a New Plugin

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

# 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

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

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

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.

Marketplace Schema Reference

Marketplace Structure

A marketplace is a JSON catalog enabling plugin discovery and distribution.

File location: .claude-plugin/marketplace.json

Required Fields

{
  "name": "marketplace-identifier",
  "owner": {
    "name": "Maintainer Name",
    "email": "maintainer@example.com"
  },
  "plugins": []
}

name: Kebab-case marketplace identifier owner: Maintainer contact information plugins: Array of plugin entries

Optional Marketplace Fields

description: Marketplace overview text version: Release version pluginRoot: Base path for relative plugin sources

Plugin Entry Schema

Each plugin entry in the plugins array:

Required:

• name: Plugin identifier (kebab-case, must match plugin.json)
• source: Plugin origin specification

Optional:

• description: Plugin purpose
• version: Plugin version (semantic versioning)
• author: Creator information
• homepage: URL
• repository: URL
• license: SPDX identifier
• keywords: Array of search terms
• category: Classification (e.g., "framework", "productivity")
• tags: Additional discovery tags
• commands: Path to commands directory
• agents: Path to agents directory
• hooks: Path to hooks configuration
• mcpServers: Path to MCP configuration

Source Specifications

Relative Path Source

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

GitHub Source

{
  "name": "my-plugin",
  "source": {
    "source": "github",
    "repo": "owner/repo"
  }
}

Generic Git Source

{
  "name": "my-plugin",
  "source": {
    "source": "url",
    "url": "https://git.example.com/plugin.git"
  }
}

Complete Example

{
  "name": "example-marketplace",
  "description": "Example plugin marketplace",
  "version": "1.0.0",
  "owner": {
    "name": "Marketplace Owner",
    "email": "owner@example.com"
  },
  "pluginRoot": "./plugins",
  "plugins": [
    {
      "name": "example-plugin",
      "source": "./example-plugin",
      "description": "Example plugin",
      "version": "1.0.0",
      "keywords": ["example"],
      "category": "productivity"
    }
  ]
}

Team Distribution

Configure automatic marketplace availability via .claude/settings.json:

{
  "extraKnownMarketplaces": [
    {
      "source": {
        "source": "github",
        "repo": "company/marketplace"
      }
    }
  ]
}

Plugin Structure Reference

Directory Hierarchy

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin metadata manifest
├── commands/                 # Optional: Custom slash commands
├── 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

Plugin Manifest (plugin.json)

Location: .claude-plugin/plugin.json (must be in this directory)

Required fields:

• name: Unique identifier (kebab-case)

Standard metadata:

• version: Semantic versioning (e.g., "1.0.0")
• description: Plugin purpose
• author: Object with name, email, url
• homepage: URL
• repository: URL
• license: SPDX identifier
• keywords: Array of search terms

Component paths (optional):

• commands: Path to commands directory
• agents: Path to agents directory
• hooks: Path to hooks configuration
• mcpServers: Path to MCP configuration

Example plugin.json

{
  "name": "example-plugin",
  "version": "1.0.0",
  "description": "Example plugin for demonstration",
  "author": {
    "name": "Plugin Creator",
    "email": "creator@example.com"
  },
  "keywords": ["example", "demo"]
}

Component Types

Commands

Location: commands/ directory Format: Markdown files with frontmatter Naming: Subdirectories create namespaces via :

commands/
├── simple.md              # Invoked as /simple
└── namespace/
    └── command.md         # Invoked as /namespace:command

Agents

Location: agents/ directory Format: Markdown files describing agent capabilities

Skills

Location: skills/ directory Format: Subdirectories with SKILL.md file Structure: See skills documentation

Hooks

Location: hooks/hooks.json or path specified in manifest Events: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact

MCP Servers

Location: .mcp.json at plugin root Purpose: External tool integrations

Path Requirements

• All paths relative to plugin root
• Start with ./ for custom paths
• Use ${CLAUDE_PLUGIN_ROOT} for dynamic resolution in hooks/MCP
• Components must be at plugin root, not inside .claude-plugin/

Plugin Development Workflows

Creating a New Plugin

1. Create Plugin Directory Structure

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

2. Create Plugin Manifest

Create 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. Add Plugin to Marketplace

Update .claude-plugin/marketplace.json by adding entry to plugins array:

{
  "name": "plugin-name",
  "source": "./plugins/plugin-name",
  "description": "Plugin description",
  "version": "0.1.0",
  "keywords": ["keyword1", "keyword2"],
  "category": "productivity"
}

4. Add Plugin Components

Create commands, skills, agents, or hooks as needed in their respective directories.

Version Bumping

When making changes to a plugin, update version in both locations:

1. plugins/<plugin-name>/.claude-plugin/plugin.json 2. .claude-plugin/marketplace.json (matching plugin entry)

Semantic versioning:

• Major (x.0.0): Breaking changes
• Minor (0.x.0): New features, refactoring
• Patch (0.0.x): Bug fixes, documentation only

Local Testing Workflow

Initial Setup

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

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

Iterative Testing

After making changes to a plugin:

# Uninstall
/plugin uninstall plugin-name@marketplace-name

# Reinstall
/plugin install plugin-name@marketplace-name

# Restart Claude Code to load changes

Note: Claude Code caches plugin files, so restart may be required for changes to take effect.

Publishing Workflow

1. Commit Changes

Use conventional commits:

git add .
git commit -m "feat: add new plugin"
git commit -m "fix: correct plugin manifest"
git commit -m "docs: update plugin README"

2. Push to Repository

git push origin main

3. Distribution

GitHub-hosted marketplace:

Users add via:

/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace-name

Local marketplace:

Users add via absolute path:

/plugin marketplace add /path/to/marketplace

Command Naming Convention

Commands use subdirectory-based namespacing:

• File: commands/namespace/command.md
• Invoked as: /namespace:command
• The : represents directory separator /

Examples:

• commands/prime/vue.md → /prime:vue
• commands/docs/generate.md → /docs:generate
• commands/simple.md → /simple

Common Plugin Patterns

Framework Plugin

Structure for framework-specific guidance (React, Vue, Nuxt, etc.):

plugins/framework-name/
├── .claude-plugin/plugin.json
├── skills/
│   └── framework-name/
│       ├── SKILL.md              # Quick reference
│       └── references/           # Library-specific patterns
├── commands/
│   └── prime/                    # Namespace for loading patterns
│       ├── components.md
│       └── framework.md
└── README.md

Utility Plugin

Structure for tools and utilities:

plugins/utility-name/
├── .claude-plugin/plugin.json
├── commands/
│   ├── action1.md
│   └── action2.md
└── README.md

Domain Plugin

Structure for domain-specific knowledge:

plugins/domain-name/
├── .claude-plugin/plugin.json
├── skills/
│   └── domain-name/
│       ├── SKILL.md
│       ├── references/
│       │   ├── schema.md
│       │   └── policies.md
│       └── scripts/
│           └── automation.py
└── README.md