surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / plugin-structure / references / manifest-reference.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

552 lines · 11.8 KBPreview CodeRaw

1	# Plugin Manifest Reference
2
3	Complete reference for `plugin.json` configuration.
4
5	## File Location
6
7	Required path: `.claude-plugin/plugin.json`
8
9	The 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
21	The 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
49	Semantic 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
71	Brief 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": "jane@example.com",
97	"url": "https://janedeveloper.com"
98	}
99	}
100	```
101
102	Alternative format (string only):
103	```json
104	{
105	"author": "Jane Developer <jane@example.com> (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
120	Link 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
138	Source 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
170	Software 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
194	Tags 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
217	Additional 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
250	Additional 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
264	Hook 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
303	MCP 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
336	All paths in component fields must follow these rules:
337
338	1. Must be relative: No absolute paths
339	2. Must start with `./`: Indicates relative to plugin root
340	3. Cannot use `../`: No parent directory navigation
341	4. 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
354	When Claude Code loads components:
355
356	1. Default directories: Scans standard locations first
357	- `./commands/`
358	- `./agents/`
359	- `./skills/`
360	- `./hooks/hooks.json`
361	- `./.mcp.json`
362
363	2. 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
368	3. 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
377	Claude 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	```
403	Fix: 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	```
416	Fix: 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	```
429	Fix: 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	```
442	Fix: 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
453	Bare minimum for a working plugin:
454
455	```json
456	{
457	"name": "hello-world"
458	}
459	```
460
461	Relies entirely on default directory discovery.
462
463	### Recommended Plugin
464
465	Good 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": "jane@example.com"
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
485	Full 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": "devops@company.com",
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
525	1. Always include version: Track changes and updates
526	2. Write clear descriptions: Help users understand plugin purpose
527	3. Provide contact information: Enable user support
528	4. Link to documentation: Reduce support burden
529	5. Choose appropriate license: Match project goals
530
531	### Paths
532
533	1. Use defaults when possible: Minimize configuration
534	2. Organize logically: Group related components
535	3. Document custom paths: Explain why non-standard layout used
536	4. Test path resolution: Verify on multiple systems
537
538	### Maintenance
539
540	1. Bump version on changes: Follow semantic versioning
541	2. Update keywords: Reflect new functionality
542	3. Keep description current: Match actual capabilities
543	4. Maintain changelog: Track version history
544	5. Update repository links: Keep URLs current
545
546	### Distribution
547
548	1. Complete metadata before publishing: All fields filled
549	2. Test on clean install: Verify plugin works without dev environment
550	3. Validate manifest: Use validation tools
551	4. Include README: Document installation and usage
552	5. Specify license file: Include LICENSE file in plugin root