Plugin Manifest

ValidatorPluginOfficial docsPlugin manifest schema

The plugin.json file lives in the .claude-plugin/ directory and declares the plugin's components.

Fields

Field	Type	Required	Description
$schema	string	no	JSON Schema reference URL
name	string	yes	Plugin name
version	string	no	Version string (semantic versioning is recommended)
description	string	no	Plugin description
author	object	no	Author info (must be an object, not a string)
homepage	string	no	Homepage URL
repository	string	no	Repository URL
license	string	no	License identifier
keywords	string[]	no	Search keywords
commands	string | object | (string | object)[]	no	Flat command paths or a command map; each entry has exactly one of source or content
agents	string | string[]	no	Path(s) to agent Markdown files
skills	string | string[]	no	Path(s) to skill directories
hooks	string | object | (string | object)[]	no	Additional hooks config paths or inline config (see Auto-discovery)
mcpServers	string | object | (string | object)[]	no	Additional MCP config paths or inline config (see Auto-discovery)
outputStyles	string | string[]	no	Path(s) to output style files
lspServers	string | object | (string | object)[]	no	Additional LSP config paths or inline config (see Auto-discovery)
themes	string | string[]	no	Color theme files/directories that appear in /theme alongside built-in presets
monitors	string | object[]	no	Background Monitor configurations that start automatically when the plugin is active
userConfig	object	no	User-configurable values prompted at enable time, keyed by valid identifier names
channels	object[]	no	Channel declarations that bind to MCP servers for message injection (Telegram, Slack, Discord style)
dependencies	(string | object)[]	no	Other plugins this plugin requires, optionally with semver version constraints
displayName	string	no	Human-readable display name
defaultEnabled	boolean	no	Initial enablement when the user has not chosen a state; default true
metadata	object	no	Free-form data for other tooling
workflows	string | string[]	no	Workflow script files or directories
experimental	object	no	Experimental components: themes and evals paths, and a monitors file or inline array
icon	string	no	Plugin directory listing image path
documentationUrl	string	no	HTTPS documentation URL for the directory listing
supportUrl	string	no	HTTPS support URL for the directory listing
privacyPolicyUrl	string	no	HTTPS privacy policy URL for the directory listing
termsOfServiceUrl	string	no	HTTPS terms URL for the directory listing
settings	object	no	Plugin defaults for agent and command-based subagentStatusLine
types	string	no	Path to mod state and noun TypeScript declarations

userConfig options accept type, title, description, required, default, options, multiple, sensitive, min, and max. A fixed options list applies only to a non-sensitive, single string value; labels are 1–64 characters. Supply a listed default or make the selection required. Unknown option keys are rejected.

Command map entries accept source or content, plus description, argumentHint, model, and allowedTools. Inline monitor entries require name, command, and description; optional when is always or on-skill-invoke:<skill>.

Author

The author field must be an object (string format is not supported):

Field	Type	Required	Description
name	string	yes	Author name
email	string	no	Contact email
url	string	no	Author URL

Auto-discovery

Claude Code automatically loads components from default locations in the plugin root. The hooks, mcpServers, and lspServers fields in plugin.json are for additional files beyond these defaults:

• Hooks — hooks/hooks.json (loaded automatically)
• MCP — .mcp.json (loaded automatically)
• LSP — .lsp.json (loaded automatically)

Paths are relative to the plugin root, outside .claude-plugin/. Use additional paths to avoid loading default resources twice. Inline hooks use an event map; hook files use a top-level hooks wrapper. MCP bundle HTTPS URLs and the skills path "." are supported.

Example

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A Claude Code plugin for automated testing",
  "author": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
  "skills": "./skills/",
  "hooks": "./config/extra-hooks.json",
  "mcpServers": "./config/extra-mcp.json"
}