1---
2name: Plugin Structure
3description: 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.
4version: 0.1.0
5---
6 
7# Plugin Structure for Claude Code
8 
9## Overview
10 
11Claude 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.
12 
13**Key concepts:**
14- Conventional directory layout for automatic discovery
15- Manifest-driven configuration in `.claude-plugin/plugin.json`
16- Component-based organization (commands, agents, skills, hooks)
17- Portable path references using `${CLAUDE_PLUGIN_ROOT}`
18- Explicit vs. auto-discovered component loading
19 
20## Directory Structure
21 
22Every Claude Code plugin follows this organizational pattern:
23 
24```
25plugin-name/
26├── .claude-plugin/
27│   └── plugin.json          # Required: Plugin manifest
28├── commands/                 # Slash commands (.md files)
29├── agents/                   # Subagent definitions (.md files)
30├── skills/                   # Agent skills (subdirectories)
31│   └── skill-name/
32│       └── SKILL.md         # Required for each skill
33├── hooks/
34│   └── hooks.json           # Event handler configuration
35├── .mcp.json                # MCP server definitions
36└── scripts/                 # Helper scripts and utilities
37```
38 
39**Critical rules:**
40 
411. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory
422. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`
433. **Optional components**: Only create directories for components the plugin actually uses
444. **Naming convention**: Use kebab-case for all directory and file names
45 
46## Plugin Manifest (plugin.json)
47 
48The manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:
49 
50### Required Fields
51 
52```json
53{
54  "name": "plugin-name"
55}
56```
57 
58**Name requirements:**
59- Use kebab-case format (lowercase with hyphens)
60- Must be unique across installed plugins
61- No spaces or special characters
62- Example: `code-review-assistant`, `test-runner`, `api-docs`
63 
64### Recommended Metadata
65 
66```json
67{
68  "name": "plugin-name",
69  "version": "1.0.0",
70  "description": "Brief explanation of plugin purpose",
71  "author": {
72    "name": "Author Name",
73    "email": "[email protected]",
74    "url": "https://example.com"
75  },
76  "homepage": "https://docs.example.com",
77  "repository": "https://github.com/user/plugin-name",
78  "license": "MIT",
79  "keywords": ["testing", "automation", "ci-cd"]
80}
81```
82 
83**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)
84**Keywords**: Use for plugin discovery and categorization
85 
86### Component Path Configuration
87 
88Specify custom paths for components (supplements default directories):
89 
90```json
91{
92  "name": "plugin-name",
93  "commands": "./custom-commands",
94  "agents": ["./agents", "./specialized-agents"],
95  "hooks": "./config/hooks.json",
96  "mcpServers": "./.mcp.json"
97}
98```
99 
100**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
101 
102**Path rules:**
103- Must be relative to plugin root
104- Must start with `./`
105- Cannot use absolute paths
106- Support arrays for multiple locations
107 
108## Component Organization
109 
110### Commands
111 
112**Location**: `commands/` directory
113**Format**: Markdown files with YAML frontmatter
114**Auto-discovery**: All `.md` files in `commands/` load automatically
115 
116**Example structure**:
117```
118commands/
119├── review.md        # /review command
120├── test.md          # /test command
121└── deploy.md        # /deploy command
122```
123 
124**File format**:
125```markdown
126---
127name: command-name
128description: Command description
129---
130 
131Command implementation instructions...
132```
133 
134**Usage**: Commands integrate as native slash commands in Claude Code
135 
136### Agents
137 
138**Location**: `agents/` directory
139**Format**: Markdown files with YAML frontmatter
140**Auto-discovery**: All `.md` files in `agents/` load automatically
141 
142**Example structure**:
143```
144agents/
145├── code-reviewer.md
146├── test-generator.md
147└── refactorer.md
148```
149 
150**File format**:
151```markdown
152---
153description: Agent role and expertise
154capabilities:
155  - Specific task 1
156  - Specific task 2
157---
158 
159Detailed agent instructions and knowledge...
160```
161 
162**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context
163 
164### Skills
165 
166**Location**: `skills/` directory with subdirectories per skill
167**Format**: Each skill in its own directory with `SKILL.md` file
168**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically
169 
170**Example structure**:
171```
172skills/
173├── api-testing/
174│   ├── SKILL.md
175│   ├── scripts/
176│   │   └── test-runner.py
177│   └── references/
178│       └── api-spec.md
179└── database-migrations/
180    ├── SKILL.md
181    └── examples/
182        └── migration-template.sql
183```
184 
185**SKILL.md format**:
186```markdown
187---
188name: Skill Name
189description: When to use this skill
190version: 1.0.0
191---
192 
193Skill instructions and guidance...
194```
195 
196**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories
197 
198**Usage**: Claude Code autonomously activates skills based on task context matching the description
199 
200### Hooks
201 
202**Location**: `hooks/hooks.json` or inline in `plugin.json`
203**Format**: JSON configuration defining event handlers
204**Registration**: Hooks register automatically when plugin enables
205 
206**Example structure**:
207```
208hooks/
209├── hooks.json           # Hook configuration
210└── scripts/
211    ├── validate.sh      # Hook script
212    └── check-style.sh   # Hook script
213```
214 
215**Configuration format**:
216```json
217{
218  "PreToolUse": [{
219    "matcher": "Write|Edit",
220    "hooks": [{
221      "type": "command",
222      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
223      "timeout": 30
224    }]
225  }]
226}
227```
228 
229**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
230 
231**Usage**: Hooks execute automatically in response to Claude Code events
232 
233### MCP Servers
234 
235**Location**: `.mcp.json` at plugin root or inline in `plugin.json`
236**Format**: JSON configuration for MCP server definitions
237**Auto-start**: Servers start automatically when plugin enables
238 
239**Example format**:
240```json
241{
242  "mcpServers": {
243    "server-name": {
244      "command": "node",
245      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
246      "env": {
247        "API_KEY": "${API_KEY}"
248      }
249    }
250  }
251}
252```
253 
254**Usage**: MCP servers integrate seamlessly with Claude Code's tool system
255 
256## Portable Path References
257 
258### ${CLAUDE_PLUGIN_ROOT}
259 
260Use `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:
261 
262```json
263{
264  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
265}
266```
267 
268**Why it matters**: Plugins install in different locations depending on:
269- User installation method (marketplace, local, npm)
270- Operating system conventions
271- User preferences
272 
273**Where to use it**:
274- Hook command paths
275- MCP server command arguments
276- Script execution references
277- Resource file paths
278 
279**Never use**:
280- Hardcoded absolute paths (`/Users/name/plugins/...`)
281- Relative paths from working directory (`./scripts/...` in commands)
282- Home directory shortcuts (`~/plugins/...`)
283 
284### Path Resolution Rules
285 
286**In manifest JSON fields** (hooks, MCP servers):
287```json
288"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"
289```
290 
291**In component files** (commands, agents, skills):
292```markdown
293Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py
294```
295 
296**In executed scripts**:
297```bash
298#!/bin/bash
299# ${CLAUDE_PLUGIN_ROOT} available as environment variable
300source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
301```
302 
303## File Naming Conventions
304 
305### Component Files
306 
307**Commands**: Use kebab-case `.md` files
308- `code-review.md` → `/code-review`
309- `run-tests.md` → `/run-tests`
310- `api-docs.md` → `/api-docs`
311 
312**Agents**: Use kebab-case `.md` files describing role
313- `test-generator.md`
314- `code-reviewer.md`
315- `performance-analyzer.md`
316 
317**Skills**: Use kebab-case directory names
318- `api-testing/`
319- `database-migrations/`
320- `error-handling/`
321 
322### Supporting Files
323 
324**Scripts**: Use descriptive kebab-case names with appropriate extensions
325- `validate-input.sh`
326- `generate-report.py`
327- `process-data.js`
328 
329**Documentation**: Use kebab-case markdown files
330- `api-reference.md`
331- `migration-guide.md`
332- `best-practices.md`
333 
334**Configuration**: Use standard names
335- `hooks.json`
336- `.mcp.json`
337- `plugin.json`
338 
339## Auto-Discovery Mechanism
340 
341Claude Code automatically discovers and loads components:
342 
3431. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables
3442. **Commands**: Scans `commands/` directory for `.md` files
3453. **Agents**: Scans `agents/` directory for `.md` files
3464. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`
3475. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest
3486. **MCP servers**: Loads configuration from `.mcp.json` or manifest
349 
350**Discovery timing**:
351- Plugin installation: Components register with Claude Code
352- Plugin enable: Components become available for use
353- No restart required: Changes take effect on next Claude Code session
354 
355**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories
356 
357## Best Practices
358 
359### Organization
360 
3611. **Logical grouping**: Group related components together
362   - Put test-related commands, agents, and skills together
363   - Create subdirectories in `scripts/` for different purposes
364 
3652. **Minimal manifest**: Keep `plugin.json` lean
366   - Only specify custom paths when necessary
367   - Rely on auto-discovery for standard layouts
368   - Use inline configuration only for simple cases
369 
3703. **Documentation**: Include README files
371   - Plugin root: Overall purpose and usage
372   - Component directories: Specific guidance
373   - Script directories: Usage and requirements
374 
375### Naming
376 
3771. **Consistency**: Use consistent naming across components
378   - If command is `test-runner`, name related agent `test-runner-agent`
379   - Match skill directory names to their purpose
380 
3812. **Clarity**: Use descriptive names that indicate purpose
382   - Good: `api-integration-testing/`, `code-quality-checker.md`
383   - Avoid: `utils/`, `misc.md`, `temp.sh`
384 
3853. **Length**: Balance brevity with clarity
386   - Commands: 2-3 words (`review-pr`, `run-ci`)
387   - Agents: Describe role clearly (`code-reviewer`, `test-generator`)
388   - Skills: Topic-focused (`error-handling`, `api-design`)
389 
390### Portability
391 
3921. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths
3932. **Test on multiple systems**: Verify on macOS, Linux, Windows
3943. **Document dependencies**: List required tools and versions
3954. **Avoid system-specific features**: Use portable bash/Python constructs
396 
397### Maintenance
398 
3991. **Version consistently**: Update version in plugin.json for releases
4002. **Deprecate gracefully**: Mark old components clearly before removal
4013. **Document breaking changes**: Note changes affecting existing users
4024. **Test thoroughly**: Verify all components work after changes
403 
404## Common Patterns
405 
406### Minimal Plugin
407 
408Single command with no dependencies:
409```
410my-plugin/
411├── .claude-plugin/
412│   └── plugin.json    # Just name field
413└── commands/
414    └── hello.md       # Single command
415```
416 
417### Full-Featured Plugin
418 
419Complete plugin with all component types:
420```
421my-plugin/
422├── .claude-plugin/
423│   └── plugin.json
424├── commands/          # User-facing commands
425├── agents/            # Specialized subagents
426├── skills/            # Auto-activating skills
427├── hooks/             # Event handlers
428│   ├── hooks.json
429│   └── scripts/
430├── .mcp.json          # External integrations
431└── scripts/           # Shared utilities
432```
433 
434### Skill-Focused Plugin
435 
436Plugin providing only skills:
437```
438my-plugin/
439├── .claude-plugin/
440│   └── plugin.json
441└── skills/
442    ├── skill-one/
443    │   └── SKILL.md
444    └── skill-two/
445        └── SKILL.md
446```
447 
448## Troubleshooting
449 
450**Component not loading**:
451- Verify file is in correct directory with correct extension
452- Check YAML frontmatter syntax (commands, agents, skills)
453- Ensure skill has `SKILL.md` (not `README.md` or other name)
454- Confirm plugin is enabled in Claude Code settings
455 
456**Path resolution errors**:
457- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`
458- Verify paths are relative and start with `./` in manifest
459- Check that referenced files exist at specified paths
460- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts
461 
462**Auto-discovery not working**:
463- Confirm directories are at plugin root (not in `.claude-plugin/`)
464- Check file naming follows conventions (kebab-case, correct extensions)
465- Verify custom paths in manifest are correct
466- Restart Claude Code to reload plugin configuration
467 
468**Conflicts between plugins**:
469- Use unique, descriptive component names
470- Namespace commands with plugin name if needed
471- Document potential conflicts in plugin README
472- Consider command prefixes for related functionality
473 
474---
475 
476For detailed examples and advanced patterns, see files in `references/` and `examples/` directories.
477