Create Plugin

Create Plugin Skill

Create new Claude Code plugins with proper structure and configuration.

Plugin Directory Structure

plugin-name/
├── .claude-plugin/           # Required: Metadata directory
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Optional: Command definitions
│   ├── command1.md
│   └── command2.md
├── agents/                   # Optional: Agent definitions
│   ├── agent1.md
│   └── agent2.md
├── skills/                   # Optional: Agent Skills
│   ├── skill-name/
│   │   └── SKILL.md
│   └── another-skill/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Optional: Hook configurations
│   ├── hooks.json           # Main hook config
│   └── additional-hooks.json
├── .mcp.json                # Optional: MCP server definitions
├── scripts/                 # Optional: Hook and utility scripts
│   ├── script1.sh
│   └── script2.py
├── LICENSE                  # Optional: License file
├── CHANGELOG.md             # Optional: Version history
└── README.md                # Optional: Documentation

Plugin Manifest (plugin.json)

Required Fields

Optional Fields

CRITICAL: Manifest Format

Commands Configuration

Commands MUST be a string (directory path) or array of strings (file paths):

CORRECT - Directory path:

{
  "commands": "./commands/"
}

CORRECT - Array of file paths:

{
  "commands": ["./commands/lint.md", "./commands/format.md"]
}

CORRECT - Single custom path:

{
  "commands": "./custom/commands/special.md"
}

WRONG - Object format (INVALID):

{
  "commands": {
    "my-command": {
      "description": "...",
      "source": "..."
    }
  }
}

Agents Configuration

Agents MUST be an array of file paths ending with .md:

CORRECT:

{
  "agents": [
    "./agents/my-agent.md",
    "./agents/another-agent.md"
  ]
}

CORRECT - Single agent:

{
  "agents": ["./agents/expert.md"]
}

WRONG - Directory path (INVALID):

{
  "agents": "./agents/"
}

WRONG - Object format (INVALID):

{
  "agents": {
    "agent-name": {
      "description": "...",
      "file": "..."
    }
  }
}

Skills Auto-Discovery

Skills are automatically discovered from the skills/ directory. No manifest entry needed.

Each skill must be in its own folder with a SKILL.md file:

skills/
├── skill-name/
│   └── SKILL.md
└── another-skill/
    └── SKILL.md

Example Manifests

Minimal

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A simple plugin for Claude Code"
}

With Commands and Agents

{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools including linting and review",
  "author": {
    "name": "Developer",
    "email": "dev@example.com"
  },
  "commands": "./commands/",
  "agents": [
    "./agents/code-reviewer.md"
  ]
}

Complete

{
  "name": "enterprise-plugin",
  "version": "1.2.0",
  "description": "Enterprise-grade development plugin",
  "author": {
    "name": "Jane Developer",
    "email": "jane@example.com",
    "url": "https://github.com/janedev"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/janedev/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "security", "compliance"],
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/security-expert.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Creation Process

1. Plan the plugin

   • Define the plugin's purpose
   • List components needed (commands, agents, skills)
   • Choose a descriptive name (kebab-case)

2. Create directory structure

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

3. Create plugin.json

   {
     "name": "plugin-name",
     "version": "1.0.0",
     "description": "Plugin description",
     "author": {
       "name": "Author Name"
     },
     "commands": "./commands/",
     "agents": ["./agents/my-agent.md"]
   }
   

4. Add components

   • Add agents to agents/ with proper frontmatter
   • Add commands to commands/ with proper frontmatter
   • Add skills to skills/skill-name/SKILL.md

5. IMPORTANT: Register in marketplace.json Every new plugin MUST be added to .claude-plugin/marketplace.json

6. Validate the plugin

   ./scripts/validate-all-plugins.sh plugin-name
   

7. Commit the changes Include both the plugin directory AND marketplace.json

Adding to Marketplace (REQUIRED)

Every new plugin must be registered in .claude-plugin/marketplace.json.

Add a new entry to the plugins array:

{
  "plugins": [
    // ... existing plugins ...
    {
      "name": "plugin-name",
      "description": "Brief plugin description",
      "source": "./plugins/plugin-name",
      "category": "development"
    }
  ]
}

Marketplace Entry Fields

Categories

• productivity - Workflow, project management, documentation tools
• development - Code quality, testing, language-specific tools
• security - Security, compliance, privacy tools

Testing Your Plugin

1. Add marketplace: /plugin marketplace add ./path-to-marketplace
2. Install plugin: /plugin install plugin-name@marketplace-name
3. Verify with /help to see commands
4. Test components individually

Common Validation Errors

Best Practices

1. Use semantic versioning for the version field
2. Include descriptive keywords for better discoverability
3. Provide author information for attribution and support
4. Link to repository for open-source contributions
5. Document your plugin with a README.md
6. Track changes with CHANGELOG.md
7. Use clear names that describe the plugin's purpose
8. Keep descriptions concise but informative

Migration Guide

If you have an existing plugin without plugin.json:

cd plugins/your-plugin
mkdir -p .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "your-plugin",
  "version": "1.0.0",
  "description": "Your plugin description",
  "author": {
    "name": "Your Name"
  }
}
EOF