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

Field	Type	Description
name	string	Plugin identifier (kebab-case recommended)
version	string	Semantic version (e.g., "1.2.0")
description	string	Brief description of the plugin

Optional Fields

Field	Type	Description
author	object	Author information
author.name	string	Author's name (required if author present)
author.email	string	Author's email
author.url	string	Author's website or GitHub profile
homepage	string	Plugin documentation URL
repository	string	Git repository URL
license	string	License identifier (e.g., "MIT", "Apache-2.0")
keywords	array	Searchable keywords
commands	string or array	Custom command locations (directory or file paths)
agents	array	Array of agent file paths (must end with .md)
hooks	string	Custom hook configuration file location
mcpServers	string	Custom MCP server configuration file location

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

Field	Required	Description
name	Yes	Must match plugin.json name
description	Yes	Brief description for marketplace listing
source	Yes	Relative path to plugin directory
category	Yes	One of: productivity, development, security

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

Error	Cause	Fix
Missing required file: .claude-plugin/plugin.json	No manifest	Create .claude-plugin/plugin.json
plugin.json missing required fields	Missing name, version, or description	Add all required fields
'author' must be an object	Author is a string	Use object format with name field
Invalid JSON syntax	Trailing commas, missing quotes	Fix JSON syntax
agents: Invalid input: must end with ".md"	Using directory path for agents	Use array of file paths: ["./agents/name.md"]

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