name: Creating New Plugins description: Follow a structured approach to create new Claude Code plugins and register them in your marketplace. Use when building plugins for commands, skills, hooks, or MCP servers.

Creating New Plugins

Overview

A systematic workflow for creating new Claude Code plugins and adding them to your plugin marketplace. This skill guides you through plugin structure, manifest creation, and marketplace registration.

When to Use

Creating a new plugin from scratch
Building plugins with commands, skills, hooks, or MCP servers
Adding plugins to an existing marketplace
Structuring a plugin following best practices

Process

Step 1: Understand Plugin Requirements

Before creating a plugin, clarify:

Purpose: What does the plugin do? (e.g., browser testing, code review, deployment automation)
Components: What will it include? Commands, skills, hooks, MCP servers, or agents?
Target audience: Who will use this plugin?
Dependencies: What external tools or services does it need?

Ask clarifying questions if the requirements are ambiguous.

Step 2: Create Plugin Directory Structure

Create the plugin directory with the standard structure:

plugin-name/
├── plugin.json          # Plugin manifest
├── .mcp.json           # MCP server config (if using MCP)
├── README.md           # Documentation
├── commands/           # Custom slash commands (optional)
│   └── command-name.md
├── agents/             # Custom agents (optional)
│   └── agent-name.md
├── skills/             # Agent skills (optional)
│   └── skill-name/
│       └── SKILL.md
└── hooks/              # Event handlers (optional)
    └── hooks.json

Only create directories for components you're actually using.

Step 3: Create plugin.json Manifest

Create a plugin.json file at the plugin root with required metadata:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Clear description of what the plugin does",
  "author": "Your Name",
  "license": "MIT",
  "mcpServers": [
    {
      "name": "server-name",
      "config": {
        "command": "command-to-run",
        "args": ["arg1", "arg2"]
      }
    }
  ]
}

Key fields:

name: Lowercase, hyphenated plugin identifier
version: Semantic versioning (1.0.0)
description: One-sentence description of functionality
author: Your name or organization
mcpServers: Array of MCP server configurations (if applicable)

Step 4: Create Supporting Files

Create necessary supporting files based on plugin components:

For MCP servers:

Create .mcp.json with server configuration matching plugin.json

For all plugins:

Create README.md with documentation including:
- Features and capabilities
- Installation instructions
- Usage examples
- Requirements and troubleshooting

Step 5: Register in Marketplace

Add the plugin to your marketplace's marketplace.json:

Open .claude-plugin/marketplace.json
Add a new entry in the plugins array:

{
  "name": "plugin-name",
  "source": "./plugin-name",
  "description": "Clear description of what the plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "homepage": "https://your-repo-url",
  "repository": "https://your-repo-url",
  "keywords": ["keyword1", "keyword2"],
  "category": "category-name",
  "tags": ["tag1", "tag2"]
}

Ensure JSON is valid (valid commas, proper nesting)
Save the file

Step 6: Verify Plugin Structure

Check that:

Plugin directory exists at the path specified in marketplace.json
plugin.json is in the plugin root (not in a subdirectory)
Required directories (commands/, skills/, etc.) are at plugin root, not in .claude-plugin/
All component markdown files are properly formatted
README.md exists with clear documentation
JSON files are valid (use jq to validate if needed)

Step 7: Test the Plugin

To test locally:

Start Claude Code from the marketplace parent directory
Use /plugin marketplace add ./path/to/marketplace
Use /plugin install plugin-name@marketplace-name
Restart Claude Code
Verify with /help to see new commands
Test all plugin functionality

Common Patterns

Creating an MCP Plugin

Set up directory structure with plugin.json and .mcp.json
In plugin.json, add mcpServers array with server details
In .mcp.json, include mcpServers object with configuration
Document required dependencies in README.md
Test that MCP server starts correctly

Creating a Skills Plugin

Create skills/ directory at plugin root
Create subdirectory for each skill: skills/skill-name/
Add SKILL.md file in each skill subdirectory
Update plugin.json to reference skills: "skills": ["skills/"]
Document skill usage in README.md

Creating a Commands Plugin

Create commands/ directory at plugin root
Create markdown files: commands/command-name.md
Format with YAML frontmatter and markdown content
Document commands in README.md
Test commands with /command-name

Critical Points

Directory Structure:

Component directories (commands/, skills/, etc.) go at plugin root
Never place components inside .claude-plugin/
plugin.json must be at plugin root, not nested

Manifest Files:

plugin.json defines the plugin itself
marketplace.json registers the plugin in your marketplace
Both must be valid JSON with proper formatting

Naming Conventions:

Plugin names: lowercase, hyphenated (e.g., browser-testing, code-review)
Directory names: match plugin name or use descriptive names
Commands: lowercase, hyphenated (e.g., /test-browser, /review-pr)

Metadata:

Version follows semantic versioning (MAJOR.MINOR.PATCH)
Description is concise (one sentence)
Keywords and tags aid discoverability
License should be specified (typically MIT)

Troubleshooting

Plugin doesn't appear in marketplace:

Verify entry exists in .claude-plugin/marketplace.json
Check that source path is correct relative to marketplace
Ensure JSON is valid with no syntax errors
Restart Claude Code

Commands not available after installation:

Verify commands/ directory is at plugin root
Check command markdown files have proper frontmatter
Restart Claude Code to load changes
Check /help to see if commands are listed

MCP server fails to start:

Verify .mcp.json has correct command and arguments
Test command runs manually (e.g., npx @playwright/mcp@latest)
Check all dependencies are installed
Review MCP server documentation

Next Steps

After creating a plugin:

Test all functionality thoroughly
Add to your marketplace for team access
Document any team-specific setup requirements
Share marketplace with team members
Iterate based on feedback

creating-new-plugins

SKILL.md