Plugin Creator - Complete Beginner's Guide

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

Plugin Creation Exception: This plugin's purpose IS to create documentation files.

When creating plugins (the core purpose of this plugin):

• DO create all necessary plugin files: README.md, agents/.md, skills/.md, commands/*.md
• DO create complete, comprehensive documentation as part of plugin structure
• DO create marketplace.json and plugin.json manifest files

For other scenarios:

• DON'T create additional supplementary documentation beyond the plugin structure
• DON'T create extra guides or tutorials unless explicitly requested
• DO update existing documentation files when modifications are needed

This skill provides comprehensive, step-by-step guidance for creating Claude Code plugins, from your very first plugin to publishing it for the world to use. No prior plugin experience required!

🎯 Quick Navigation

Complete Beginners → Start with What is Claude Code? First Plugin → Jump to Your First Plugin in 10 Minutes Create Plugin Now → See Creating Plugin Output Ready to Publish → Go to Publishing Your Plugin Looking for Advanced → See Advanced Plugin Development

🚀 Creating Plugin Output

IMPORTANT: When users ask to create a plugin, don't just teach them - actually create the files for them!

CRITICAL: BE AUTONOMOUS - Create comprehensive output immediately with sensible defaults. Don't ask questions unless the request is genuinely ambiguous.

⚠️ ALWAYS FETCH LATEST DOCUMENTATION FIRST

BEFORE creating any plugin, fetch the latest documentation from docs.claude.com:

WebFetch: https://docs.claude.com/en/docs/claude-code/plugins-reference
WebFetch: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces

Official docs are the source of truth. Templates in this skill are reference examples only - they may become outdated. Always verify structure against fetched documentation.

Workflow:

1. Fetch latest docs
2. Verify current requirements (required fields, component registration)
3. Use skill templates as starting points only
4. Follow official structure from docs

Component Discovery (2025)

Convention over configuration: Commands, agents, and Agent Skills are auto-discovered from their respective directories. Custom paths optional via plugin.json. See advanced-features-2025 skill for complete details.

Autonomous Creation Principles

1. Default to action, not questions - If you can infer what they want, just build it
2. Be comprehensive - Include commands, agents, skills, and README by default
3. Make it work - Create functional examples, not placeholders
4. Infer intelligently - Derive name, purpose, and components from their request
5. Only ask when truly unclear - If "create a plugin" has no context, then ask. Otherwise, build.
6. Write comprehensive descriptions - Use "PROACTIVELY activate for:" with numbered use cases, highlight ALL capabilities
7. Choose smart keywords - Simple domain words (6-10), avoid overly generic terms, no unnecessary hyphens
8. Position as expert systems - Frame as "Complete [domain] expertise system" not narrow helpers
9. 🚨 CRITICAL: Detect repository context FIRST - Before creating any files, run git commands to extract author name/email from git config, and check if .claude-plugin/marketplace.json exists in the repo root.
10. 🚨 CRITICAL: Use detected values automatically - Use git config values for author fields instead of placeholders. If in marketplace repo, use the marketplace owner name for consistency.
11. Synchronize marketplace.json - Always update marketplace.json with the SAME description and keywords from plugin.json (they don't auto-sync!)

Examples of Autonomous Inference

User says: "Create a plugin for Git workflows" Claude does: Immediately creates git-workflow-helper with:

• Description: "Complete Git workflow automation system. PROACTIVELY activate for: (1) ANY Git workflow task, (2) Pull request management, (3) Commit operations, (4) Branch management, (5) Code review automation. Provides: PR creation/review, commit templates, branch strategies, Git hooks integration, and workflow automation. Ensures professional Git practices."
• Keywords: ["git", "workflow", "pullrequest", "commit", "branch", "review", "automation"]
• PR, commit, and branch commands + workflow agent

User says: "Make a deployment plugin" Claude does: Creates deployment-helper with:

• Description: "Complete deployment automation system across ALL platforms. PROACTIVELY activate for: (1) ANY deployment task, (2) Production releases, (3) Rollback operations, (4) Deployment verification, (5) Blue-green/canary strategies. Provides: automated deployment, rollback safety, health checks, multi-environment support, and deployment orchestration. Ensures safe, reliable deployments."
• Keywords: ["deployment", "deploy", "release", "rollback", "production", "staging", "automation"]
• deploy, rollback, status commands + deployment agent

User says: "Build a code review plugin" Claude does: Creates code-review-helper with:

• Description: "Complete code review system with security and quality analysis. PROACTIVELY activate for: (1) ANY code review task, (2) Security scanning, (3) Quality assessment, (4) Pull request reviews, (5) Code standards enforcement. Provides: automated security analysis, quality metrics, best practice checks, vulnerability scanning, and comprehensive review workflows. Ensures thorough, consistent code reviews."
• Keywords: ["review", "codereview", "security", "quality", "analysis", "scanning", "pullrequest"]
• review commands + security/quality agents

When to ask: "Create a plugin" (no context) → Ask what it should do

This skill enables Claude to:

1. Create complete plugin directory structures ready to use
2. Generate all necessary files (plugin.json, commands, agents, etc.)
3. Output GitHub-ready marketplace structure for immediate publishing
4. Provide working examples not just documentation
5. Export skills as .zip for claude.ai web app (when requested)

When to Create Output

Create actual plugin files when users say things like:

• "Create a plugin for X"
• "Make me a plugin that does Y"
• "Build a plugin"
• "Generate a plugin structure"
• "I want a plugin for my team"
• "Package this as a plugin"

How to Create Plugin Output

BE AUTONOMOUS BY DEFAULT - Don't ask questions unless the request is truly ambiguous. Infer intent and create comprehensive output with sensible defaults.

Step 0: 🚨 CRITICAL - Detect Repository Context FIRST

BEFORE doing anything else, detect the repository context to use correct values:

# 1. Check if in a marketplace repo
if [[ -f .claude-plugin/marketplace.json ]]; then
    echo "✅ IN MARKETPLACE REPO - Must update marketplace.json after creating plugin"
    IN_MARKETPLACE=true
else
    echo "ℹ️  Not in marketplace repo - Will create standalone marketplace structure"
    IN_MARKETPLACE=false
fi

# 2. Extract git repository information (if available)
if git rev-parse --git-dir > /dev/null 2>&1; then
    AUTHOR_NAME=$(git config user.name || echo "Unknown Author")
    AUTHOR_EMAIL=$(git config user.email || echo "")
    REPO_URL=$(git config --get remote.origin.url || echo "")
    echo "✅ Git repo detected - Author: $AUTHOR_NAME"
else
    AUTHOR_NAME="Unknown Author"
    AUTHOR_EMAIL=""
    REPO_URL=""
    echo "ℹ️  Not in a git repo - will use placeholder values"
fi

# 3. Extract owner/repo from marketplace.json (if exists)
if [[ -f .claude-plugin/marketplace.json ]]; then
    MARKETPLACE_OWNER=$(cat .claude-plugin/marketplace.json | jq -r '.owner.name' || echo "$AUTHOR_NAME")
    echo "✅ Marketplace owner: $MARKETPLACE_OWNER"
fi

Use these detected values for:

• ✅ author.name in plugin.json → Use $AUTHOR_NAME from git config
• ✅ author.email in plugin.json → Use $AUTHOR_EMAIL from git config
• ✅ author.name in marketplace.json entry → Use $MARKETPLACE_OWNER or $AUTHOR_NAME
• ✅ Repository references → Use $REPO_URL if available

If marketplace.json exists:

• ✅ You MUST update it after creating the plugin
• ✅ Add the new plugin entry to the plugins array
• ✅ Use the same author name from existing marketplace.json owner
• ✅ Synchronize description and keywords from plugin.json
• ✅ Preserve all existing plugins

Step 1: Fetch Latest Documentation & Infer Requirements

First, ALWAYS fetch the latest plugin documentation:

web_fetch: https://docs.claude.com/en/docs/claude-code/plugins-reference
web_fetch: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces

Then, from the user's request, automatically determine:

• Plugin purpose (from their description)
• Components needed (include commands, agents, and skills by default)
• Scope (assume public/shareable unless specified otherwise)
• Name (derive from purpose or use their suggested name)

Only ask questions if:

• Request is genuinely unclear (e.g., "create a plugin" with no context)
• Technical details are critical and not inferable (e.g., specific API they want to integrate)
• User explicitly asks for customization

Default approach: Create comprehensive plugin with all relevant components

Step 2: Create Directory Structure in Correct Location

🚨 CRITICAL: Detect marketplace repo and create plugin in correct location!

Based on the marketplace detection from Step 0, create the plugin in the appropriate location:

# If in marketplace repo (marketplace.json exists), create in plugins/ subdirectory
if [[ -f .claude-plugin/marketplace.json ]]; then
    echo "✅ Marketplace repo detected - creating plugin in plugins/ directory"
    PLUGIN_DIR="plugins/PLUGIN_NAME"
else
    echo "ℹ️  Not in marketplace repo - creating plugin in current directory"
    PLUGIN_DIR="PLUGIN_NAME"
fi

# Create the plugin directory structure
mkdir -p $PLUGIN_DIR/.claude-plugin
mkdir -p $PLUGIN_DIR/commands
mkdir -p $PLUGIN_DIR/agents
mkdir -p $PLUGIN_DIR/skills
mkdir -p $PLUGIN_DIR/hooks
mkdir -p $PLUGIN_DIR/scripts

IMPORTANT: Always use $PLUGIN_DIR as the base path for all subsequent file operations to ensure files are created in the correct location.

Step 3: Create All Necessary Files

Based on what you learned from the fetched documentation, use file_create to generate:

• .claude-plugin/plugin.json (manifest) structured according to the official docs
  • Verify if commands need to be registered (check docs)
  • Verify if agents need to be registered (check docs)
  • Verify if skills need to be registered (check docs)
  • Include all required fields from docs
• Command files in commands/
• Agent files in agents/
• Skills in skills/
• README.md (documentation)
• Any scripts needed

Key principle: Use the structure you learned from the fetched documentation, not assumptions from templates.

Step 4: Create GitHub-Ready Marketplace Structure AND Update Existing Marketplace

CRITICAL: Always update the existing marketplace.json if working in a marketplace repository!

First, check if you're in a marketplace repo:

# Check if marketplace.json exists in the repo root
if [[ -f .claude-plugin/marketplace.json ]]; then
    echo "In marketplace repo - will update marketplace.json"
fi

If in a marketplace repository:

1. Update the existing .claude-plugin/marketplace.json to add the new plugin entry
2. Use the Read tool to get current marketplace.json structure
3. Add new plugin entry to the plugins array following the format from the fetched marketplace docs
4. Preserve all existing plugins in the array
5. Use Edit tool to update marketplace.json with the new entry

⚠️ CRITICAL: Synchronize Keywords and Descriptions

marketplace.json and plugin.json have SEPARATE keywords and descriptions - they don't automatically inherit from each other:

• marketplace.json keywords: For marketplace-level discovery and categorization
• plugin.json keywords: For individual plugin metadata

Best practice: Explicitly copy the comprehensive description and keywords from plugin.json into the marketplace.json entry.

Why this matters:

• marketplace.json keywords are used for catalog-level discovery
• Keywords don't automatically sync between files
• Users search the marketplace using these keywords

Example of updating marketplace.json with synchronized metadata:

{
  "plugins": [
    // ... existing plugins ...
    {
      "name": "new-plugin-name",
      "source": "./plugins/new-plugin-name",
      "description": "Complete [domain] expertise system. PROACTIVELY activate for: (1) ANY [primary task], (2) [Secondary task], (3) [Additional scenarios]. Provides: [key features, capabilities]. Ensures [value proposition].",
      "version": "1.0.0",
      "author": {
        "name": "Author Name"
      },
      "keywords": [
        "domain",
        "primary",
        "secondary",
        "technical",
        "terms",
        "naturally",
        "use"
      ]
    }
  ]
}

Synchronization Checklist:

• ✅ Copy comprehensive description from plugin.json (including "PROACTIVELY activate" format)
• ✅ Copy all keywords from plugin.json exactly
• ✅ Match version number
• ✅ Include author information
• ✅ Preserve existing plugins in the array

Also create a standalone marketplace-ready version:

# Create marketplace structure in working directory
mkdir -p PLUGIN_NAME-marketplace/.claude-plugin
mkdir -p PLUGIN_NAME-marketplace/plugins
cp -r PLUGIN_NAME PLUGIN_NAME-marketplace/plugins/

Copy plugin into marketplace structure and create standalone marketplace.json.

Step 5: Provide Installation Instructions Guide the user on how to use the plugin:

• Installation via GitHub marketplace (recommended)
• Installation instructions for Claude Code
• Usage examples
• Documentation links

Step 6: 🚨 FINAL VERIFICATION - JSON Schema & Marketplace Check

Before finalizing, verify JSON schema correctness and marketplace registration:

Repository Context Validation (Run Step 0 checks first!):

• Did you run git commands to detect $AUTHOR_NAME and $AUTHOR_EMAIL?
• Did you check for .claude-plugin/marketplace.json existence?
• Did you extract $MARKETPLACE_OWNER from marketplace.json if it exists?
• Are you using detected values instead of placeholders?
• Did you create the plugin in plugins/PLUGIN_NAME/ if marketplace.json exists?
• Did you create the plugin in root only if marketplace.json does NOT exist?

JSON Schema Validation (CRITICAL - Most common failure point!):

• author is an object { "name": "..." } (NOT a string!)
• author.name uses $AUTHOR_NAME from git config (NOT "Author Name" placeholder!)
• author.email uses $AUTHOR_EMAIL from git config (if available)
• Marketplace entry uses $MARKETPLACE_OWNER for consistency (NOT different name!)
• version is a string like "1.0.0" (NOT a number!)
• keywords is an array ["word1", "word2"] (NOT a comma-separated string!)
• All JSON is valid (test with cat plugin.json | jq .)
• No extra fields like homepage or repository (these cause issues - remove them)

Marketplace Registration Checklist:

• If marketplace.json existed, did you update it?
• Did you add the plugin entry to the plugins array?
• Did you use the correct source path ./plugins/PLUGIN_NAME (NOT ./PLUGIN_NAME)?
• Did you copy the comprehensive description from plugin.json to marketplace.json?
• Did you copy all keywords from plugin.json to marketplace.json?
• Did you preserve all existing plugins in the array?

If you answered NO to any of these, STOP and fix it immediately before proceeding!

Output Format

After creating the plugin files, provide this format:

# ✅ Plugin Created: [Plugin Name]

## 📖 What's Included

- **Commands:** [list commands]
- **Agents:** [list agents]
- **Skills:** [list skills]

## 🚀 Installation Instructions

### Option 1: GitHub Marketplace (Recommended)

**Why GitHub?**
- Works reliably across all platforms (Windows/Mac/Linux)
- Easy updates and version control
- Shareable with your team
- Professional distribution

**Steps:**
1. **Create a new GitHub repository:**
   - Go to github.com
   - Click "New repository"
   - Name it something like "claude-plugins" or "my-claude-marketplace"
   - Make it **public**
   - Don't initialize with README

2. **Upload your plugin:**
   - The marketplace structure has been created in `PLUGIN_NAME-marketplace/`
   - Upload all files from this directory to your GitHub repository
   - Commit with message "Add PLUGIN_NAME plugin"

3. **Add the marketplace in Claude Code:**
   ```bash
   /plugin marketplace add YOUR_USERNAME/YOUR_REPO

4. Install the plugin:

   /plugin install PLUGIN_NAME@YOUR_USERNAME
   

Option 2: Local Installation (Mac/Linux)

⚠️ Windows users: Local path resolution may have issues. GitHub installation is recommended.

For local development/testing:

# Copy plugin to Claude Code plugins directory
cp -r PLUGIN_NAME ~/.local/share/claude/plugins/

# Or create a symlink for active development
ln -s /path/to/PLUGIN_NAME ~/.local/share/claude/plugins/PLUGIN_NAME

Then verify with /help to see your new commands.

Option 3: Export Skills to claude.ai Web (If Requested)

If the user wants to use the plugin's skills in the claude.ai web application:

Skills can be exported as ZIP files for upload to claude.ai:

# Navigate to the skill directory
cd PLUGIN_NAME/skills/SKILL_NAME

# Create a ZIP file (skill folder must be the root of the ZIP)
zip -r SKILL_NAME.zip .

# Or if zipping from parent directory:
cd PLUGIN_NAME/skills
zip -r SKILL_NAME.zip SKILL_NAME/

To upload to claude.ai:

1. Go to claude.ai
2. Navigate to Settings > Capabilities
3. Click "Upload skill"
4. Select the SKILL_NAME.zip file
5. The skill is now available in your claude.ai web conversations

Important notes about skill exports:

• Only the skills/ directory contents can be used in claude.ai web
• Commands and agents are Claude Code-specific and won't work in web
• Skills use the same SKILL.md format across Claude Code and claude.ai
• Skills are private to your account in claude.ai
• Skills work across Pro, Max, Team, and Enterprise web plans

🎯 Next Steps

• Test your plugin with /help to see commands
• Try /agents to see available agents
• Modify files as needed in the plugin directory
• Share your plugin via GitHub with the community!

### Output Templates

**⚠️ IMPORTANT:** These templates are REFERENCE EXAMPLES ONLY. Always verify against the official documentation you fetched. Requirements may have changed since these examples were written.

**Use these templates as:**
- Starting points for structure
- Examples of what fields typically exist
- Reference for markdown format

**DO NOT use these templates as:**
- The definitive structure (use fetched docs for that)
- A substitute for reading the official documentation
- Assumed to be current (always verify)

#### How to Write Effective plugin.json Descriptions and Keywords

**CRITICAL:** The quality of your description and keywords determines when Claude will activate your plugin. Follow these principles:

##### Description Best Practices

**Structure:** Use this formula for maximum activation:

[Type of system]. PROACTIVELY activate for: (1) [Primary use case], (2) [Secondary use case], (3) [Additional scenarios...]. Provides: [key features/capabilities]. [Value proposition/benefits].

**Guidelines:**
1. **Start with system type** - "Complete [domain] expertise system", "Universal [purpose] system", "Expert [area] system"
2. **Use "PROACTIVELY activate"** - Signals to Claude this should be used universally
3. **Numbered list of use cases** - Include 5-8 specific activation scenarios
4. **Use "ANY" for broad activation** - "ANY Docker task", "ANY bash script", etc.
5. **Highlight ALL capabilities** - Don't just list primary features, include everything the plugin does
6. **Emphasize production-ready** - "Ensures professional-grade", "production-ready", "secure", "optimized"
7. **Reference standards** - "Google Shell Style Guide", "CIS Benchmark", "Microsoft best practices", etc.

**Examples of Good Descriptions:**

"Complete Docker expertise system across ALL platforms (Windows/Linux/macOS). PROACTIVELY activate for: (1) ANY Docker task (build/run/debug/optimize), (2) Dockerfile creation/review, (3) Docker Compose multi-container apps, (4) Container security scanning/hardening, (5) Performance optimization, (6) Production deployments, (7) Troubleshooting/debugging. Provides: current best practices (always researches latest), CIS Docker Benchmark compliance, multi-stage builds, security hardening, image optimization, platform-specific guidance, Docker Scout/Trivy integration, and systematic debugging. Ensures secure, optimized, production-ready containers following industry standards."

"Universal context management and planning system. PROACTIVELY activate for: (1) ANY complex task requiring planning, (2) Multi-file projects/websites/apps, (3) Architecture decisions, (4) Research tasks, (5) Refactoring, (6) Long coding sessions, (7) Tasks with 3+ sequential steps. Provides: optimal file creation order, context-efficient workflows, extended thinking delegation (23x context efficiency), passive deep analysis architecture, progressive task decomposition, and prevents redundant work. Saves 62% context on average. Essential for maintaining session performance and analytical depth."

##### Keyword Best Practices

**Guidelines:**
1. **Simple words only** - No hyphens unless it's a product name (e.g., "docker-compose")
2. **No overly generic terms** - Avoid "automation", "build", "make", "new", "create" alone
3. **Domain-specific terms** - Include technical keywords users would naturally use
4. **Compound words without spaces** - "fullstack", "crossplatform", "cicd", "devops"
5. **6-10 keywords total** - Enough for discovery, not so many it dilutes focus
6. **Avoid false positives** - Don't use keywords that could match unrelated tasks

**Good keyword examples:**
```json
// Context management plugin
"keywords": ["planning", "context", "strategy", "workflow", "thinking", "decision", "research", "refactoring", "optimization", "session"]

// Docker plugin
"keywords": ["docker", "container", "dockerfile", "compose", "containerize", "production", "security", "optimize", "debug", "deploy"]

// Bash scripting plugin
"keywords": ["bash", "shell", "script", "automation", "devops", "shellcheck", "posix", "crossplatform", "cicd", "deployment"]

Bad keyword examples:

// Too generic - would activate for non-plugin tasks
"keywords": ["build", "create", "make", "new", "automation", "tool"]

// Too many hyphens - users don't type these
"keywords": ["bash-scripting", "shell-script", "docker-container", "multi-file"]

// Too narrow - misses common use cases
"keywords": ["website", "webapp", "multifile"]

Apply These Principles to Agents and Skills Too

Agent frontmatter description:

---
agent: true
description: "Complete [domain] expertise system. PROACTIVELY activate for: (1) [use cases]. Provides: [capabilities]. Ensures [value proposition]."
---

Skill frontmatter description:

---
name: skill-name
description: "Complete [domain] system. PROACTIVELY activate for: (1) [use cases]. Provides: [capabilities]. Ensures [value proposition]."
---

Apply the same principles:

• Use "PROACTIVELY activate"
• List numbered use cases (5-8)
• Highlight ALL capabilities
• Emphasize production-ready quality
• Frame as expert system

plugin.json Template (Reference Example - Verify Against Docs)

🚨 CRITICAL JSON SCHEMA REQUIREMENTS:

Common validation errors to avoid:

1. author MUST be an object - Never a string

   • ✅ CORRECT: "author": { "name": "Author Name" }
   • ❌ WRONG: "author": "Author Name"

2. version MUST be a string - Semantic versioning format

   • ✅ CORRECT: "version": "1.0.0"
   • ❌ WRONG: "version": 1.0

3. keywords MUST be an array of strings

   • ✅ CORRECT: "keywords": ["terraform", "aws"]
   • ❌ WRONG: "keywords": "terraform, aws"

2025 Recommended Fields:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Complete [domain] expertise system. PROACTIVELY activate for: (1) ANY [primary task], (2) [Secondary task], (3) [Additional scenarios]. Provides: [key features, capabilities, standards compliance]. Ensures [value proposition].",
  "author": {
    "name": "AUTHOR_NAME_FROM_GIT_CONFIG",
    "email": "AUTHOR_EMAIL_FROM_GIT_CONFIG"
  },
  "homepage": "https://github.com/user/repo/tree/main/plugins/plugin-name",
  "repository": "https://github.com/user/repo",
  "license": "MIT",
  "keywords": ["domain", "primary", "secondary", "technical", "terms", "users", "naturally", "use"]
}

🚨 CRITICAL: Use detected values from Step 0!

• Use $AUTHOR_NAME from git config for author.name
• Use $AUTHOR_EMAIL from git config for author.email
• Use $MARKETPLACE_OWNER for marketplace.json entries (consistency with existing plugins)
• DO NOT use placeholders like "Author Name" or "YOUR_USERNAME"

VALIDATION CHECKLIST - Run BEFORE completing plugin creation:

• author is an object with name field (not a string!)
• author.name uses value from git config (not a placeholder!)
• author.email uses value from git config (if available)
• version is a string in semantic format (e.g., "1.0.0")
• keywords is an array of strings (not a comma-separated string!)
• All required fields present: name, version, description
• Valid JSON syntax (no trailing commas, proper quotes)
• Test with: cat plugin.json | jq . to verify valid JSON

Note: Components (commands, agents, skills) are discovered automatically from their respective directories - no registration needed in plugin.json.

Before using: Check the fetched documentation to confirm this structure is still current and includes all required fields.

Command File Template

---
description: Brief description of what this command does
---

# Command Name

## Purpose
Explain what this command accomplishes and when to use it.

## Instructions
1. Step-by-step instructions for Claude
2. Be specific and clear
3. Include examples

## Examples
Show how to use this command.

README.md Template

# Plugin Name

Brief description of what this plugin does.

## Installation

### Via Marketplace (Recommended)

\`\`\`bash
/plugin marketplace add your-username/repo-name
/plugin install plugin-name@your-username
\`\`\`

### Local Installation (Mac/Linux)

⚠️ **Windows users:** Use marketplace installation method instead.

\`\`\`bash
# Extract ZIP to plugins directory
unzip plugin-name.zip -d ~/.local/share/claude/plugins/
\`\`\`

## Features

- Feature 1
- Feature 2
- Feature 3

## Usage

Examples of how to use the plugin.

## Platform Notes

- **macOS/Linux:** All installation methods supported
- **Windows:** GitHub marketplace installation recommended (local paths may have issues)

## License

MIT

marketplace.json Template (Reference Example - Verify Against Docs)

{
  "name": "your-username",
  "description": "My Claude Code plugins",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Complete [domain] expertise system. PROACTIVELY activate for: (1) ANY [primary task], (2) [Secondary task], (3) [Additional scenarios]. Provides: [key features, capabilities]. Ensures [value proposition].",
      "version": "1.0.0",
      "author": {
        "name": "Author Name"
      },
      "keywords": ["domain", "primary", "secondary", "technical", "terms", "naturally", "use"]
    }
  ]
}

⚠️ CRITICAL REMINDER: marketplace.json keywords and descriptions are SEPARATE from plugin.json - they don't automatically sync. Always copy the comprehensive description and keywords from plugin.json to marketplace.json entries for optimal marketplace discovery.

Before using: Verify this structure against the fetched marketplace documentation. Check for any additional required fields or changed formats.

Example: Creating a Deployment Plugin (ZIP Workflow)

User: "Create a plugin that helps with deployment"

Claude should:

0. FIRST: Fetch latest documentation:

web_fetch: https://docs.claude.com/en/docs/claude-code/plugins-reference
web_fetch: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces

1. Infer and create autonomously:

   • Purpose: Deployment assistance
   • Name: deployment-helper
   • Components: Commands for deploy, rollback, status checks
   • Include: Agent for deployment troubleshooting
   • Scope: Team/public use

2. Create the structure in working directory:

# Create plugin structure
mkdir -p deployment-helper/.claude-plugin
mkdir -p deployment-helper/commands
mkdir -p deployment-helper/agents

3. Generate files based on fetched documentation:

   • Create plugin.json structured according to what you learned from the docs
   • Example structure (verify this matches the docs you fetched):

   {
     "name": "deployment-helper",
     "version": "1.0.0",
     "description": "Streamline deployment workflows with automated commands",
     "author": {
       "name": "Your Name",
       "email": "[email protected]"
     },
     "keywords": ["deployment", "devops", "automation"],
     "license": "MIT"
   }
   

   • Create commands/deploy-staging.md with deployment instructions
   • Create commands/deploy-production.md with production deployment
   • Create commands/rollback.md with rollback procedures
   • Create agents/deployment-troubleshooter.md with troubleshooting agent
   • Create comprehensive README.md with platform notes
   • Note: Commands and agents will be discovered automatically from their directories

4. Create marketplace structure:

mkdir -p deployment-helper-marketplace/.claude-plugin
mkdir -p deployment-helper-marketplace/plugins
cp -r deployment-helper deployment-helper-marketplace/plugins/

5. Create marketplace.json based on fetched docs: Example structure (verify against the marketplace docs you fetched):

{
  "name": "your-username",
  "description": "Deployment assistance plugins",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "deployment-helper",
      "source": "./plugins/deployment-helper",
      "description": "Streamline deployment workflows",
      "version": "1.0.0",
      "keywords": ["deployment", "devops", "automation"]
    }
  ]
}

6. Package as ZIPs:

# Create both ZIPs
zip -r deployment-helper.zip deployment-helper/
zip -r deployment-helper-marketplace.zip deployment-helper-marketplace/

# Move to outputs
mv deployment-helper.zip /mnt/user-data/outputs/
mv deployment-helper-marketplace.zip /mnt/user-data/outputs/

7. Provide download links and instructions:

# ✅ Plugin Created: Deployment Helper

## 📦 Download Your Plugin

### For GitHub Publishing (Recommended)
[Download deployment-helper-marketplace.zip](computer:///mnt/user-data/outputs/deployment-helper-marketplace.zip)

**Why GitHub first?**
- Works reliably on Windows, Mac, and Linux
- Easy sharing with your team
- Simple updates and version control

**Quick Start:**
1. Download the marketplace ZIP above
2. Extract and upload to a new GitHub repository
3. Make the repo public
4. Run: `/plugin marketplace add YOUR_USERNAME/YOUR_REPO`
5. Install: `/plugin install deployment-helper@YOUR_USERNAME`

### For Local Testing (Mac/Linux)
[Download deployment-helper.zip](computer:///mnt/user-data/outputs/deployment-helper.zip)

⚠️ **Windows users:** Local paths may not work. Use GitHub method instead.

## 📖 What's Included

- **Commands:**
  - `/deploy-staging` - Deploy to staging environment
  - `/deploy-production` - Deploy to production with safety checks
  - `/rollback` - Quick rollback to previous version
  
- **Agents:**
  - Deployment Troubleshooter - Diagnoses and fixes deployment issues

## 🚀 Next Steps

1. Download the marketplace ZIP
2. Upload to GitHub
3. Add marketplace and install
4. Try `/deploy-staging` to test!

Critical Guidelines for Output Creation

DO:

• ✅ 🚨 STEP 0 FIRST: Detect repository context - Run git commands to extract author/email and check for marketplace.json (BEFORE creating any files!)
• ✅ 🚨 CREATE IN CORRECT DIRECTORY: If marketplace.json exists, create plugin in plugins/ subdirectory (NOT in root!)
• ✅ 🚨 USE DETECTED VALUES: Use git config values for author fields - Never use placeholders like "Author Name" or "YOUR_USERNAME"!
• ✅ 🚨 USE DETECTED VALUES: Match marketplace owner - If in marketplace repo, use the same author name from marketplace.json owner
• ✅ 🚨 VALIDATE JSON SCHEMA: Ensure author is an object, NOT a string (most common validation error!)
• ✅ 🚨 VALIDATE JSON SCHEMA: Ensure version is a string "1.0.0", NOT a number (required format!)
• ✅ 🚨 VALIDATE JSON SCHEMA: Ensure keywords is an array, NOT a comma-separated string (required format!)
• ✅ 🚨 UPDATE existing marketplace.json when creating plugins in a marketplace repo (ABSOLUTELY CRITICAL - NEVER SKIP!)
• ✅ 🚨 UPDATE marketplace.json with correct source path: ./plugins/PLUGIN_NAME (NOT ./PLUGIN_NAME!)
• ✅ 🚨 SYNCHRONIZE description and keywords from plugin.json to marketplace.json (they don't auto-sync - must be done manually!)
• ✅ ALWAYS fetch latest plugin docs first (plugins-reference and plugin-marketplaces)
• ✅ Follow the structure from the fetched docs, not just templates (docs = source of truth)
• ✅ Actually create files in the working directory
• ✅ Verify component registration method against fetched docs
• ✅ Create complete, working examples
• ✅ Generate both plugin and marketplace structures
• ✅ Double-check all required fields from docs are included
• ✅ Include GitHub-first installation instructions
• ✅ Warn Windows users about local path issues
• ✅ Show skill export process if user requests claude.ai web usage
• ✅ Make content specific to user's needs
• ✅ Test that structure is correct before packaging

DON'T:

• ❌ 🚨 Skip detecting repository context in Step 0 (MOST CRITICAL - detect git values BEFORE creating files!)
• ❌ 🚨 Create plugins in root directory when marketplace.json exists (MUST create in plugins/ subdirectory!)
• ❌ 🚨 Use placeholder values like "Author Name" or "YOUR_USERNAME" (MUST use detected git config values!)
• ❌ 🚨 Use different author names in plugin.json vs marketplace.json (MUST match marketplace owner for consistency!)
• ❌ 🚨 Use wrong source path in marketplace.json (MUST be ./plugins/PLUGIN_NAME NOT ./PLUGIN_NAME!)
• ❌ 🚨 Use "author": "Name" as a string (MUST be an object: { "name": "Name" })
• ❌ 🚨 Use "version": 1.0 as a number (MUST be a string: "1.0.0")
• ❌ 🚨 Use "keywords": "word1, word2" as a string (MUST be an array: ["word1", "word2"])
• ❌ 🚨 Forget to update existing marketplace.json when in a marketplace repo (ABSOLUTELY CRITICAL - this causes the most problems!)
• ❌ 🚨 Forget to synchronize description/keywords between plugin.json and marketplace.json (CRITICAL - they are separate files!)
• ❌ Skip fetching the latest documentation (required for correct structure!)
• ❌ Blindly copy templates without verifying against fetched docs
• ❌ Assume requirements haven't changed
• ❌ Just show example code without creating files
• ❌ Create incomplete structures
• ❌ Skip creating ZIP files
• ❌ Forget the marketplace.json in standalone marketplace
• ❌ Use placeholder content without customizing
• ❌ Provide only directory links (users can't download directories!)
• ❌ Forget to mention Windows path limitations
• ❌ Skip GitHub-first recommendations

Platform-Specific Notes for Users

Windows Users:

• ⚠️ Local plugin installation may not work due to path resolution issues
• ✅ GitHub marketplace installation works reliably
• ✅ Always use the marketplace method for best results

Git Bash/MinGW Users (Windows):

• ⚠️ Path conversion may affect plugin installation paths
• ✅ Detect shell with: echo $MSYSTEM (MINGW64/MINGW32 indicates Git Bash)
• ✅ Use cygpath for path conversion if needed: cygpath -w "/c/path" → C:\path
• ✅ GitHub marketplace method bypasses local path issues
• 💡 Shell detection: Check $MSYSTEM environment variable (MINGW64, MINGW32, MSYS)

Mac/Linux Users:

• ✅ Both local and GitHub installation methods work
• 💡 GitHub method still recommended for easy updates and sharing

Ready-to-Upload GitHub Structure (in ZIP)

When creating marketplace ZIP, ensure it contains this structure:

plugin-name-marketplace/
├── .claude-plugin/
│   └── marketplace.json          # Marketplace manifest
├── plugins/
│   └── plugin-name/              # The actual plugin
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── commands/
│       ├── agents/
│       └── README.md
└── README.md                     # Marketplace README

Users can extract this ZIP and upload directly to GitHub!

What is Claude Code?

/plugin marketplace add YOUR_USERNAME/YOUR_REPO
/plugin install commit-helper@YOUR_USERNAME

/commit-smart

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "keywords": ["helpful", "search", "terms"],
  "license": "MIT"
}

your-repo/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   └── your-plugin/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── ...
└── README.md

/plugin marketplace add YOUR_USERNAME/REPO_NAME

{
  "name": "my-marketplace",
  "description": "My collection of Claude Code plugins",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description",
      "version": "1.0.0",
      "keywords": ["keyword1", "keyword2"]
    }
  ]
}

unzip my-plugin.zip -d ~/.local/share/claude/plugins/

/help          # See your commands
/agents        # See your agents

/plugin marketplace update marketplace-name
/plugin update plugin-name

mkdir -p ~/.local/share/claude/plugins
unzip my-plugin.zip -d ~/.local/share/claude/plugins/

claude --reload-plugins

/plugin list

/help                    # See your commands
/agents                  # See your agents
/your-command           # Test a command

/plugin marketplace add YOUR_USERNAME/YOUR_TEST_REPO

/plugin install my-plugin@YOUR_USERNAME
/help

claude --debug

my-plugin/
└── .claude-plugin/
    └── plugin.json       # ← This file is REQUIRED

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does"
}

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

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "Complete [domain] expertise system. PROACTIVELY activate for: (1) [use cases]. Provides: [capabilities].",
      "version": "1.0.0",
      "author": {
        "name": "Author Name"
      },
      "keywords": ["domain", "primary", "secondary", "technical"]
    }
  ]
}

# Marketplace management
/plugin marketplace add username/repo
/plugin marketplace list
/plugin marketplace update marketplace-name
/plugin marketplace remove marketplace-name

# Plugin management
/plugin install plugin-name@marketplace-name
/plugin list
/plugin uninstall plugin-name

# Testing
/help                      # See your commands
/agents                    # See your agents
claude --debug             # Debug mode

# RECOMMENDED: GitHub marketplace
/plugin marketplace add YOUR_USERNAME/YOUR_REPO
/plugin install plugin-name@YOUR_USERNAME

# Option 1: GitHub marketplace (recommended)
/plugin marketplace add YOUR_USERNAME/YOUR_REPO
/plugin install plugin-name@YOUR_USERNAME

# Option 2: Local installation
unzip plugin-name.zip -d ~/.local/share/claude/plugins/