plugin-creator

name

plugin-creator

description

Create, scaffold, test, and distribute Claude Code plugins (.claude-plugin/plugin.json manifest + components). Use when: (1) building a new Claude Code plugin from scratch, (2) adding skills, agents, hooks, MCP servers, or LSP servers to a plugin, (3) migrating .claude/ standalone config into a distributable plugin, (4) validating or debugging an existing plugin, (5) submitting a plugin to a marketplace. Trigger phrases: "create a Claude plugin", "build a plugin", "add a skill to my plugin", "hook into Claude tool use", "package my Claude config as a plugin", "submit plugin to marketplace".

Claude Plugin Creator

Plugin vs. standalone .claude/ config

Situation	Use
Customizing a single project personally	.claude/ (no plugin needed)
Sharing config across multiple projects	Plugin
Distributing to a team or community	Plugin
Publishing to a marketplace	Plugin

Plugins namespace skills: /hello (standalone) → /my-plugin:hello (plugin).

Workflow

1. Scaffold the plugin

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json (minimal):

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin provides",
  "author": { "name": "Your Name" }
}

• name is required — drives skill namespacing (/my-plugin:skill-name)
• version follows MAJOR.MINOR.PATCH semantic versioning
• See references/manifest-schema.md for full schema with all optional fields

2. Add components (mix and match)

Skills

my-plugin/skills/<skill-name>/SKILL.md

---
name: skill-name
description: What it does and when Claude should invoke it.
---
Instructions for Claude when this skill is invoked.
Use $ARGUMENTS to capture user input: /my-plugin:skill-name <args>

Skills support nested resources (scripts/, references/, assets/) the same way standalone skills do.

Agents

my-plugin/agents/<agent-name>.md

---
name: agent-name
description: What this agent specializes in and when to invoke it.
---
Detailed system prompt for the agent.

Agents appear in /agents and can be invoked manually or automatically by Claude.

Hooks

my-plugin/hooks/hooks.json — see references/hooks.md for all event types and hook types.

Quick example (auto-format after file writes):

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

Key rules: event names are case-sensitive (PostToolUse not postToolUse); always use ${CLAUDE_PLUGIN_ROOT} for script paths; scripts must be executable (chmod +x).

MCP servers

.mcp.json at plugin root:

{
  "mcpServers": {
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

LSP servers

.lsp.json at plugin root (or inline in plugin.json under lspServers):

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" }
  }
}

Default settings

settings.json at plugin root:

{ "agent": "my-agent-name" }

3. Test locally

# Load plugin without installing
claude --plugin-dir ./my-plugin

# Inside session:
#   Run a skill:   /my-plugin:skill-name [args]
#   List agents:   /agents
#   Multiple:      claude --plugin-dir ./a --plugin-dir ./b

# Validate manifest
claude plugin validate    # or /plugin validate inside session

# Debug mode (shows load errors, registration)
claude --debug

See references/troubleshooting.md for common errors and fixes.

4. Distribute

Lifecycle CLI:

claude plugin install   <name>[@marketplace] [--scope user|project|local]
claude plugin enable    <name>
claude plugin disable   <name>
claude plugin update    <name>
claude plugin uninstall <name>

Default scope is user (~/.claude/settings.json). Use project to share with team via .claude/settings.json.

Marketplace submission:

• Claude.ai → https://claude.ai/settings/plugins/submit
• Console → https://platform.claude.com/plugins/submit

Before submitting: bump version in plugin.json, add a CHANGELOG.md, include a README.md with install/usage instructions.

5. Migrate from standalone .claude/

mkdir -p my-plugin/.claude-plugin
# Write plugin.json (name / version / description)
cp -r .claude/commands  my-plugin/
cp -r .claude/agents    my-plugin/   # if any
cp -r .claude/skills    my-plugin/   # if any
# Move hooks out of settings.json → hooks/hooks.json (see references/hooks.md)
claude --plugin-dir ./my-plugin      # verify all components work

What changes after migration:

• Skill invocations gain namespace: /hello → /my-plugin:hello
• Hooks move: .claude/settings.json hooks: block → hooks/hooks.json
• Install via /plugin install instead of local file copy

Standard plugin directory layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # manifest (required)
├── commands/               # slash commands (.md files)
├── agents/                 # sub-agent definitions (.md files)
├── skills/                 # agent skills
│   └── <skill-name>/
│       ├── SKILL.md
│       ├── scripts/        # skill-specific scripts
│       └── references/     # skill-specific reference docs
├── hooks/
│   └── hooks.json          # lifecycle hooks
├── .mcp.json               # MCP server config
├── .lsp.json               # LSP server config
├── settings.json           # default settings
└── scripts/                # plugin-wide hook/utility scripts

Reference files

• references/manifest-schema.md — complete plugin.json schema with all fields
• references/hooks.md — all hook events, hook types, and configuration patterns
• references/troubleshooting.md — common errors, error messages, and debug procedures