Create and manage Claude Code plugins including commands, agents, skills, hooks, and MCP servers. This skill should be used when building new plugins, debugging plugin issues, understanding plugin structure, or working with plugin marketplaces.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/templates/SKILL.md.templateassets/templates/agent.md.templateassets/templates/command.md.templateassets/templates/hooks.json.templateassets/templates/mcp.json.templateassets/templates/plugin.json.templatereferences/components.mdreferences/manifest-schema.mdreferences/marketplace-schema.mdreferences/plugin-structure.mdThis skill provides guidance for creating, structuring, and debugging Claude Code plugins.
This skill should be used when:
A Claude Code plugin is a directory containing:
.claude-plugin/plugin.json (required) - Plugin manifest with metadatacommands/, agents/, skills/, hooks/, .mcp.jsonmy-plugin/
├── .claude-plugin/
│ └── plugin.json # REQUIRED - manifest
├── commands/ # Slash commands (.md files)
├── agents/ # Subagents (.md files)
├── skills/ # Agent skills (dirs with SKILL.md)
├── hooks/
│ └── hooks.json # Hook configurations
├── .mcp.json # MCP server definitions
└── scripts/ # Utility scripts for hooks
Minimal manifest:
{
"name": "my-plugin",
"version": "1.0.0",
"description": "What this plugin does"
}
Full manifest - see references/manifest-schema.md.
Commands - Create commands/name.md:
---
description: Brief description for autocomplete
---
# Command Name
Instructions for the command...
Agents - Create agents/name.md:
---
description: What this agent specializes in
capabilities: ["task1", "task2"]
---
# Agent Name
Agent instructions...
Skills - Create skills/name/SKILL.md:
---
name: skill-name
description: What the skill does
---
# Skill Name
Skill instructions...
Hooks - Create hooks/hooks.json or inline in plugin.json:
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
}]
}]
}
}
MCP Servers - Create .mcp.json or inline in plugin.json:
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["@company/mcp-server"],
"cwd": "${CLAUDE_PLUGIN_ROOT}"
}
}
}
.claude-plugin/ contains ONLY plugin.json - All component directories go at plugin root./${CLAUDE_PLUGIN_ROOT} - For absolute paths in hooks/MCP configschmod +x script.shRun claude --debug to see:
| Issue | Cause | Solution |
|---|---|---|
| Plugin not loading | Invalid plugin.json | Validate JSON syntax |
| Commands not appearing | Wrong directory structure | Ensure commands/ at root, not in .claude-plugin/ |
| Hooks not firing | Script not executable | Run chmod +x script.sh |
| MCP server fails | Missing CLAUDE_PLUGIN_ROOT | Use variable for all plugin paths |
| Path errors | Absolute paths used | All paths must be relative with ./ |
references/plugin-structure.md - Complete directory layout and file locationsreferences/manifest-schema.md - Full plugin.json schema with all fieldsreferences/marketplace-schema.md - Marketplace bundles, categories, and installationreferences/components.md - Detailed specs for commands, agents, skills, hooks, MCPassets/templates/ - Template files for creating new plugins| Approach | Manifest | Use Case |
|---|---|---|
| Standalone | plugin.json | Single focused plugin |
| Marketplace | marketplace.json | Bundle multiple plugins |
Choose ONE - having both may cause conflicts. Categories in marketplaces are metadata only (no visual grouping in UI).