create-plugin

Create a Claude Code Plugin

You are creating a new Claude Code plugin. Follow these steps carefully.

Step 1: Gather information

Ask the user what they need if not already clear from their arguments:

1. Plugin name (required) — use kebab-case, no spaces. This becomes the namespace prefix for all skills (e.g., /my-plugin:skill-name)
2. Description — brief explanation of what the plugin does
3. What components to include:
   • Skills (custom instructions Claude follows) — most common
   • Agents (specialized subagents for specific tasks)
   • Hooks (event handlers that run on tool use, prompt submit, etc.)
   • MCP servers (external tool integrations)
   • LSP servers (language server protocol for code intelligence)
4. Author name (optional)

Use $ARGUMENTS as the plugin name if provided. If the user also provided a description after the name, use that too.

Step 2: Create the directory structure

Create the plugin at the current working directory. The structure depends on which components the user wants:

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json          # Only plugin.json goes here!
├── skills/                  # Skills with SKILL.md files
│   └── <skill-name>/
│       └── SKILL.md
├── commands/                # Simple markdown command files (optional)
├── agents/                  # Subagent definitions (optional)
├── hooks/                   # Event handlers (optional)
│   └── hooks.json
├── scripts/                 # Utility scripts (optional)
├── .mcp.json                # MCP server configs (optional)
├── .lsp.json                # LSP server configs (optional)
└── settings.json            # Default settings (optional)

Critical rule: Never put commands/, agents/, skills/, or hooks/ inside .claude-plugin/. Only plugin.json goes there. All other directories go at the plugin root.

Step 3: Create plugin.json manifest

Create .claude-plugin/plugin.json:

{
  "name": "<plugin-name>",
  "description": "<description>",
  "version": "1.0.0",
  "author": {
    "name": "<author>"
  }
}

Optional fields you can add: homepage, repository, license, keywords.

Step 4: Create requested components

Skills (most common)

Each skill is a directory under skills/ containing a SKILL.md file:

skills/
└── my-skill/
    ├── SKILL.md           # Required — main instructions
    ├── references/        # Optional — detailed docs loaded on demand
    ├── scripts/           # Optional — executable helpers
    └── assets/            # Optional — templates, icons, etc.

Write SKILL.md with YAML frontmatter and markdown instructions:

---
name: skill-name
description: What this skill does and when to use it. Be specific about trigger contexts.
---

Instructions for Claude to follow when this skill is invoked.

Key SKILL.md frontmatter fields:

• name — display name (defaults to directory name)
• description — tells Claude when to use the skill (recommended, be slightly "pushy" to ensure triggering)
• argument-hint — shown during autocomplete, e.g. [filename]
• disable-model-invocation — set true to make it manual-only (/name)
• user-invocable — set false to hide from slash menu (background knowledge only)
• allowed-tools — restrict which tools Claude can use (e.g., Read, Grep, Glob)
• context — set to fork to run in an isolated subagent
• agent — which subagent type when context: fork (e.g., Explore, Plan)
• model — override the model for this skill

Available substitutions in skill content:

• $ARGUMENTS — all arguments passed to the skill
• $ARGUMENTS[N] or $N — specific argument by index
• ${CLAUDE_SESSION_ID} — current session ID
• ${CLAUDE_SKILL_DIR} — directory containing the SKILL.md
• !command`` — runs a shell command and injects its output (preprocessing)

Skill writing tips:

• Keep SKILL.md under 500 lines; use reference files for detailed docs
• Explain the "why" behind instructions rather than heavy-handed MUSTs
• Include examples when helpful
• For large reference files (>300 lines), include a table of contents

Agents

Create markdown files in agents/ directory:

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Hooks

Create hooks/hooks.json:

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

Available hook events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, PreCompact, TaskCompleted.

Hook types: command (shell), prompt (LLM evaluation), agent (agentic verifier).

Use ${CLAUDE_PLUGIN_ROOT} for paths to plugin scripts — this resolves correctly regardless of installation location.

MCP Servers

Create .mcp.json at plugin root:

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

LSP Servers

Create .lsp.json at plugin root:

{
  "language-name": {
    "command": "language-server-binary",
    "args": ["serve"],
    "extensionToLanguage": {
      ".ext": "language"
    }
  }
}

Default Settings

Create settings.json at plugin root to activate a custom agent by default:

{
  "agent": "agent-name"
}

Step 5: Tell the user how to test

After creating the plugin, tell them:

# Test the plugin locally
claude --plugin-dir ./<plugin-name>

# Try a skill
/<plugin-name>:skill-name

# Check available skills
/help

# Load multiple plugins
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Step 6: Share distribution guidance

When the plugin is ready to share:

1. Version it — use semantic versioning (MAJOR.MINOR.PATCH) in plugin.json. Bump the version whenever you change the plugin, otherwise cached copies won't update.
2. Add a README.md — document installation and usage
3. Distribute via a marketplace — see Claude Code docs on plugin marketplaces
4. Submit to official marketplace — via claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit

Installation scopes:

• user (default) — available across all projects (~/.claude/settings.json)
• project — shared via version control (.claude/settings.json)
• local — project-specific, gitignored (.claude/settings.local.json)

Converting existing .claude/ configs

If the user wants to convert existing standalone configuration:

1. Create the plugin structure as above
2. Copy commands/, agents/, skills/ from .claude/ to the plugin root
3. Move hooks from .claude/settings.json to hooks/hooks.json
4. Test with claude --plugin-dir
5. After verifying, they can remove the originals from .claude/