Plugin Builder

Overview

plugin-builder automates the entire Claude Code plugin creation and distribution process. It generates valid plugin structures, manifests, validates compliance, packages existing skills, and prepares plugins for marketplace distribution.

Purpose: Transform skills into distributable plugins in minutes instead of hours

Key Capabilities:

• Initialize plugin directory structure
• Generate valid plugin.json and marketplace.json manifests
• Validate plugin structure and 2025 schema compliance
• Package existing skills into plugin format
• Automate repetitive plugin tasks

Pattern: Task-based (independent operations, flexible order)

Time Savings: 2-4 hours manual work → 15-30 minutes automated

What Are Claude Code Plugins?

Plugins are distributable packages that extend Claude Code with custom functionality. They can contain:

• Skills: Agent capabilities (what we have 32 of!)
• Commands: Custom slash commands
• Agents: Specialized subagents
• Hooks: Event handlers
• MCP Servers: External tool integrations

Distribution: Plugins are shared via Git-based marketplaces. Users install with:

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

Structure:

plugin-name/
├── .claude-plugin/
│   ├── plugin.json           # Required: Plugin metadata
│   └── marketplace.json      # Optional: For distribution
├── skills/                    # Your skills go here
├── commands/                  # Custom commands (optional)
├── agents/                    # Subagents (optional)
└── README.md                  # Recommended: Documentation

When to Use

Use plugin-builder when you need to:

Creating Plugins:

• Package your skills for distribution
• Create installable skill collections
• Share skills with your team
• Publish to community marketplaces

Validation & Quality:

• Validate plugin structure before publishing
• Ensure 2025 schema compliance
• Check manifest correctness
• Verify component formatting

Distribution Setup:

• Create team/organization marketplaces
• Set up GitHub distribution
• Configure multi-plugin catalogs

Bulk Operations:

• Convert multiple skills to plugins
• Package entire skill ecosystems
• Migrate existing skills to plugin format

Prerequisites

Before using plugin-builder:

Knowledge:

• Basic understanding of Claude Code skills
• Familiarity with terminal/command line
• Basic JSON concepts (scripts generate it for you)

Tools:

• Python 3.8+ installed
• Skills/commands/agents to package (for packaging operations)
• Git installed (for marketplace distribution)

Optional:

• GitHub account (for public distribution)
• Text editor (for manual manifest edits)

Operations

Operation 1: Initialize Plugin Structure

Create a complete plugin directory structure with minimal configuration.

Purpose: Quickly scaffold a new plugin with correct structure and minimal boilerplate

When to Use:

• Starting a new plugin from scratch
• Need proper directory layout
• Want generated README template

Prerequisites:

• Plugin name decided (kebab-case recommended)
• Basic metadata known (description, author)

Inputs:

• Plugin name
• Optional: Description, author information

Process:

Method 1: Interactive Script (Recommended)

cd /path/to/your/workspace
python /path/to/plugin-builder/scripts/init_plugin.py

Follow prompts:

1. Enter plugin name (will create directory with this name)
2. Enter description (brief, 1-2 sentences)
3. Enter author name
4. Enter author email (optional)
5. Choose components to include (skills/commands/agents)

Method 2: Command Line

python /path/to/plugin-builder/scripts/init_plugin.py my-plugin \
  --description "My awesome plugin" \
  --author "Your Name" \
  --email "you@example.com" \
  --components skills,commands

Method 3: Manual Creation

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills
mkdir -p my-plugin/commands  # optional
mkdir -p my-plugin/agents    # optional

# Create minimal plugin.json
cat > my-plugin/.claude-plugin/plugin.json <<'EOF'
{
  "name": "my-plugin"
}
EOF

# Create README
cat > my-plugin/README.md <<'EOF'
# My Plugin

Description of what this plugin does.

## Installation

\`\`\`bash
/plugin marketplace add your-username/your-repo
/plugin install my-plugin
\`\`\`
EOF

Outputs:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Minimal manifest (name only)
├── skills/               # If selected
├── commands/             # If selected
├── agents/               # If selected
└── README.md             # Template with installation instructions

Validation:

• [ ] Directory created with correct name
• [ ] .claude-plugin/plugin.json exists with valid JSON
• [ ] README.md exists
• [ ] Selected component directories created

Example:

# Interactive mode
$ python scripts/init_plugin.py

Enter plugin name (kebab-case): team-toolkit
Enter description: Development tools for our team
Enter author name: DevOps Team
Enter author email (optional): devops@company.com
Include skills? (y/n): y
Include commands? (y/n): y
Include agents? (y/n): n

Creating plugin structure...
✓ Created team-toolkit/
✓ Created .claude-plugin/plugin.json
✓ Created README.md
✓ Created skills/
✓ Created commands/

Next steps:
1. Add your skills to team-toolkit/skills/
2. Add your commands to team-toolkit/commands/
3. Run: python scripts/generate_manifest.py team-toolkit/
4. Run: python scripts/validate_plugin.py team-toolkit/

See Also: templates/plugin.json.minimal for the generated manifest structure

---

Operation 2: Generate plugin.json

Create or update the plugin manifest file with complete metadata.

Purpose: Generate a valid, schema-compliant plugin.json with all recommended fields

When to Use:

• After initializing plugin structure
• Need to add/update metadata
• Want all optional fields included
• Upgrading from minimal to complete manifest

Prerequisites:

• Plugin directory exists
• Plugin name decided
• Metadata information available

Inputs:

• Plugin name (required)
• Version (recommended, default: 1.0.0)
• Description (recommended)
• Author information (optional but recommended)
• Homepage URL (optional)
• Repository URL (optional)
• License (optional, default: MIT)
• Keywords (optional, for discoverability)
• Component paths (optional, uses defaults)

Process:

Method 1: Interactive Script (Recommended)

python scripts/generate_manifest.py /path/to/my-plugin

Follow prompts for each field. Press Enter to accept defaults or skip optional fields.

Method 2: Update Existing Manifest

python scripts/generate_manifest.py /path/to/my-plugin --update

Loads existing manifest, prompts only for changes/additions.

Method 3: Use Template

python scripts/generate_manifest.py /path/to/my-plugin --template standard

Templates available:

• minimal: Name only (valid but basic)
• standard: Name, version, description, author (recommended)
• complete: All fields with examples

Method 4: Manual Creation

Copy from templates/plugin.json.standard and edit:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of plugin functionality",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "keywords": ["keyword1", "keyword2"],
  "license": "MIT"
}

Save to my-plugin/.claude-plugin/plugin.json.

Outputs:

• Valid plugin.json in .claude-plugin/ directory
• JSON formatted and validated
• All required fields present
• Optional fields included as specified

Validation:

• [ ] JSON syntax is valid
• [ ] Name field present (required)
• [ ] Name is kebab-case
• [ ] Version follows semver if present
• [ ] No absolute paths
• [ ] File saved in correct location

Example:

$ python scripts/generate_manifest.py team-toolkit/

Generating plugin.json for team-toolkit
======================================

Name: team-toolkit (from directory)
Version [1.0.0]: 2.1.0
Description: Development and deployment tools for engineering team
Author name: DevOps Team
Author email: devops@company.com
Author URL (optional): https://company.com/devops
Homepage (optional): https://github.com/company/team-toolkit
Repository (optional): https://github.com/company/team-toolkit
License [MIT]: Apache-2.0
Keywords (comma-separated): deployment,ci-cd,automation,team

Component paths (optional, press Enter for defaults):
Skills path [./skills/]:
Commands path [./commands/]:
Agents path:

Generated plugin.json:
{
  "name": "team-toolkit",
  "version": "2.1.0",
  "description": "Development and deployment tools for engineering team",
  "author": {
    "name": "DevOps Team",
    "email": "devops@company.com",
    "url": "https://company.com/devops"
  },
  "homepage": "https://github.com/company/team-toolkit",
  "repository": "https://github.com/company/team-toolkit",
  "license": "Apache-2.0",
  "keywords": ["deployment", "ci-cd", "automation", "team"]
}

✓ Saved to team-toolkit/.claude-plugin/plugin.json
✓ Validation: All checks passed

Next steps:
1. Review generated manifest
2. Package your skills: python scripts/package_skills.py
3. Validate: python scripts/validate_plugin.py team-toolkit/

Tips:

• Use semantic versioning (MAJOR.MINOR.PATCH)
• Include keywords for discoverability
• Add repository URL for open source plugins
• Keep description under 200 characters
• Use kebab-case for plugin name

See Also:

• references/plugin-json-schema.md - Complete field reference
• templates/ - All manifest templates

---

Operation 3: Generate marketplace.json

Create a marketplace catalog file for distributing one or more plugins.

Purpose: Set up a marketplace for team/community distribution of plugins

When to Use:

• Distributing plugins via GitHub repository
• Creating team marketplace
• Publishing multiple plugins
• Setting up plugin catalog

Prerequisites:

• One or more plugins ready for distribution
• Marketplace name decided
• Owner information available

Inputs:

• Marketplace name (required)
• Owner name and email (required)
• Plugin entries (required):
  • Plugin name
  • Source (path, GitHub repo, or git URL)
  • Description
  • Category (optional)
  • Version (optional)

Process:

Method 1: Interactive Script (Recommended)

python scripts/generate_marketplace.py

Follow prompts:

1. Marketplace name (kebab-case)
2. Marketplace description
3. Owner name and email
4. Plugin source directory (optional, for auto-discovery)
5. For each plugin:
   • Name
   • Source (local path, GitHub, git URL)
   • Description
   • Category
   • Version

Method 2: Auto-Discover Plugins

python scripts/generate_marketplace.py --scan plugins/

Automatically finds plugins in directory and prompts for metadata.

Method 3: Manual Creation

Copy from templates/marketplace.json.minimal and edit:

{
  "name": "my-marketplace",
  "description": "Curated plugins for my team",
  "owner": {
    "name": "Team Name",
    "email": "team@company.com"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "description": "First plugin",
      "source": "./plugins/plugin-one",
      "category": "development"
    }
  ]
}

Save to repository root as .claude-plugin/marketplace.json.

Outputs:

• Valid marketplace.json file
• All plugins listed with metadata
• Ready for Git repository hosting

Validation:

• [ ] JSON syntax valid
• [ ] Required fields present (name, owner, plugins)
• [ ] All plugin sources are valid
• [ ] Plugin names are kebab-case
• [ ] Categories are standard (development, productivity, security, learning)

Example:

$ python scripts/generate_marketplace.py --scan company-plugins/

Generating marketplace.json
===========================

Scanning company-plugins/ for plugins...
Found 3 plugins:
  - deployment-tools
  - security-scanner
  - test-automation

Marketplace name: company-approved-plugins
Marketplace description: Approved plugins for Company use
Owner name: Engineering Team
Owner email: engineering@company.com

Plugin 1: deployment-tools
  Description: Automated deployment and rollback tools
  Category [development]:
  Version [1.0.0]: 2.1.0
  Source [./plugins/deployment-tools]:

Plugin 2: security-scanner
  Description: Security analysis and vulnerability detection
  Category [security]:
  Version [1.0.0]: 1.5.0
  Source [./plugins/security-scanner]:

Plugin 3: test-automation
  Description: Automated testing framework and utilities
  Category [development]:
  Version [1.0.0]: 3.0.0
  Source [./plugins/test-automation]:

Generated marketplace.json (3 plugins)
✓ Saved to .claude-plugin/marketplace.json
✓ Validation: All checks passed

Next steps:
1. Create GitHub repository
2. Push marketplace.json to repo root
3. Users can add: /plugin marketplace add company/company-plugins
4. Users can install: /plugin install deployment-tools@company-approved-plugins

Distribution Setup:

After generating marketplace.json:

1. Create GitHub Repository:

   cd /path/to/marketplace
   git init
   git add .
   git commit -m "Initial marketplace setup"
   git remote add origin git@github.com:username/my-marketplace.git
   git push -u origin main

2. Users Add Marketplace:

   /plugin marketplace add username/my-marketplace

3. Users Install Plugins:

   /plugin install plugin-name@my-marketplace

See Also:

• references/marketplace-json-schema.md - Complete schema
• references/distribution-guide.md - Setup instructions
• templates/marketplace.json.multi - Multi-plugin example

---

Operation 4: Validate Plugin

Comprehensive validation of plugin structure, manifests, and component compliance.

Purpose: Ensure plugin is correctly structured and ready for distribution

When to Use:

• Before publishing to marketplace
• After making changes to plugin
• Before creating GitHub release
• Troubleshooting plugin issues
• Ensuring 2025 schema compliance

Prerequisites:

• Plugin directory exists
• plugin.json file exists

Inputs:

• Plugin directory path

Process:

Method 1: Script Validation (Comprehensive)

python scripts/validate_plugin.py /path/to/my-plugin

Method 2: Verbose Output

python scripts/validate_plugin.py /path/to/my-plugin --verbose

Shows detailed checks and reasoning.

Method 3: Specific Validation Type

# Structure only
python scripts/validate_plugin.py /path/to/my-plugin --check structure

# Manifests only
python scripts/validate_plugin.py /path/to/my-plugin --check manifests

# Components only (skills, commands, agents)
python scripts/validate_plugin.py /path/to/my-plugin --check components

# 2025 schema compliance
python scripts/validate_plugin.py /path/to/my-plugin --check 2025

Validation Categories:

1. Structure Validation:

• [x] .claude-plugin/ directory exists
• [x] plugin.json exists in .claude-plugin/
• [x] Component directories at plugin root (NOT in .claude-plugin/)
• [x] Directory names are kebab-case
• [x] README.md exists (recommended)

2. Manifest Validation:

• [x] plugin.json is valid JSON
• [x] Required field name present
• [x] Name is kebab-case (no spaces, underscores)
• [x] Version follows semver if present
• [x] No absolute paths (all paths relative with ./)
• [x] Referenced files in manifest actually exist

3. Component Validation:

• [x] Skills have SKILL.md files
• [x] Skills have valid YAML frontmatter
• [x] Skills have allowed-tools field (2025 schema)
• [x] Commands have valid markdown with frontmatter
• [x] Agents have proper markdown structure
• [x] No placeholder TODO comments in production files

4. 2025 Schema Compliance:

• [x] All skills have allowed-tools field in frontmatter
• [x] allowed-tools lists valid Claude Code tools
• [x] Frontmatter format is correct

Outputs:

Success Example:

Validating plugin: team-toolkit
================================

✓ Structure validation passed (5/5 checks)
  ✓ .claude-plugin/ directory exists
  ✓ plugin.json exists
  ✓ Component directories at root
  ✓ Directory names valid
  ✓ README.md present

✓ Manifest validation passed (6/6 checks)
  ✓ Valid JSON syntax
  ✓ Required fields present
  ✓ Name format valid
  ✓ Version format valid
  ✓ Paths are relative
  ✓ Referenced files exist

✓ Component validation passed (8 skills, 3 commands)
  ✓ All skills have SKILL.md
  ✓ All skills have valid frontmatter
  ✓ All skills have allowed-tools field
  ✓ All commands valid

✓ 2025 schema compliance passed

================
RESULT: PASSED
================
0 errors, 0 warnings

✓ Plugin is ready for distribution!

Error Example:

Validating plugin: my-plugin
============================

✗ Structure validation failed (4/5 checks)
  ✓ .claude-plugin/ directory exists
  ✓ plugin.json exists
  ✗ Component directories at root
    ERROR: skills/ directory found in .claude-plugin/ (should be at plugin root)
  ✓ Directory names valid
  ✓ README.md present

✗ Manifest validation failed (5/6 checks)
  ✓ Valid JSON syntax
  ✓ Required fields present
  ✗ Paths are relative
    ERROR: "commands" field has absolute path: /home/user/commands
    FIX: Change to relative path: ./commands
  ✓ Referenced files exist

✗ Component validation failed (2/3 skills)
  ✓ All skills have SKILL.md
  ✗ Skills missing allowed-tools field
    ERROR: skills/my-skill/SKILL.md missing allowed-tools in frontmatter
    FIX: Add "allowed-tools: Read, Write, Bash" to YAML frontmatter

================
RESULT: FAILED
================
3 errors, 0 warnings

Fix errors above before distributing plugin.

Exit Codes:

• 0: All validation passed, plugin ready
• 1: Errors found, plugin not ready
• 2: Script execution error

Common Errors and Fixes:

Error: Component directory in .claude-plugin/

ERROR: skills/ found in .claude-plugin/ (should be at plugin root)
FIX: Move skills/ to plugin root directory

Error: Absolute paths in manifest

ERROR: "skills" field has absolute path: /Users/me/skills
FIX: Change to relative path: ./skills

Error: Missing allowed-tools field

ERROR: skill missing allowed-tools in frontmatter (2025 schema)
FIX: Add to SKILL.md frontmatter:
---
name: my-skill
description: ...
allowed-tools: Read, Write, Glob, Bash
---

Error: Invalid JSON syntax

ERROR: plugin.json has invalid JSON (trailing comma)
FIX: Remove trailing comma in JSON file

Error: Non-kebab-case name

ERROR: Plugin name "my_plugin" should be kebab-case
FIX: Change name to "my-plugin"

Validation Checklist:

Before publishing, ensure all pass:

• [ ] Structure validation: 0 errors
• [ ] Manifest validation: 0 errors
• [ ] Component validation: 0 errors
• [ ] 2025 compliance: All skills have allowed-tools
• [ ] README exists and is complete
• [ ] Test installation locally

See Also:

• references/validation-rules.md - Complete validation rules
• references/plugin-json-schema.md - Schema reference

---

Operation 5: Package Skills

Copy existing skills into plugin structure and update manifest.

Purpose: Convert standalone skills into plugin-packaged skills ready for distribution

When to Use:

• Converting .claude/skills/ to plugin format
• Packaging skill collections
• Migrating existing skills to plugins
• Creating skill-focused plugins

Prerequisites:

• Plugin structure initialized
• Skills exist in source directory
• Skills are 2025-compliant (or will be validated and flagged)

Inputs:

• Source skills directory path
• Target plugin path
• Optional: Specific skills to package (default: all)
• Optional: Validation mode (strict/warn)

Process:

Method 1: Package All Skills

python scripts/package_skills.py /path/to/skills /path/to/plugin

Copies all skills from source to plugin/skills/ directory.

Method 2: Package Specific Skills

python scripts/package_skills.py /path/to/skills /path/to/plugin \
  --skills skill1,skill2,skill3

Method 3: Package with Validation

python scripts/package_skills.py /path/to/skills /path/to/plugin --validate

Validates each skill for 2025 compliance before packaging.

Method 4: Dry Run (Preview)

python scripts/package_skills.py /path/to/skills /path/to/plugin --dry-run

Shows what would be packaged without actually copying.

What Happens:

1. Scans Source Directory:

   • Finds all skill directories
   • Identifies skills with SKILL.md files
   • Lists skills to be packaged

2. Validates Skills (if --validate):

   • Checks SKILL.md exists
   • Validates YAML frontmatter
   • Checks for allowed-tools field (2025 schema)
   • Reports warnings for missing fields

3. Copies Skills:

   • Creates plugin/skills/ if doesn't exist
   • Copies each skill directory
   • Preserves structure (SKILL.md, references/, scripts/)
   • Copies all files (no modification)

4. Updates Manifest:

   • Adds skills to plugin.json
   • Updates skills array (if field exists)
   • Preserves existing manifest fields

5. Reports Results:

   • Number of skills packaged
   • Any warnings or issues
   • Next steps

Outputs:

plugin/
├── .claude-plugin/
│   └── plugin.json          # Updated with skills reference
├── skills/
│   ├── skill1/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   └── scripts/
│   ├── skill2/
│   │   └── SKILL.md
│   └── skill3/
│       ├── SKILL.md
│       └── references/
└── README.md

Validation:

• [ ] All skills copied successfully
• [ ] Directory structure preserved
• [ ] SKILL.md files exist in each skill
• [ ] plugin.json updated (if applicable)
• [ ] 2025 compliance checked

Example:

$ python scripts/package_skills.py .claude/skills skrillz-ecosystem --validate

Packaging skills into plugin: skrillz-ecosystem
==============================================

Scanning .claude/skills for skills...
Found 32 skills:
  ✓ analysis
  ✓ anthropic-expert
  ✓ auto-updater
  ... (29 more)

Validating skills (2025 schema compliance)...
  ✓ analysis: Valid (allowed-tools present)
  ✓ anthropic-expert: Valid (allowed-tools present)
  ⚠ legacy-skill: WARNING - Missing allowed-tools field
  ... (checking all 32)

Results: 31 valid, 1 warning

Packaging skills...
  ✓ Copied analysis (245 KB, 3 files)
  ✓ Copied anthropic-expert (1.2 MB, 12 files)
  ✓ Copied auto-updater (180 KB, 5 files)
  ... (29 more)

✓ 32 skills packaged successfully
✓ Total size: 15.8 MB
✓ Updated plugin.json

Warnings:
  ⚠ legacy-skill missing allowed-tools field (2025 compliance)
    Add to SKILL.md frontmatter: allowed-tools: Read, Write, Bash

Next steps:
1. Fix warnings (add allowed-tools to legacy-skill)
2. Review plugin/skills/ directory
3. Update README.md with skill list
4. Validate: python scripts/validate_plugin.py skrillz-ecosystem
5. Test: /plugin install skrillz-ecosystem (local test)

Handling 2025 Compliance:

If skills are missing allowed-tools field:

1. Manual Fix: Add to SKILL.md frontmatter:

   ---
   name: my-skill
   description: Skill description
   allowed-tools: Read, Write, Edit, Glob, Bash
   ---

2. Common Tool Sets:

• Read-only analysis: Read, Grep, Glob
• File editing: Read, Write, Edit
• Automation: Read, Write, Bash
• Research: Read, WebSearch, WebFetch
• All tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch

3. Re-package after fixing:

   python scripts/package_skills.py .claude/skills plugin --validate

Tips:

• Use --validate to catch issues early
• Use --dry-run to preview before packaging
• Fix 2025 compliance warnings before distribution
• Keep original skills as backup
• Test plugin installation locally before publishing

See Also:

• references/component-packaging-guide.md - Detailed packaging guide
• references/validation-rules.md - 2025 compliance rules

---

Best Practices

Plugin Development

1. Start with MVP:

• Get basic plugin working first
• Add optional metadata later
• Test early, test often

2. Use Semantic Versioning:

• Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)
• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes

3. Write Good Descriptions:

• Clear, concise (under 200 chars)
• Explain what plugin does
• Mention key features
• Include use cases

4. Include Comprehensive README:

• Installation instructions
• Usage examples
• List of components
• Configuration options
• Troubleshooting

5. Validate Before Publishing:

python scripts/validate_plugin.py my-plugin/
# Should show 0 errors

6. Test Installation Locally:

# Create local marketplace
python scripts/generate_marketplace.py

# Test installation (if possible)
/plugin marketplace add ./my-marketplace
/plugin install my-plugin

Manifest Best Practices

1. Always Include:

• name: Clear, kebab-case identifier
• version: Semantic version
• description: What it does
• author: Who maintains it

2. Highly Recommended:

• keywords: For discoverability
• license: Legal clarity (MIT, Apache-2.0, etc.)
• repository: Source code location
• homepage: Documentation URL

3. Path Rules:

• Always use relative paths: ./skills/
• Never use absolute paths: /Users/me/skills
• Use forward slashes (cross-platform): ./path/to/file

4. Naming Conventions:

• Plugin names: kebab-case
• No spaces, underscores, or special chars
• Descriptive and memorable

2025 Schema Compliance

1. All Skills Must Have allowed-tools:

---
name: my-skill
description: What it does
allowed-tools: Read, Write, Bash
---

2. Common Tool Combinations:

• Analysis: Read, Grep, Glob
• Editing: Read, Write, Edit
• Automation: Read, Write, Bash
• Research: Read, WebSearch, WebFetch

3. Be Specific:

• Only list tools skill actually uses
• Don't include all tools if not needed
• Helps Claude optimize execution

Distribution Best Practices

1. GitHub Repository Setup:

• Clear repository name
• Comprehensive README.md
• LICENSE file
• .gitignore for OS files

2. Version Management:

• Tag releases: git tag v1.0.0
• Write changelogs
• Follow semver strictly

3. Documentation:

• Installation instructions
• Usage examples
• Component documentation
• Troubleshooting guide

4. Team Distribution:

• Use .claude/settings.json for team-wide:

  {
  "extraKnownMarketplaces": [
    {"source": "github", "repo": "company/approved-plugins"}
  ]
  }

Common Mistakes

Mistake 1: Component Directories in Wrong Location

❌ Wrong:

my-plugin/
└── .claude-plugin/
    ├── plugin.json
    └── skills/          # WRONG LOCATION

✅ Correct:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/              # AT PLUGIN ROOT

Why: Claude looks for components at plugin root, not in .claude-plugin/

Fix: Move component directories to plugin root

---

Mistake 2: Absolute Paths in Manifests

❌ Wrong:

{
  "name": "my-plugin",
  "skills": "/Users/me/my-plugin/skills"
}

✅ Correct:

{
  "name": "my-plugin",
  "skills": "./skills"
}

Why: Absolute paths break on other machines

Fix: Use relative paths starting with ./

---

Mistake 3: Non-Kebab-Case Names

❌ Wrong:

{
  "name": "My_Plugin"     // Underscores and capitals
}

✅ Correct:

{
  "name": "my-plugin"     // Kebab-case
}

Why: Naming convention expected by Claude Code

Fix: Use lowercase with hyphens

---

Mistake 4: Missing allowed-tools (2025 Schema)

❌ Wrong:

---
name: my-skill
description: What it does
---

✅ Correct:

---
name: my-skill
description: What it does
allowed-tools: Read, Write, Bash
---

Why: 2025 schema requires explicit tool permissions

Fix: Add allowed-tools field to all skills

---

Mistake 5: Invalid JSON Syntax

❌ Wrong:

{
  "name": "my-plugin",
  "version": "1.0.0",    // Trailing comma
}

✅ Correct:

{
  "name": "my-plugin",
  "version": "1.0.0"
}

Why: JSON doesn't allow trailing commas

Fix: Remove trailing commas, validate JSON

---

Mistake 6: No README

❌ Wrong:

my-plugin/
├── .claude-plugin/plugin.json
└── skills/

✅ Correct:

my-plugin/
├── .claude-plugin/plugin.json
├── README.md           # Installation & usage
└── skills/

Why: Users need to understand what plugin does and how to install it

Fix: Create README with installation instructions

---

Mistake 7: Not Validating Before Publishing

❌ Wrong:

git push origin main    # Push without validation

✅ Correct:

python scripts/validate_plugin.py my-plugin/
# Fix any errors
git push origin main

Why: Catch errors before users try to install

Fix: Always validate before publishing

---

Mistake 8: No Version Bumping

❌ Wrong:

{
  "version": "1.0.0"     // Never changes
}

✅ Correct:

{
  "version": "1.1.0"     // Bumped for each release
}

Why: Users need to know when updates are available

Fix: Bump version for each release following semver

---

Quick Reference

Essential Commands

# Initialize new plugin
python scripts/init_plugin.py my-plugin

# Generate manifest (interactive)
python scripts/generate_manifest.py my-plugin/

# Generate marketplace
python scripts/generate_marketplace.py

# Validate plugin
python scripts/validate_plugin.py my-plugin/

# Package skills
python scripts/package_skills.py .claude/skills my-plugin/

# Package with validation
python scripts/package_skills.py .claude/skills my-plugin/ --validate

Plugin Structure

plugin-name/
├── .claude-plugin/
│   ├── plugin.json           # Required: Metadata
│   └── marketplace.json      # Optional: Distribution
├── skills/                    # Your skills
├── commands/                  # Custom slash commands
├── agents/                    # Specialized agents
└── README.md                  # Recommended: Docs

plugin.json Minimal

{
  "name": "my-plugin"
}

plugin.json Standard

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "keywords": ["keyword1", "keyword2"],
  "license": "MIT"
}

marketplace.json

{
  "name": "my-marketplace",
  "description": "Plugin marketplace",
  "owner": {
    "name": "Maintainer",
    "email": "maintainer@example.com"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "description": "First plugin",
      "source": "./plugins/plugin-one",
      "category": "development"
    }
  ]
}

2025 Skill Frontmatter

---
name: my-skill
description: What it does. Use when [triggers].
allowed-tools: Read, Write, Bash
---

Validation Checklist

Before publishing:

• [ ] Run python scripts/validate_plugin.py my-plugin/
• [ ] 0 errors, 0 warnings
• [ ] README.md exists and is complete
• [ ] All skills have allowed-tools field
• [ ] Version number bumped (if updating)
• [ ] Git tag created for release
• [ ] Test installation locally

Distribution Workflow

1. Create Plugin:

   python scripts/init_plugin.py my-plugin
   python scripts/generate_manifest.py my-plugin/
   python scripts/package_skills.py .claude/skills my-plugin/

2. Validate:

   python scripts/validate_plugin.py my-plugin/

3. Create Marketplace:

   python scripts/generate_marketplace.py

4. Push to GitHub:

   cd my-marketplace
   git init
   git add .
   git commit -m "Initial plugin marketplace"
   git remote add origin git@github.com:username/my-marketplace.git
   git push -u origin main

5. Users Install:

   /plugin marketplace add username/my-marketplace
   /plugin install my-plugin@my-marketplace

Common Tool Sets (2025)

• Read-only: Read, Grep, Glob
• File editing: Read, Write, Edit
• Automation: Read, Write, Bash
• Research: Read, WebSearch, WebFetch
• Full access: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch

Script Help

All scripts support --help:

python scripts/init_plugin.py --help
python scripts/generate_manifest.py --help
python scripts/validate_plugin.py --help
python scripts/package_skills.py --help

---

Next Steps After MVP

This MVP includes the core operations needed to package and distribute plugins. Future enhancements could include:

Additional Operations:

• Package commands (Operation 6)
• Package agents (Operation 7)
• Update existing plugin (Operation 9)
• Bulk package multiple plugins (Operation 10)

Enhanced Features:

• Automated GitHub repo creation
• Change log generation
• Dependency resolution
• Plugin analytics

For Now: The MVP operations (1-5) are sufficient to:

• Create plugins
• Package your 32 skills
• Distribute via GitHub
• Validate compliance
• Share with team or community

---

References

Detailed guides for advanced topics:

• plugin-json-schema.md - Complete field reference, all options, examples
• marketplace-json-schema.md - Marketplace structure, source types, plugin entries
• validation-rules.md - All validation checks, error fixes, 2025 compliance

---

plugin-builder makes plugin creation fast, validated, and reliable. Use it to package your skills and share them with your team or the community!