1# Plugin Manifest Reference
2 
3Complete reference for `plugin.json` configuration.
4 
5## File Location
6 
7**Required path**: `.claude-plugin/plugin.json`
8 
9The manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.
10 
11## Complete Field Reference
12 
13### Core Fields
14 
15#### name (required)
16 
17**Type**: String
18**Format**: kebab-case
19**Example**: `"test-automation-suite"`
20 
21The unique identifier for the plugin. Used for:
22- Plugin identification in Claude Code
23- Conflict detection with other plugins
24- Command namespacing (optional)
25 
26**Requirements**:
27- Must be unique across all installed plugins
28- Use only lowercase letters, numbers, and hyphens
29- No spaces or special characters
30- Start with a letter
31- End with a letter or number
32 
33**Validation**:
34```javascript
35/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
36```
37 
38**Examples**:
39- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`
40- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`
41 
42#### version
43 
44**Type**: String
45**Format**: Semantic versioning (MAJOR.MINOR.PATCH)
46**Example**: `"2.1.0"`
47**Default**: `"0.1.0"` if not specified
48 
49Semantic versioning guidelines:
50- **MAJOR**: Incompatible API changes, breaking changes
51- **MINOR**: New functionality, backward-compatible
52- **PATCH**: Bug fixes, backward-compatible
53 
54**Pre-release versions**:
55- `"1.0.0-alpha.1"` - Alpha release
56- `"1.0.0-beta.2"` - Beta release
57- `"1.0.0-rc.1"` - Release candidate
58 
59**Examples**:
60- `"0.1.0"` - Initial development
61- `"1.0.0"` - First stable release
62- `"1.2.3"` - Patch update to 1.2
63- `"2.0.0"` - Major version with breaking changes
64 
65#### description
66 
67**Type**: String
68**Length**: 50-200 characters recommended
69**Example**: `"Automates code review workflows with style checks and automated feedback"`
70 
71Brief explanation of plugin purpose and functionality.
72 
73**Best practices**:
74- Focus on what the plugin does, not how
75- Use active voice
76- Mention key features or benefits
77- Keep under 200 characters for marketplace display
78 
79**Examples**:
80- ✅ "Generates comprehensive test suites from code analysis and coverage reports"
81- ✅ "Integrates with Jira for automatic issue tracking and sprint management"
82- ❌ "A plugin that helps you do testing stuff"
83- ❌ "This is a very long description that goes on and on about every single feature..."
84 
85### Metadata Fields
86 
87#### author
88 
89**Type**: Object
90**Fields**: name (required), email (optional), url (optional)
91 
92```json
93{
94  "author": {
95    "name": "Jane Developer",
96    "email": "[email protected]",
97    "url": "https://janedeveloper.com"
98  }
99}
100```
101 
102**Alternative format** (string only):
103```json
104{
105  "author": "Jane Developer <[email protected]> (https://janedeveloper.com)"
106}
107```
108 
109**Use cases**:
110- Credit and attribution
111- Contact for support or questions
112- Marketplace display
113- Community recognition
114 
115#### homepage
116 
117**Type**: String (URL)
118**Example**: `"https://docs.example.com/plugins/my-plugin"`
119 
120Link to plugin documentation or landing page.
121 
122**Should point to**:
123- Plugin documentation site
124- Project homepage
125- Detailed usage guide
126- Installation instructions
127 
128**Not for**:
129- Source code (use `repository` field)
130- Issue tracker (include in documentation)
131- Personal websites (use `author.url`)
132 
133#### repository
134 
135**Type**: String (URL) or Object
136**Example**: `"https://github.com/user/plugin-name"`
137 
138Source code repository location.
139 
140**String format**:
141```json
142{
143  "repository": "https://github.com/user/plugin-name"
144}
145```
146 
147**Object format** (detailed):
148```json
149{
150  "repository": {
151    "type": "git",
152    "url": "https://github.com/user/plugin-name.git",
153    "directory": "packages/plugin-name"
154  }
155}
156```
157 
158**Use cases**:
159- Source code access
160- Issue reporting
161- Community contributions
162- Transparency and trust
163 
164#### license
165 
166**Type**: String
167**Format**: SPDX identifier
168**Example**: `"MIT"`
169 
170Software license identifier.
171 
172**Common licenses**:
173- `"MIT"` - Permissive, popular choice
174- `"Apache-2.0"` - Permissive with patent grant
175- `"GPL-3.0"` - Copyleft
176- `"BSD-3-Clause"` - Permissive
177- `"ISC"` - Permissive, similar to MIT
178- `"UNLICENSED"` - Proprietary, not open source
179 
180**Full list**: https://spdx.org/licenses/
181 
182**Multiple licenses**:
183```json
184{
185  "license": "(MIT OR Apache-2.0)"
186}
187```
188 
189#### keywords
190 
191**Type**: Array of strings
192**Example**: `["testing", "automation", "ci-cd", "quality-assurance"]`
193 
194Tags for plugin discovery and categorization.
195 
196**Best practices**:
197- Use 5-10 keywords
198- Include functionality categories
199- Add technology names
200- Use common search terms
201- Avoid duplicating plugin name
202 
203**Categories to consider**:
204- Functionality: `testing`, `debugging`, `documentation`, `deployment`
205- Technologies: `typescript`, `python`, `docker`, `aws`
206- Workflows: `ci-cd`, `code-review`, `git-workflow`
207- Domains: `web-development`, `data-science`, `devops`
208 
209### Component Path Fields
210 
211#### commands
212 
213**Type**: String or Array of strings
214**Default**: `["./commands"]`
215**Example**: `"./cli-commands"`
216 
217Additional directories or files containing command definitions.
218 
219**Single path**:
220```json
221{
222  "commands": "./custom-commands"
223}
224```
225 
226**Multiple paths**:
227```json
228{
229  "commands": [
230    "./commands",
231    "./admin-commands",
232    "./experimental-commands"
233  ]
234}
235```
236 
237**Behavior**: Supplements default `commands/` directory (does not replace)
238 
239**Use cases**:
240- Organizing commands by category
241- Separating stable from experimental commands
242- Loading commands from shared locations
243 
244#### agents
245 
246**Type**: String or Array of strings
247**Default**: `["./agents"]`
248**Example**: `"./specialized-agents"`
249 
250Additional directories or files containing agent definitions.
251 
252**Format**: Same as `commands` field
253 
254**Use cases**:
255- Grouping agents by specialization
256- Separating general-purpose from task-specific agents
257- Loading agents from plugin dependencies
258 
259#### hooks
260 
261**Type**: String (path to JSON file) or Object (inline configuration)
262**Default**: `"./hooks/hooks.json"`
263 
264Hook configuration location or inline definition.
265 
266**File path**:
267```json
268{
269  "hooks": "./config/hooks.json"
270}
271```
272 
273**Inline configuration**:
274```json
275{
276  "hooks": {
277    "PreToolUse": [
278      {
279        "matcher": "Write",
280        "hooks": [
281          {
282            "type": "command",
283            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
284            "timeout": 30
285          }
286        ]
287      }
288    ]
289  }
290}
291```
292 
293**Use cases**:
294- Simple plugins: Inline configuration (< 50 lines)
295- Complex plugins: External JSON file
296- Multiple hook sets: Separate files for different contexts
297 
298#### mcpServers
299 
300**Type**: String (path to JSON file) or Object (inline configuration)
301**Default**: `./.mcp.json`
302 
303MCP server configuration location or inline definition.
304 
305**File path**:
306```json
307{
308  "mcpServers": "./.mcp.json"
309}
310```
311 
312**Inline configuration**:
313```json
314{
315  "mcpServers": {
316    "github": {
317      "command": "node",
318      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js"],
319      "env": {
320        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
321      }
322    }
323  }
324}
325```
326 
327**Use cases**:
328- Simple plugins: Single inline server (< 20 lines)
329- Complex plugins: External `.mcp.json` file
330- Multiple servers: Always use external file
331 
332## Path Resolution
333 
334### Relative Path Rules
335 
336All paths in component fields must follow these rules:
337 
3381. **Must be relative**: No absolute paths
3392. **Must start with `./`**: Indicates relative to plugin root
3403. **Cannot use `../`**: No parent directory navigation
3414. **Forward slashes only**: Even on Windows
342 
343**Examples**:
344- ✅ `"./commands"`
345- ✅ `"./src/commands"`
346- ✅ `"./configs/hooks.json"`
347- ❌ `"/Users/name/plugin/commands"`
348- ❌ `"commands"` (missing `./`)
349- ❌ `"../shared/commands"`
350- ❌ `".\\commands"` (backslash)
351 
352### Resolution Order
353 
354When Claude Code loads components:
355 
3561. **Default directories**: Scans standard locations first
357   - `./commands/`
358   - `./agents/`
359   - `./skills/`
360   - `./hooks/hooks.json`
361   - `./.mcp.json`
362 
3632. **Custom paths**: Scans paths specified in manifest
364   - Paths from `commands` field
365   - Paths from `agents` field
366   - Files from `hooks` and `mcpServers` fields
367 
3683. **Merge behavior**: Components from all locations load
369   - No overwriting
370   - All discovered components register
371   - Name conflicts cause errors
372 
373## Validation
374 
375### Manifest Validation
376 
377Claude Code validates the manifest on plugin load:
378 
379**Syntax validation**:
380- Valid JSON format
381- No syntax errors
382- Correct field types
383 
384**Field validation**:
385- `name` field present and valid format
386- `version` follows semantic versioning (if present)
387- Paths are relative with `./` prefix
388- URLs are valid (if present)
389 
390**Component validation**:
391- Referenced paths exist
392- Hook and MCP configurations are valid
393- No circular dependencies
394 
395### Common Validation Errors
396 
397**Invalid name format**:
398```json
399{
400  "name": "My Plugin"  // ❌ Contains spaces
401}
402```
403Fix: Use kebab-case
404```json
405{
406  "name": "my-plugin"  // ✅
407}
408```
409 
410**Absolute path**:
411```json
412{
413  "commands": "/Users/name/commands"  // ❌ Absolute path
414}
415```
416Fix: Use relative path
417```json
418{
419  "commands": "./commands"  // ✅
420}
421```
422 
423**Missing ./ prefix**:
424```json
425{
426  "hooks": "hooks/hooks.json"  // ❌ No ./
427}
428```
429Fix: Add ./ prefix
430```json
431{
432  "hooks": "./hooks/hooks.json"  // ✅
433}
434```
435 
436**Invalid version**:
437```json
438{
439  "version": "1.0"  // ❌ Not semantic versioning
440}
441```
442Fix: Use MAJOR.MINOR.PATCH
443```json
444{
445  "version": "1.0.0"  // ✅
446}
447```
448 
449## Minimal vs. Complete Examples
450 
451### Minimal Plugin
452 
453Bare minimum for a working plugin:
454 
455```json
456{
457  "name": "hello-world"
458}
459```
460 
461Relies entirely on default directory discovery.
462 
463### Recommended Plugin
464 
465Good metadata for distribution:
466 
467```json
468{
469  "name": "code-review-assistant",
470  "version": "1.0.0",
471  "description": "Automates code review with style checks and suggestions",
472  "author": {
473    "name": "Jane Developer",
474    "email": "[email protected]"
475  },
476  "homepage": "https://docs.example.com/code-review",
477  "repository": "https://github.com/janedev/code-review-assistant",
478  "license": "MIT",
479  "keywords": ["code-review", "automation", "quality", "ci-cd"]
480}
481```
482 
483### Complete Plugin
484 
485Full configuration with all features:
486 
487```json
488{
489  "name": "enterprise-devops",
490  "version": "2.3.1",
491  "description": "Comprehensive DevOps automation for enterprise CI/CD pipelines",
492  "author": {
493    "name": "DevOps Team",
494    "email": "[email protected]",
495    "url": "https://company.com/devops"
496  },
497  "homepage": "https://docs.company.com/plugins/devops",
498  "repository": {
499    "type": "git",
500    "url": "https://github.com/company/devops-plugin.git"
501  },
502  "license": "Apache-2.0",
503  "keywords": [
504    "devops",
505    "ci-cd",
506    "automation",
507    "kubernetes",
508    "docker",
509    "deployment"
510  ],
511  "commands": [
512    "./commands",
513    "./admin-commands"
514  ],
515  "agents": "./specialized-agents",
516  "hooks": "./config/hooks.json",
517  "mcpServers": "./.mcp.json"
518}
519```
520 
521## Best Practices
522 
523### Metadata
524 
5251. **Always include version**: Track changes and updates
5262. **Write clear descriptions**: Help users understand plugin purpose
5273. **Provide contact information**: Enable user support
5284. **Link to documentation**: Reduce support burden
5295. **Choose appropriate license**: Match project goals
530 
531### Paths
532 
5331. **Use defaults when possible**: Minimize configuration
5342. **Organize logically**: Group related components
5353. **Document custom paths**: Explain why non-standard layout used
5364. **Test path resolution**: Verify on multiple systems
537 
538### Maintenance
539 
5401. **Bump version on changes**: Follow semantic versioning
5412. **Update keywords**: Reflect new functionality
5423. **Keep description current**: Match actual capabilities
5434. **Maintain changelog**: Track version history
5445. **Update repository links**: Keep URLs current
545 
546### Distribution
547 
5481. **Complete metadata before publishing**: All fields filled
5492. **Test on clean install**: Verify plugin works without dev environment
5503. **Validate manifest**: Use validation tools
5514. **Include README**: Document installation and usage
5525. **Specify license file**: Include LICENSE file in plugin root
553