Plugin Master

Plugin Development Guide

Quick Reference

Critical Rules

Directory Structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # MUST be inside .claude-plugin/
├── agents/
│   └── domain-expert.md
├── commands/
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       ├── references/
│       └── examples/
└── README.md

Plugin.json Schema

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Complete [domain] expertise. PROACTIVELY activate for: (1) ...",
  "author": {
    "name": "Author Name",
    "email": "email@example.com"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Validation Rules:

• author MUST be an object { "name": "..." } - NOT a string
• version MUST be a string "1.0.0" - NOT a number
• keywords MUST be an array ["word1", "word2"] - NOT a string
• Do NOT include agents, skills, slashCommands - these are auto-discovered

YAML Frontmatter (REQUIRED)

ALL markdown files in agents/, commands/, skills/ MUST begin with frontmatter:

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

# Content...

Without frontmatter, components will NOT load.

Plugin Design Philosophy (2025)

Agent-First Design

• Primary interface: ONE expert agent named {domain}-expert
• Minimal commands: Only 0-2 for automation workflows
• Why: Users want conversational interaction, not command menus

Naming Standard:

• docker-master → agent named docker-expert
• terraform-master → agent named terraform-expert

Progressive Disclosure for Skills

Skills use three-tier loading: 1. Frontmatter - Loaded at startup for triggering 2. SKILL.md body - Loaded when skill activates 3. references/ - Loaded only when specific detail needed

This enables unbounded capacity without context bloat.

Creating a Plugin

Step 1: Detect Repository Context

Before creating files, check:

# Check if in marketplace repo
if [[ -f .claude-plugin/marketplace.json ]]; then
    PLUGIN_DIR="plugins/PLUGIN_NAME"
else
    PLUGIN_DIR="PLUGIN_NAME"
fi

# Get author from git config
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

Step 2: Create Structure

mkdir -p $PLUGIN_DIR/.claude-plugin
mkdir -p $PLUGIN_DIR/agents
mkdir -p $PLUGIN_DIR/skills/domain-knowledge

Step 3: Create Files

1. plugin.json - Manifest with metadata 2. agents/domain-expert.md - Primary expert agent 3. skills/domain-knowledge/SKILL.md - Core knowledge 4. README.md - Documentation

Step 4 (conditional): Attribution manifest

If the plugin ships any vendored, derived, or licensed third-party content, create NOTICES.md at the plugin root before registering in the marketplace. Treat it as a first-class shipping artifact alongside plugin.json and README.md, not as doc polish. See references/publishing-guide.md ("Licensed / Vendored / Derived Content" checklist) for the structural integrity, license-text-preservation, and cross-reference requirements.

If the plugin contains no third-party content, skip this step.

Step 5: Register in Marketplace

CRITICAL: If .claude-plugin/marketplace.json exists at repo root, you MUST add the plugin:

{
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Same as plugin.json description",
      "version": "1.0.0",
      "author": { "name": "Author" },
      "keywords": ["same", "as", "plugin.json"]
    }
  ]
}

Component Types

Commands

User-initiated slash commands in commands/*.md:

---
description: What this command does
---

# Command Name

Instructions for Claude to execute...

Agents

Autonomous subagents in agents/*.md:

---
name: agent-name
description: |
  Brief role summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.

  # Optional. Include 3-5 <example> blocks ONLY when the agent body
  # exceeds 2,500 words. Lean orchestrators omit them by design.
  # See agent-development "Example-block requirement by agent body size".
model: inherit
color: blue
---

System prompt for agent...

Skills

Dynamic knowledge in skills/skill-name/SKILL.md:

---
name: skill-name
description: When to use this skill...
---

# Skill content with progressive disclosure...

Hooks

Event automation in hooks/hooks.json:

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
    }]
  }]
}

Events: PreToolUse, PostToolUse, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, Stop, SubagentStop

Best Practices

Naming Conventions

• Plugins: kebab-case (e.g., code-review-helper)
• Commands: verb-based (e.g., review-pr, run-tests)
• Agents: role-based (e.g., code-reviewer, test-generator)
• Skills: topic-based (e.g., api-design, error-handling)

Portability

Use ${CLAUDE_PLUGIN_ROOT} for all internal paths:

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"

Never use hardcoded absolute paths.

Platform Notes

• Windows: Use GitHub marketplace installation (local paths may fail)
• Git Bash/MinGW: Detect with $MSYSTEM, use GitHub method
• Mac/Linux: All installation methods work

Troubleshooting

Additional Resources

For detailed information, see:

• `references/manifest-reference.md` - Complete plugin.json fields
• `references/component-patterns.md` - Advanced component patterns
• `references/publishing-guide.md` - Marketplace publishing details
• `examples/minimal-plugin.md` - Simplest working plugin
• `examples/full-plugin.md` - Complete plugin with all features

Full Plugin Example

A complete plugin demonstrating all component types.

Structure

docker-master/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── docker-expert.md
├── commands/
│   └── docker-compose-up.md
├── skills/
│   └── docker-patterns/
│       ├── SKILL.md
│       ├── references/
│       │   └── dockerfile-best-practices.md
│       └── examples/
│           └── multi-stage-build.md
├── hooks/
│   └── hooks.json
├── scripts/
│   └── validate-dockerfile.sh
└── README.md

Files

.claude-plugin/plugin.json

{
  "name": "docker-master",
  "version": "1.0.0",
  "description": "Complete Docker expertise. PROACTIVELY activate for: (1) Dockerfile creation, (2) Docker Compose setup, (3) Container optimization, (4) Multi-stage builds. Provides: best practices, security hardening, performance optimization.",
  "author": {
    "name": "DevOps Team",
    "email": "devops@example.com"
  },
  "homepage": "https://github.com/example/docker-master",
  "repository": "https://github.com/example/docker-master",
  "license": "MIT",
  "keywords": [
    "docker",
    "containers",
    "devops",
    "dockerfile",
    "docker-compose",
    "kubernetes"
  ]
}

agents/docker-expert.md

---
name: docker-expert
description: |
  Use this agent for Docker and container expertise. Trigger for:
  - Dockerfile creation and optimization
  - Docker Compose configuration
  - Container troubleshooting
  - Security hardening

  <example>
  Context: User needs Dockerfile help
  user: "Create a Dockerfile for my Node.js app"
  assistant: "I'll use the docker-expert agent to create an optimized Dockerfile."
  <commentary>Dockerfile creation request, trigger docker-expert.</commentary>
  </example>

  <example>
  Context: User has container issues
  user: "My container keeps crashing on startup"
  assistant: "I'll use the docker-expert agent to diagnose the issue."
  <commentary>Container troubleshooting, trigger docker-expert.</commentary>
  </example>

model: inherit
color: cyan
---

You are a Docker and containerization expert with deep knowledge of:
- Dockerfile best practices
- Multi-stage builds
- Docker Compose orchestration
- Container security
- Performance optimization

## Core Responsibilities

1. Create optimized Dockerfiles following best practices
2. Configure Docker Compose for development and production
3. Troubleshoot container issues
4. Implement security hardening
5. Optimize image sizes and build times

## Process

When helping with Docker tasks:

1. **Analyze Requirements**
   - Understand the application stack
   - Identify dependencies
   - Determine environment needs

2. **Apply Best Practices**
   - Use official base images
   - Implement multi-stage builds
   - Minimize layers
   - Use .dockerignore
   - Run as non-root user

3. **Security Considerations**
   - Scan for vulnerabilities
   - Use minimal base images
   - Don't store secrets in images
   - Set proper permissions

4. **Optimization**
   - Cache dependencies properly
   - Order instructions by change frequency
   - Use COPY instead of ADD
   - Combine RUN commands

## Output Format

Provide:
- Complete, working configuration files
- Explanation of key decisions
- Security considerations
- Performance tips

commands/docker-compose-up.md

````markdown --- description: Start Docker Compose services with proper checks ---

Start Docker Compose services after validating configuration.

Process

1. Check for docker-compose.yml or compose.yaml 2. Validate configuration syntax 3. Check if Docker daemon is running 4. Start services with appropriate flags 5. Show service status

Commands

# Validate compose file
docker compose config --quiet

# Start services
docker compose up -d

# Show status
docker compose ps

Error Handling

• If no compose file: prompt user to create one
• If syntax error: show specific error and line
• If Docker not running: provide start instructions

````

skills/docker-patterns/SKILL.md

````markdown --- name: docker-patterns description: | Docker configuration patterns and best practices. Activate for: (1) Dockerfile optimization (2) Multi-stage builds (3) Docker Compose patterns (4) Container security ---

Docker Patterns

Quick Reference

Multi-Stage Build

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Production stage
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER node
CMD ["node", "server.js"]

Security Hardening

1. Use official, minimal base images 2. Run as non-root user 3. Don't store secrets in images 4. Scan images for vulnerabilities

Additional Resources

See references/dockerfile-best-practices.md for detailed guidance. See examples/multi-stage-build.md for complete examples. ````

hooks/hooks.json

{
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-dockerfile.sh ${TOOL_INPUT_FILE_PATH}",
          "timeout": 5000
        }
      ]
    }
  ]
}

scripts/validate-dockerfile.sh

#!/bin/bash
# Validate Dockerfile if one was written

FILE_PATH="$1"

# Only validate Dockerfiles
if [[ "$FILE_PATH" == *"Dockerfile"* ]]; then
    echo "Validating Dockerfile: $FILE_PATH"

    # Check for common issues
    if grep -q "^ADD " "$FILE_PATH"; then
        echo "Warning: Consider using COPY instead of ADD"
    fi

    if ! grep -q "^USER " "$FILE_PATH"; then
        echo "Warning: No USER instruction - container will run as root"
    fi

    echo "Dockerfile validation complete"
fi

README.md

# Docker Master

Complete Docker expertise for Claude Code.

## Features

- Dockerfile creation and optimization
- Docker Compose configuration
- Multi-stage build patterns
- Security hardening guidance
- Automatic Dockerfile validation

## Installation

/plugin marketplace add example/marketplace /plugin install docker-master@example

## Usage

Just ask about Docker:
- "Create a Dockerfile for my Python app"
- "Set up Docker Compose for my microservices"
- "Optimize my container image size"

## Components

- **docker-expert agent**: Main expertise interface
- **docker-compose-up command**: Start services
- **docker-patterns skill**: Best practices knowledge
- **Dockerfile validation hook**: Auto-validates on write

## License

MIT

Marketplace Registration

If publishing to a marketplace, add to .claude-plugin/marketplace.json:

{
  "name": "docker-master",
  "source": "./plugins/docker-master",
  "description": "Complete Docker expertise. PROACTIVELY activate for: (1) Dockerfile creation, (2) Docker Compose setup, (3) Container optimization, (4) Multi-stage builds. Provides: best practices, security hardening, performance optimization.",
  "version": "1.0.0",
  "author": {
    "name": "DevOps Team"
  },
  "keywords": [
    "docker",
    "containers",
    "devops",
    "dockerfile",
    "docker-compose",
    "kubernetes"
  ]
}

Minimal Plugin Example

The simplest working Claude Code plugin.

Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── agents/
    └── my-expert.md

Files

.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what this plugin does",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT"
}

agents/my-expert.md

---
name: my-expert
description: |
  Use this agent when users need help with [domain]. Examples:

  <example>
  Context: User needs domain help
  user: "Help me with [task]"
  assistant: "I'll use the my-expert agent to help you."
  <commentary>Domain task requested, trigger expert agent.</commentary>
  </example>

model: inherit
color: blue
---

You are an expert in [domain].

## Your Responsibilities
1. Help users with [domain] tasks
2. Provide best practices guidance
3. Troubleshoot issues

## Process
1. Understand the user's request
2. Apply domain knowledge
3. Provide clear, actionable guidance

## Output
Provide clear explanations with working examples.

Installation

Local Testing

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

From Marketplace

If published to a marketplace:

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

Testing

After installation, test by asking:

• "Help me with [domain task]"
• The agent should trigger and provide assistance

Expanding

To add more functionality:

1. Add a command: Create commands/do-task.md 2. Add a skill: Create skills/domain-knowledge/SKILL.md 3. Add hooks: Create hooks/hooks.json

See full-plugin.md for a complete example with all component types.

Component Patterns

Advanced patterns for creating plugin components.

Agent Patterns

Expert Agent Pattern

The standard pattern for domain expertise:

---
name: domain-expert
description: |
  Use this agent when users need [domain] expertise. Trigger for:
  - Creating [domain] solutions
  - Troubleshooting [domain] issues
  - Best practices guidance

  <example>
  Context: User needs domain help
  user: "Help me with [domain task]"
  assistant: "I'll use the domain-expert agent to assist you."
  <commentary>Domain expertise needed, trigger expert agent.</commentary>
  </example>

model: inherit
color: blue
---

You are an expert in [domain] with deep knowledge of...

## Core Responsibilities
1. [Responsibility 1]
2. [Responsibility 2]

## Process
1. Analyze the request
2. Apply domain knowledge
3. Provide solution with explanation

## Output Format
- Clear explanation
- Working code/commands
- Next steps

Validator Agent Pattern

For validation and checking tasks:

---
name: config-validator
description: |
  Use this agent to validate configuration files. Examples:

  <example>
  Context: User wants validation
  user: "Check if my config is correct"
  assistant: "I'll use the config-validator to analyze your configuration."
  <commentary>Validation request, trigger validator agent.</commentary>
  </example>

model: haiku
color: yellow
tools: ["Read", "Glob", "Grep"]
---

You are a configuration validator that checks files for...

## Validation Process
1. Read configuration file
2. Check required fields
3. Validate format
4. Report issues with severity

## Output Format
- Status: PASS/FAIL
- Issues found (if any)
- Recommendations

Generator Agent Pattern

For code/content generation:

---
name: test-generator
description: |
  Use this agent to generate tests. Examples:

  <example>
  Context: User wants tests
  user: "Generate tests for this function"
  assistant: "I'll use the test-generator agent to create comprehensive tests."
  <commentary>Test generation request, trigger generator agent.</commentary>
  </example>

model: sonnet
color: green
---

You are a test generation specialist...

## Generation Process
1. Analyze the code to test
2. Identify test cases (happy path, edge cases, errors)
3. Generate tests following project patterns
4. Include assertions and mocks

## Output
- Complete test file
- Explanation of test coverage
- Suggestions for additional tests

Command Patterns

Simple Action Command

---
description: Run project tests with coverage report
---

Run the test suite and generate a coverage report.

## Process
1. Detect test framework (jest, pytest, etc.)
2. Run tests with coverage flag
3. Parse and display results
4. Highlight failures and low coverage areas

## Expected Output
- Test results summary
- Coverage percentage
- Failed test details

Interactive Command

---
description: Configure deployment settings interactively
argument-hint: "[environment]"
---

Guide user through deployment configuration.

## Process
1. If environment not specified, ask user which environment
2. Load current configuration
3. Present options using AskUserQuestion:
   - Target servers
   - Deployment strategy
   - Notification settings
4. Generate configuration file
5. Validate before saving

## Questions to Ask
- Which environment? (staging/production)
- Deployment strategy? (rolling/blue-green)
- Enable notifications? (yes/no)

Workflow Command

---
description: Create and submit a pull request
allowed-tools: ["Bash", "Read", "Write"]
---

Automate the PR creation workflow.

## Process
1. Check for uncommitted changes
2. Create/switch to feature branch if needed
3. Stage and commit changes
4. Push to remote
5. Create PR with generated description
6. Return PR URL

## Safety Checks
- Confirm branch name with user
- Show diff before committing
- Warn about force pushes

Skill Patterns

Domain Knowledge Skill

---
name: api-design
description: |
  API design best practices and patterns. Activate for:
  (1) REST API design
  (2) GraphQL schema design
  (3) API versioning strategies
  (4) Error handling patterns
---

# API Design Guide

## Quick Reference
[Tables and key points]

## Core Patterns
[Essential information]

## Best Practices
[Guidelines]

## Additional Resources
See `references/` for detailed patterns.

Workflow Skill

---
name: deployment-workflow
description: |
  Production deployment procedures. Activate for:
  (1) Release preparation
  (2) Deployment execution
  (3) Rollback procedures
  (4) Post-deployment verification
---

# Deployment Workflow

## Pre-Deployment Checklist
- [ ] Tests passing
- [ ] Code reviewed
- [ ] Environment ready

## Deployment Steps
1. Tag release
2. Deploy to staging
3. Run smoke tests
4. Deploy to production
5. Monitor metrics

## Rollback Procedure
[Steps for rollback]

Hook Patterns

Validation Hook

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
      "timeout": 10000
    }]
  }]
}

Auto-Format Hook

{
  "PostToolUse": [{
    "matcher": "Write",
    "hooks": [{
      "type": "command",
      "command": "prettier --write ${TOOL_INPUT_FILE_PATH}",
      "timeout": 5000
    }]
  }]
}

Logging Hook

{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "echo \"Session started: $(date)\" >> ${CLAUDE_PLUGIN_ROOT}/logs/sessions.log"
    }]
  }],
  "SessionEnd": [{
    "hooks": [{
      "type": "command",
      "command": "echo \"Session ended: $(date)\" >> ${CLAUDE_PLUGIN_ROOT}/logs/sessions.log"
    }]
  }]
}

MCP Server Patterns

External API Integration

{
  "mcpServers": {
    "stripe-api": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

Local Tool Server

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

Database Integration

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Plugin Manifest Reference

Complete documentation for all plugin.json fields.

Required Fields

name (required)

{
  "name": "my-plugin-name"
}

Rules:

• Kebab-case format (lowercase with hyphens)
• Must be unique across installed plugins
• No spaces or special characters
• 3-50 characters

Valid examples:

• code-review-assistant
• test-runner
• api-docs-generator

Invalid examples:

• My Plugin (spaces, uppercase)
• my_plugin (underscores)
• ab (too short)

Recommended Fields

version

Semantic versioning string:

{
  "version": "1.0.0"
}

Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

CRITICAL: Must be a STRING, not a number:

• ✅ "1.0.0"
• ❌ 1.0 (number)

description

Brief explanation of plugin purpose:

{
  "description": "Complete [domain] expertise. PROACTIVELY activate for: (1) Use case 1, (2) Use case 2. Provides: capability list."
}

Best practices:

• Start with "Complete" or action verb
• Include numbered use cases
• Mention key capabilities
• Keep under 300 characters for display

author

MUST be an object:

{
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://author-website.com"
  }
}

NEVER a string:

// ❌ WRONG - will cause validation errors
{
  "author": "Author Name"
}

Minimal:

{
  "author": {
    "name": "Author Name"
  }
}

homepage

Documentation or landing page URL:

{
  "homepage": "https://docs.example.com/my-plugin"
}

repository

Source code repository URL:

{
  "repository": "https://github.com/user/repo"
}

Note: Must be a STRING URL, not an object.

license

SPDX license identifier:

{
  "license": "MIT"
}

Common values:

• MIT - Permissive
• Apache-2.0 - Permissive with patent clause
• GPL-3.0 - Copyleft
• BSD-3-Clause - Permissive
• UNLICENSED - Proprietary

keywords

Array of discovery keywords:

{
  "keywords": ["testing", "automation", "ci-cd", "quality"]
}

MUST be an array:

• ✅ ["word1", "word2"]
• ❌ "word1, word2" (string)

Best practices:

• Include 5-15 relevant keywords
• Use lowercase
• Include technology names (e.g., docker, kubernetes)
• Include use cases (e.g., testing, deployment)

Optional Configuration Fields

commands

Custom commands directory (supplements default):

{
  "commands": "./custom-commands"
}

Or array for multiple directories:

{
  "commands": ["./commands", "./extra-commands"]
}

Note: Default commands/ still loads automatically.

agents

Custom agents directory:

{
  "agents": "./custom-agents"
}

hooks

Custom hooks configuration file:

{
  "hooks": "./config/hooks.json"
}

mcpServers

MCP server configuration file:

{
  "mcpServers": "./.mcp.json"
}

Or inline configuration:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Complete Example

{
  "name": "deployment-helper",
  "version": "2.1.0",
  "description": "Complete deployment automation system. PROACTIVELY activate for: (1) Production deployments, (2) Rollback operations, (3) Environment configuration. Provides: safe deployments, automated rollbacks, multi-environment support.",
  "author": {
    "name": "DevOps Team",
    "email": "devops@company.com",
    "url": "https://company.com/devops"
  },
  "homepage": "https://docs.company.com/deployment-helper",
  "repository": "https://github.com/company/deployment-helper",
  "license": "MIT",
  "keywords": [
    "deployment",
    "devops",
    "automation",
    "rollback",
    "production",
    "staging",
    "kubernetes",
    "docker"
  ]
}

Validation Checklist

Before publishing, verify:

• [ ] name is kebab-case, unique
• [ ] version is a string like "1.0.0"
• [ ] author is an object with at least name
• [ ] keywords is an array of strings
• [ ] repository is a URL string (if present)
• [ ] No agents, skills, slashCommands fields (auto-discovered)
• [ ] JSON syntax is valid (use validator)

Common Errors

"author must be an object"

// Change from:
"author": "Name"
// To:
"author": { "name": "Name" }

"version must be a string"

// Change from:
"version": 1.0
// To:
"version": "1.0.0"

"keywords must be an array"

// Change from:
"keywords": "word1, word2"
// To:
"keywords": ["word1", "word2"]

Publishing Guide

Complete guide to publishing plugins to GitHub marketplaces.

Marketplace Concepts

What is a Marketplace?

A GitHub repository containing multiple plugins organized in a standard structure. Users add marketplaces and install plugins from them.

Marketplace Structure

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json     # Required: Plugin registry
├── plugins/
│   ├── plugin-one/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── ...
│   └── plugin-two/
│       └── ...
└── README.md

marketplace.json Format

{
  "name": "My Marketplace",
  "owner": {
    "name": "Organization Name",
    "email": "contact@org.com",
    "github": "github-username"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description matching plugin.json",
      "version": "1.0.0",
      "author": {
        "name": "Author Name"
      },
      "keywords": ["keyword1", "keyword2"]
    }
  ]
}

Publishing to Existing Marketplace

Step 1: Fork or Clone

git clone https://github.com/owner/marketplace-repo.git
cd marketplace-repo

Step 2: Create Plugin Directory

mkdir -p plugins/my-plugin/.claude-plugin
mkdir -p plugins/my-plugin/agents

Step 3: Create Plugin Files

Create all necessary plugin files in plugins/my-plugin/:

• .claude-plugin/plugin.json
• agents/my-expert.md
• README.md
• etc.

Step 4: Register in marketplace.json

Add entry to the plugins array in .claude-plugin/marketplace.json:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "Same description as plugin.json",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["relevant", "keywords"]
}

CRITICAL: Descriptions and keywords must match between:

• plugins/my-plugin/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json entry
• plugins/my-plugin/README.md

Step 5: Submit PR

git checkout -b add-my-plugin
git add .
git commit -m "Add my-plugin: Brief description"
git push origin add-my-plugin
# Create PR through GitHub

Creating Your Own Marketplace

Step 1: Create Repository

mkdir my-marketplace
cd my-marketplace
git init

Step 2: Create Marketplace Structure

mkdir -p .claude-plugin
mkdir -p plugins

Step 3: Create marketplace.json

{
  "name": "My Marketplace",
  "owner": {
    "name": "Your Name",
    "email": "your@email.com",
    "github": "your-github-username"
  },
  "plugins": []
}

Step 4: Add Plugins

Create plugins in plugins/ and register each in marketplace.json.

Step 5: Push to GitHub

git add .
git commit -m "Initial marketplace setup"
git remote add origin https://github.com/username/my-marketplace.git
git push -u origin main

Important: Repository must be PUBLIC for users to access.

Installation Commands

Adding a Marketplace

/plugin marketplace add username/marketplace-repo

Installing a Plugin

/plugin install plugin-name@username

Listing Available Plugins

/plugin list --marketplace username/repo

Publishing Checklist

Before publishing, verify:

Plugin Quality

• [ ] plugin.json has all required fields
• [ ] plugin.json author is an object
• [ ] All components have YAML frontmatter
• [ ] Agent has proper <example> blocks
• [ ] README is comprehensive

Marketplace Registration

• [ ] Plugin added to marketplace.json
• [ ] Source path is correct (./plugins/plugin-name)
• [ ] Description matches plugin.json
• [ ] Keywords synchronized
• [ ] Version matches

Testing

• [ ] Test installation from marketplace
• [ ] Verify commands appear in /help
• [ ] Test agent triggering
• [ ] Check on multiple platforms if possible

Documentation

• [ ] Plugin README has installation instructions
• [ ] Usage examples provided
• [ ] Platform-specific notes included

Licensed / Vendored / Derived Content (MANDATORY when applicable)

If the plugin ships ANY third-party content — vendored docs, derived prompts, ported skill text, embedded example code under another license, anything that originated outside this plugin's own authorship — treat the attribution manifest as a first-class shipping artifact, NOT as doc polish.

• [ ] NOTICES.md exists at the plugin root (same level as README.md)
• [ ] Each upstream source has exactly one ## <source-name> heading (no duplicate H2 sections for the same upstream — grep -c "^## " NOTICES.md | sort | uniq -c should show no repeats)
• [ ] Required license text (MIT preamble, Apache NOTICE, CC-BY attribution string, etc.) is preserved verbatim under each section — paraphrasing or truncation is not acceptable
• [ ] Each section names: upstream project, upstream URL, upstream license SPDX identifier, the specific file(s) in this plugin that derive from it, and the nature of the derivation (verbatim, adapted, fragment quoted)
• [ ] README.md contains a cross-reference: a one-liner under "License" or "Attribution" pointing to NOTICES.md
• [ ] plugin.json license field is consistent with what NOTICES.md permits (e.g., if you incorporate AGPL content, "license": "MIT" is wrong)
• [ ] Cross-reference test passes: grep -l "NOTICES" README.md plugin.json returns at least README.md when third-party content is present

Why this is a separate gate from regular docs: license-text preservation and accurate attribution are legal-adjacent obligations, not stylistic choices. A duplicate H2 heading for the same upstream is not a typo — it is an attribution defect that obscures the actual provenance chain.

If the plugin ships zero third-party content, NOTICES.md is not required and these items are N/A.

Common Issues

"Plugin not found"

• Check source path in marketplace.json starts with ./
• Verify directory structure matches path
• Ensure repository is public

"Invalid plugin manifest"

• Check plugin.json syntax
• Verify author is an object
• Ensure version is a string

"Commands not showing"

• Check frontmatter in command files
• Verify files are in commands/ directory
• Restart Claude Code after changes

Version Management

Semantic Versioning

• MAJOR (1.0.0 → 2.0.0): Breaking changes
• MINOR (1.0.0 → 1.1.0): New features
• PATCH (1.0.0 → 1.0.1): Bug fixes

Updating Versions

1. Update version in plugin.json 2. Update version in marketplace.json 3. Update changelog in README 4. Commit and push

Release Process

1. Create release branch 2. Update versions 3. Test thoroughly 4. Merge to main 5. Tag release: git tag v1.0.0 6. Push tags: git push --tags

Best Practices

Naming

• Use descriptive, unique names
• Avoid generic names like helper or utils
• Include domain in name: docker-deploy, api-testing

Documentation

• Include real-world examples
• Document all configuration options
• Provide troubleshooting section

Maintenance

• Respond to issues promptly
• Keep dependencies updated
• Document breaking changes clearly

Security

• Never hardcode secrets
• Use environment variables for sensitive data
• Document required permissions