This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.
.claude-plugin/plugin.json${CLAUDE_PLUGIN_ROOT}plugin-name/
├── .claude-plugin/
│ └── plugin.json # Required: Plugin manifest
├── commands/ # Slash commands (.md files)
├── agents/ # Subagent definitions (.md files)
├── skills/ # Agent skills (subdirectories)
│ └── skill-name/
│ └── SKILL.md # Required for each skill
├── hooks/
│ └── hooks.json # Event handler configuration
├── .mcp.json # MCP server definitions
└── scripts/ # Helper scripts and utilities
plugin.json manifest MUST be in .claude-plugin/ directory.claude-plugin/.claude-plugin/plugin.json:{
"name": "plugin-name"
}
code-review-assistant, test-runner, api-docs{
"name": "plugin-name",
"version": "1.0.0",
"description": "Brief explanation of plugin purpose",
"author": {
"name": "Author Name",
"email": "author@example.com",
"url": "https://example.com"
},
"homepage": "https://docs.example.com",
"repository": "https://github.com/user/plugin-name",
"license": "MIT",
"keywords": ["testing", "automation", "ci-cd"]
}
{
"name": "plugin-name",
"commands": "./custom-commands",
"agents": ["./agents", "./specialized-agents"],
"hooks": "./config/hooks.json",
"mcpServers": "./.mcp.json"
}
./commands/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in commands/ load automaticallycommands/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command
---
name: command-name
description: Command description
---
Command implementation instructions...
agents/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in agents/ load automaticallyagents/
├── code-reviewer.md
├── test-generator.md
└── refactorer.md
---
description: Agent role and expertise
capabilities:
- Specific task 1
- Specific task 2
---
Detailed agent instructions and knowledge...
skills/ directory with subdirectories per skill
Format: Each skill in its own directory with SKILL.md file
Auto-discovery: All SKILL.md files in skill subdirectories load automaticallyskills/
├── api-testing/
│ ├── SKILL.md
│ ├── scripts/
│ │ └── test-runner.py
│ └── references/
│ └── api-spec.md
└── database-migrations/
├── SKILL.md
└── examples/
└── migration-template.sql
---
name: Skill Name
description: When to use this skill
version: 1.0.0
---
Skill instructions and guidance...
hooks/hooks.json or inline in plugin.json
Format: JSON configuration defining event handlers
Registration: Hooks register automatically when plugin enableshooks/
├── hooks.json # Hook configuration
└── scripts/
├── validate.sh # Hook script
└── check-style.sh # Hook script
{
"PreToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
"timeout": 30
}]
}]
}
.mcp.json at plugin root or inline in plugin.json
Format: JSON configuration for MCP server definitions
Auto-start: Servers start automatically when plugin enables{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
${CLAUDE_PLUGIN_ROOT} environment variable for all intra-plugin path references:{
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}
/Users/name/plugins/...)./scripts/... in commands)~/plugins/...)"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"
Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py
#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
.md filescode-review.md → /code-reviewrun-tests.md → /run-testsapi-docs.md → /api-docs.md files describing roletest-generator.mdcode-reviewer.mdperformance-analyzer.mdapi-testing/database-migrations/error-handling/validate-input.shgenerate-report.pyprocess-data.jsapi-reference.mdmigration-guide.mdbest-practices.mdhooks.json.mcp.jsonplugin.json.claude-plugin/plugin.json when plugin enablescommands/ directory for .md filesagents/ directory for .md filesskills/ for subdirectories containing SKILL.mdhooks/hooks.json or manifest.mcp.json or manifestplugin.json supplement (not replace) default directoriesscripts/ for different purposesplugin.json leantest-runner, name related agent test-runner-agentapi-integration-testing/, code-quality-checker.mdutils/, misc.md, temp.shreview-pr, run-ci)code-reviewer, test-generator)error-handling, api-design)my-plugin/
├── .claude-plugin/
│ └── plugin.json # Just name field
└── commands/
└── hello.md # Single command
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/ # User-facing commands
├── agents/ # Specialized subagents
├── skills/ # Auto-activating skills
├── hooks/ # Event handlers
│ ├── hooks.json
│ └── scripts/
├── .mcp.json # External integrations
└── scripts/ # Shared utilities
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
├── skill-one/
│ └── SKILL.md
└── skill-two/
└── SKILL.md
SKILL.md (not README.md or other name)${CLAUDE_PLUGIN_ROOT}./ in manifestecho $CLAUDE_PLUGIN_ROOT in hook scripts.claude-plugin/)references/ and examples/ directories.