OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add anthropics/claude-plugins-official --skill plugin-structure
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.
npx skills add anthropics/claude-plugins-official --skill plugin-structure
Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.
Key concepts:
.claude-plugin/plugin.json${CLAUDE_PLUGIN_ROOT}Every Claude Code plugin follows this organizational pattern:
Critical rules:
plugin.json manifest MUST be in .claude-plugin/ directory.claude-plugin/The manifest defines plugin metadata and configuration. Located at .claude-plugin/plugin.json:
Name requirements:
code-review-assistant, test-runner, api-docsVersion format: Follow semantic versioning (MAJOR.MINOR.PATCH) Keywords: Use for plugin discovery and categorization
Specify custom paths for components (supplements default directories):
Important: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
Path rules:
./Location: commands/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in commands/ load automatically
Example structure:
File format:
Usage: Commands integrate as native slash commands in Claude Code
Location: agents/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in agents/ load automatically
Example structure:
File format:
Usage: Users can invoke agents manually, or Claude Code selects them automatically based on task context
Location: 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 automatically
Example structure:
SKILL.md format:
Supporting files: Skills can include scripts, references, examples, or assets in subdirectories
Usage: Claude Code autonomously activates skills based on task context matching the description
Location: hooks/hooks.json or inline in plugin.json
Format: JSON configuration defining event handlers
Registration: Hooks register automatically when plugin enables
Example structure:
Configuration format:
Available events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
Usage: Hooks execute automatically in response to Claude Code events
Location: .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
Example format:
Usage: MCP servers integrate seamlessly with Claude Code's tool system
Use ${CLAUDE_PLUGIN_ROOT} environment variable for all intra-plugin path references:
Why it matters: Plugins install in different locations depending on:
Where to use it:
Never use:
/Users/name/plugins/...)./scripts/... in commands)~/plugins/...)In manifest JSON fields (hooks, MCP servers):
In component files (commands, agents, skills):
In executed scripts:
Commands: Use kebab-case .md files
code-review.md → /code-reviewrun-tests.md → /run-testsapi-docs.md → /api-docsAgents: Use kebab-case .md files describing role
test-generator.mdcode-reviewer.mdperformance-analyzer.mdSkills: Use kebab-case directory names
api-testing/database-migrations/error-handling/Scripts: Use descriptive kebab-case names with appropriate extensions
validate-input.shgenerate-report.pyprocess-data.jsDocumentation: Use kebab-case markdown files
api-reference.mdmigration-guide.mdbest-practices.mdConfiguration: Use standard names
hooks.json.mcp.jsonplugin.jsonClaude Code automatically discovers and loads components:
.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 manifestDiscovery timing:
Override behavior: Custom paths in plugin.json supplement (not replace) default directories
Logical grouping: Group related components together
scripts/ for different purposesMinimal manifest: Keep plugin.json lean
Documentation: Include README files
Consistency: Use consistent naming across components
test-runner, name related agent test-runner-agentClarity: Use descriptive names that indicate purpose
api-integration-testing/, code-quality-checker.mdutils/, misc.md, temp.shLength: Balance brevity with clarity
review-pr, run-ci)code-reviewer, test-generator)error-handling, api-design)Single command with no dependencies:
Complete plugin with all component types:
Plugin providing only skills:
Component not loading:
SKILL.md (not README.md or other name)Path resolution errors:
${CLAUDE_PLUGIN_ROOT}./ in manifestecho $CLAUDE_PLUGIN_ROOT in hook scriptsAuto-discovery not working:
.claude-plugin/)Conflicts between plugins:
For detailed examples and advanced patterns, see files in references/ and examples/ directories.
{
"name": "plugin-name"
}{
"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/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command---
name: command-name
description: Command description
---
Command implementation instructions...agents/
├── 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/
├── 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 # 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
}]
}]
}{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}{
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}"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"my-plugin/
├── .claude-plugin/
│ └── plugin.json # Just name field
└── commands/
└── hello.md # Single commandmy-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 utilitiesmy-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
├── skill-one/
│ └── SKILL.md
└── skill-two/
└── SKILL.md