create-plugin

Create a new Claude Code plugin with proper directory structure and manifest. Use when the user wants to create a new plugin from scratch. Sets up plugin.json, directory structure, and optional components.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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

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

Create directory structure

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

Create plugin.json

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

Add components
- Add agents to agents/ with proper frontmatter
- Add commands to commands/ with proper frontmatter
- Add skills to skills/skill-name/SKILL.md
IMPORTANT: Register in marketplace.json Every new plugin MUST be added to .claude-plugin/marketplace.json

Validate the plugin

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

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`

Testing Your Plugin

Add marketplace: /plugin marketplace add ./path-to-marketplace
Install plugin: /plugin install plugin-name@marketplace-name
Verify with /help to see commands
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

Use semantic versioning for the version field
Include descriptive keywords for better discoverability
Provide author information for attribution and support
Link to repository for open-source contributions
Document your plugin with a README.md
Track changes with CHANGELOG.md
Use clear names that describe the plugin's purpose
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

Repository: jpoutrin/product-forge
Path: plugins/claude-code-dev/skills/create-plugin/SKILL.md
Commit: 0ebe7ae

Last updated: 1 month ago
First committed: 9 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.