plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md
Complete reference for plugin.json configuration.
Required path: .claude-plugin/plugin.json
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.
Type: String
Format: kebab-case
Example: "test-automation-suite"
The unique identifier for the plugin. Used for:
Requirements:
Validation:
/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
Examples:
api-tester, code-review, git-workflow-automationAPI Tester, code_review, -git-workflow, test-Type: String
Format: Semantic versioning (MAJOR.MINOR.PATCH)
Example: "2.1.0"
Default: "0.1.0" if not specified
Semantic versioning guidelines:
Pre-release versions:
"1.0.0-alpha.1" - Alpha release"1.0.0-beta.2" - Beta release"1.0.0-rc.1" - Release candidateExamples:
"0.1.0" - Initial development"1.0.0" - First stable release"1.2.3" - Patch update to 1.2"2.0.0" - Major version with breaking changesType: String
Length: 50-200 characters recommended
Example: "Automates code review workflows with style checks and automated feedback"
Brief explanation of plugin purpose and functionality.
Best practices:
Examples:
Type: Object Fields: name (required), email (optional), url (optional)
{
"author": {
"name": "Jane Developer",
"email": "[email protected]",
"url": "https://janedeveloper.com"
}
}
Alternative format (string only):
{
"author": "Jane Developer <[email protected]> (https://janedeveloper.com)"
}
Use cases:
Type: String (URL)
Example: "https://docs.example.com/plugins/my-plugin"
Link to plugin documentation or landing page.
Should point to:
Not for:
repository field)author.url)Type: String (URL) or Object
Example: "https://github.com/user/plugin-name"
Source code repository location.
String format:
{
"repository": "https://github.com/user/plugin-name"
}
Object format (detailed):
{
"repository": {
"type": "git",
"url": "https://github.com/user/plugin-name.git",
"directory": "packages/plugin-name"
}
}
Use cases:
Type: String
Format: SPDX identifier
Example: "MIT"
Software license identifier.
Common licenses:
"MIT" - Permissive, popular choice"Apache-2.0" - Permissive with patent grant"GPL-3.0" - Copyleft"BSD-3-Clause" - Permissive"ISC" - Permissive, similar to MIT"UNLICENSED" - Proprietary, not open sourceFull list: https://spdx.org/licenses/
Multiple licenses:
{
"license": "(MIT OR Apache-2.0)"
}
Type: Array of strings
Example: ["testing", "automation", "ci-cd", "quality-assurance"]
Tags for plugin discovery and categorization.
Best practices:
Categories to consider:
testing, debugging, documentation, deploymenttypescript, python, docker, awsci-cd, code-review, git-workflowweb-development, data-science, devopsType: String or Array of strings
Default: ["./commands"]
Example: "./cli-commands"
Additional directories or files containing command definitions.
Single path:
{
"commands": "./custom-commands"
}
Multiple paths:
{
"commands": [
"./commands",
"./admin-commands",
"./experimental-commands"
]
}
Behavior: Supplements default commands/ directory (does not replace)
Use cases:
Type: String or Array of strings
Default: ["./agents"]
Example: "./specialized-agents"
Additional directories or files containing agent definitions.
Format: Same as commands field
Use cases:
Type: String (path to JSON file) or Object (inline configuration)
Default: "./hooks/hooks.json"
Hook configuration location or inline definition.
File path:
{
"hooks": "./config/hooks.json"
}
Inline configuration:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
"timeout": 30
}
]
}
]
}
}
Use cases:
Type: String (path to JSON file) or Object (inline configuration)
Default: ./.mcp.json
MCP server configuration location or inline definition.
File path:
{
"mcpServers": "./.mcp.json"
}
Inline configuration:
{
"mcpServers": {
"github": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
Use cases:
.mcp.json fileAll paths in component fields must follow these rules:
./: Indicates relative to plugin root../: No parent directory navigationExamples:
"./commands""./src/commands""./configs/hooks.json""/Users/name/plugin/commands""commands" (missing ./)"../shared/commands"".\\commands" (backslash)When Claude Code loads components:
Default directories: Scans standard locations first
./commands/./agents/./skills/./hooks/hooks.json./.mcp.jsonCustom paths: Scans paths specified in manifest
commands fieldagents fieldhooks and mcpServers fieldsMerge behavior: Components from all locations load
Claude Code validates the manifest on plugin load:
Syntax validation:
Field validation:
name field present and valid formatversion follows semantic versioning (if present)./ prefixComponent validation:
Invalid name format:
{
"name": "My Plugin" // ❌ Contains spaces
}
Fix: Use kebab-case
{
"name": "my-plugin" // ✅
}
Absolute path:
{
"commands": "/Users/name/commands" // ❌ Absolute path
}
Fix: Use relative path
{
"commands": "./commands" // ✅
}
Missing ./ prefix:
{
"hooks": "hooks/hooks.json" // ❌ No ./
}
Fix: Add ./ prefix
{
"hooks": "./hooks/hooks.json" // ✅
}
Invalid version:
{
"version": "1.0" // ❌ Not semantic versioning
}
Fix: Use MAJOR.MINOR.PATCH
{
"version": "1.0.0" // ✅
}
Bare minimum for a working plugin:
{
"name": "hello-world"
}
Relies entirely on default directory discovery.
Good metadata for distribution:
{
"name": "code-review-assistant",
"version": "1.0.0",
"description": "Automates code review with style checks and suggestions",
"author": {
"name": "Jane Developer",
"email": "[email protected]"
},
"homepage": "https://docs.example.com/code-review",
"repository": "https://github.com/janedev/code-review-assistant",
"license": "MIT",
"keywords": ["code-review", "automation", "quality", "ci-cd"]
}
Full configuration with all features:
{
"name": "enterprise-devops",
"version": "2.3.1",
"description": "Comprehensive DevOps automation for enterprise CI/CD pipelines",
"author": {
"name": "DevOps Team",
"email": "[email protected]",
"url": "https://company.com/devops"
},
"homepage": "https://docs.company.com/plugins/devops",
"repository": {
"type": "git",
"url": "https://github.com/company/devops-plugin.git"
},
"license": "Apache-2.0",
"keywords": [
"devops",
"ci-cd",
"automation",
"kubernetes",
"docker",
"deployment"
],
"commands": [
"./commands",
"./admin-commands"
],
"agents": "./specialized-agents",
"hooks": "./config/hooks.json",
"mcpServers": "./.mcp.json"
}