plugin-json-schema
Skill9 starsChanged 7 months agoMITView on GitHub
Official Claude Code plugin.json schema reference and validation guide. Use when creating or troubleshooting plugin.json manifest files. Covers all fields, auto-discovery behavior, path formats, and common validation errors.
In this repository142 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- readme-style-guideSkill
- releaseSkill
- scaffoldSkill
- wicked-garden-agentic-agentic-patternsSkill
- wicked-garden-agentic-architectSkill
- wicked-garden-agentic-context-engineeringSkill
- wicked-garden-agentic-frameworksSkill
- wicked-garden-agentic-performance-analystSkill
- wicked-garden-agentic-review-methodologySkill
- wicked-garden-agentic-safety-reviewerSkill
- wicked-garden-agenticSkill
- wicked-garden-agentic-trust-and-safetySkill
- wicked-garden-appsSkill
- wicked-garden-archetypeSkill
- wicked-garden-build-guideSkill
- wicked-garden-classifySkill
- wicked-garden-coreSkill
- wicked-garden-data-engineerSkill
- wicked-garden-dataSkill
- wicked-garden-deliberateSkill
- wicked-garden-demoSkill
- wicked-garden-domain-coverageSkill
- wicked-garden-domain-extractorSkill
- wicked-garden-domain-modelerSkill
- wicked-garden-domainSkill
- wicked-garden-draftSkill
- wicked-garden-editor-scaffoldSkill
- wicked-garden-engineering-api-documentarianSkill
- wicked-garden-engineering-architectureSkill
- wicked-garden-engineering-backendSkill
- wicked-garden-engineering-debuggingSkill
- wicked-garden-engineering-docsSkill
- wicked-garden-engineering-frontendSkill
- wicked-garden-engineering-integrationSkill
- wicked-garden-engineering-large-scale-migrationSkill
- wicked-garden-engineering-migration-engineerSkill
- wicked-garden-engineering-patchSkill
- wicked-garden-engineeringSkill
- wicked-garden-engineering-solution-architectSkill
- wicked-garden-engineering-system-designSkill
- wicked-garden-engineering-unit-test-qualitySkill
- wicked-garden-governed-workerSkill
- wicked-garden-groundSkill
- wicked-garden-jam-brainstorm-facilitatorSkill
- wicked-garden-jam-councilSkill
- wicked-garden-jamSkill
- wicked-garden-learnSkill
- wicked-garden-mcp-scaffoldSkill
- wicked-garden-mcpSkill
- wicked-garden-mem-captureSkill
- wicked-garden-mem-ingestSkill
- wicked-garden-memSkill
- wicked-garden-personaSkill
- wicked-garden-platform-auditSkill
- wicked-garden-platform-compliance-officerSkill
- wicked-garden-platform-complianceSkill
- wicked-garden-platform-errorsSkill
- wicked-garden-platform-gate-benchmark-rebaselineSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 102
Key insight: If using standard directories, omit the fields entirely from plugin.json.
- Distinctive: line 106
Use explicit paths only when components are in non-standard locations:
- Very specific: line 193
Fix: Use ./hooks/hooks.json or omit field for auto-discovery
- Very specific: line 197
Fix: Use string ("./commands/") or array (["./cmd.md"]), or omit for auto-discovery
- Very specific: line 204
Check all paths start with ./
- Distinctive: line 205
Remove component fields if using standard directories
- Very specific: line 206
Verify no path traversal (../)
- Distinctive: line 207
Ensure arrays contain only strings (paths)
- Distinctive: line 211
Prefer minimal manifests: - Only specify what's non-standard
- Distinctive: line 212
Use auto-discovery: - Put components in standard directories
- Very specific: line 213
Avoid explicit paths for standard locations: - Don't add "commands": "./commands" if that's the default
- Very specific: line 215
Validate before publishing: - Run claude plugin validate /path/to/plugin
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude Code plugin.json Schema Reference
Complete reference for Claude Code plugin manifest files.
Minimal Valid plugin.json
For plugins using standard directory structures, this is all you need:
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Brief description of the plugin"
}Auto-discovery will automatically load components from standard locations.
Complete Schema
{
"name": "plugin-name",
"version": "1.2.0",
"description": "Brief plugin description",
"author": {
"name": "Author Name",
"email": "author@example.com",
"url": "https://github.com/author"
},
"homepage": "https://docs.example.com/plugin",
"repository": "https://github.com/author/plugin",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"commands": "./custom/commands/",
"agents": "./custom/agents/",
"skills": "./custom/skills/",
"hooks": "./config/hooks.json",
"mcpServers": "./mcp-config.json",
"outputStyles": "./styles/",
"lspServers": "./.lsp.json"
}Field Reference
Required Fields
| Field | Type | Description |
name | string | Unique identifier, kebab-case, max 64 chars |
version | string | Semantic version (x.y.z) |
description | string | Brief explanation of the plugin |
Optional Metadata Fields
| Field | Type | Description |
author | object | {name, email?, url?} |
homepage | string | Documentation URL |
repository | string | Source code URL |
license | string | License identifier (MIT, Apache-2.0, etc.) |
keywords | array | Discovery tags (strings) |
Component Path Fields
| Field | Type | Auto-Discovery Location |
commands | string | array | commands/ |
agents | string | array | agents/ |
skills | string | array | skills/ |
hooks | string | object | hooks/hooks.json |
mcpServers | string | object | .mcp.json |
lspServers | string | object | .lsp.json |
outputStyles | string | array | (none) |
Auto-Discovery
Claude Code automatically loads components from standard directories without needing explicit paths in plugin.json:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Only manifest required here
├── commands/ # Auto-discovered: all .md files
├── agents/ # Auto-discovered: all .md files
├── skills/ # Auto-discovered: subdirs with SKILL.md
├── hooks/
│ └── hooks.json # Auto-discovered
├── .mcp.json # Auto-discovered
└── .lsp.json # Auto-discoveredKey insight: If using standard directories, omit the fields entirely from plugin.json. Explicit paths are only needed for non-standard locations.
When to Use Explicit Paths
Use explicit paths only when components are in non-standard locations:
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Plugin with custom paths",
"commands": "./src/custom-commands/",
"agents": ["./ai/agents/reviewer.md", "./ai/agents/tester.md"],
"hooks": "./config/hooks.json"
}Custom paths supplement (don't replace) auto-discovered components.
Path Format Rules
Correct Path Formats
// Directory path
"commands": "./custom/commands/"
// Single file path
"hooks": "./config/hooks.json"
// Array of paths
"agents": ["./agents/agent1.md", "./agents/agent2.md"]Invalid Path Formats (Will Cause Validation Errors)
// WRONG: Missing leading ./
"commands": "commands/"
// WRONG: Absolute path
"commands": "/Users/me/plugins/commands/"
// WRONG: Path traversal (../)
"commands": "../shared/commands/"
// WRONG: Relative to plugin.json location
"commands": "../commands"Inline Configuration
hooks, mcpServers, and lspServers can be inline objects instead of file paths:
Inline Hooks
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
}
]
}
]
}
}Inline MCP Servers
{
"mcpServers": {
"database": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
}
}Common Validation Errors
"hooks: Invalid input"
- Cause: Using path traversal (
../) or wrong type - Fix: Use
./hooks/hooks.jsonor omit field for auto-discovery
"commands: Invalid input"
- Cause: Wrong path format or invalid type
- Fix: Use string (
"./commands/") or array (["./cmd.md"]), or omit for auto-discovery
"agents: Invalid input"
- Cause: Wrong path format, often using object instead of string/array
- Fix: Use string (
"./agents/") or array (["./agent.md"]), or omit for auto-discovery
General Validation Failures
- Check all paths start with
./ - Remove component fields if using standard directories
- Verify no path traversal (
../) - Ensure arrays contain only strings (paths)
Best Practices
- Prefer minimal manifests - Only specify what's non-standard
- Use auto-discovery - Put components in standard directories
- Avoid explicit paths for standard locations - Don't add
"commands": "./commands"if that's the default - Use
${CLAUDE_PLUGIN_ROOT}- In hook scripts for portable paths - Validate before publishing - Run
claude plugin validate /path/to/plugin
Directory Structure Template
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Minimal manifest
├── README.md # Plugin documentation
├── commands/ # Slash commands (auto-discovered)
│ ├── deploy.md
│ └── status.md
├── agents/ # Agents (auto-discovered)
│ └── reviewer.md
├── skills/ # Skills (auto-discovered)
│ └── analysis/
│ └── SKILL.md
├── hooks/ # Hooks (auto-discovered)
│ ├── hooks.json
│ └── scripts/
│ └── post-edit.py
└── scripts/ # Shared scripts
└── utils.pyDebugging
# Validate plugin structure
claude plugin validate /path/to/plugin
# Debug mode for detailed loading info
claude --debug
# Check what components are loaded
claude /help # Lists available commands from pluginsDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

