Plugin Manifest

The manifest is the file .claude-plugin/plugin.json inside a plugin. It names the plugin. It can also point to its parts. The file is optional. Only name is required. For example, { "name": "my-plugin", "version": "1.0.0" } is a valid manifest.

You write it by hand or start from claude plugin init. Run claude plugin validate after you edit it. enabledPlugins enables or disables the plugin as a whole. A manifest can set defaultEnabled for users who set nothing.

Rules

Claude Code strips an unknown top-level key. claude plugin validate warns about it.
An unknown key inside userConfig, channels, lspServers, or monitors is an error. The plugin does not load.
A component path starts with ./. It stays inside the plugin folder. It must exist.

Source: Plugin Manifest Reference and the program (the bundled manifest schema). A marketplace entry can repeat many of these keys. See Marketplaces.

Top-Level Keys

The last column says where the key may appear: the manifest, a marketplace entry, or both.

Key	Status	What It Does	How It Works	Where
`$schema`	Documented: An official docs page names this item.	Gives an editor schema URL.	The loader ignores it.	Manifest
`name`	Documented: An official docs page names this item.	Sets the plugin id and namespace.	Not empty, no spaces, no control or bidirectional characters. Reserved: names that start with `claude-`, `anthropic-`, `anthropics-`, or `cc-plugin-`, and the names `claude`, `anthropic`, `claude-code`, `claude-mods`.	Both
`displayName`	Documented: An official docs page names this item.	Sets the name shown in the UI.	The entry value wins.	Both
`version`	Documented: An official docs page names this item.	Sets the version text.	Must be a string (a number is an error). Any text works. Nothing checks it as semver. The validator only warns when it is missing or empty. Users stay on this version until you change it. The manifest value wins over the entry. `claude plugin validate` warns when they differ.	Both
`description`, `homepage`, `repository`, `license`, `keywords`	Documented: An official docs page names this item.	Listing data.	`homepage` must be a URL.	Both
`author`	Documented: An official docs page names this item.	Names the maker.	An object: `name` (required), `email`, `url`.	Both
`metadata`	Documented: An official docs page names this item.	A free map for your own data.	The program drops a value that is not an object.	Both
`icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`, `termsOfServiceUrl`	Documented: An official docs page names this item.	Directory listing data.	The program also ignores these names without error: `screenshots`, `classification`, `privacy_policy`, `privacyPolicy`, `support`, `bugs`, `terms_of_service`, `docs`.	Manifest only
`defaultEnabled`	Documented: An official docs page names this item.	Sets the start state when the user chose nothing.	Default `true`. The entry value wins. `enabledPlugins` always wins.	Both
`dependencies`	Documented: An official docs page names this item.	Lists plugins that must be enabled too.	Each item is `"name"`, `"name@marketplace"`, or an object. The program also accepts a trailing `@^range`. It strips the range.	Both
`settings`	Documented: An official docs page names this item.	Applies settings while the plugin is enabled.	Only `agent` and `subagentStatusLine` take effect. A `settings.json` in the plugin root wins.	Manifest
`userConfig`	Documented: An official docs page names this item.	Asks the user for values when the plugin is enabled.	See `userConfig` Option Keys.	Manifest
`channels`	Documented: An official docs page names this item.	Declares message channels.	Items have `server`, `displayName`, and `userConfig`. Strict.	Manifest
`types`	Documented: An official docs page names this item.	Points to a `.d.ts` file for a mod.	Must end in `.d.ts` and must not contain `..`.	Manifest
`skills`	Documented: An official docs page names this item.	Adds skill folders.	Adds to `skills/`. The value `"."` means the plugin root.	Manifest
`commands`	Documented: An official docs page names this item.	Lists command files or a map.	Replaces `commands/`. A map entry has `source` or `content` (exactly one), `description`, `argumentHint`, `model`, and `allowedTools`.	Manifest
`agents`	Documented: An official docs page names this item.	Lists agent `.md` files.	Replaces `agents/`. Folders are not allowed.	Manifest
`hooks`	Documented: An official docs page names this item.	Gives hook files or inline hooks.	Merges with `hooks/hooks.json`. A file needs the `"hooks"` wrapper.	Manifest
`mcpServers`	Documented: An official docs page names this item.	Gives MCP server config.	A path, a `.mcpb` or `.dxt` bundle path or URL, an inline map, or an array. A later name replaces an earlier one.	Manifest
`lspServers`	Documented: An official docs page names this item.	Gives language server config.	Fields: `command`, `extensionToLanguage`, `args`, `transport`, `env`, `initializationOptions`, `settings`, `workspaceFolder`, `startupTimeout`, `shutdownTimeout`, `requestTimeout`, `restartOnCrash`, `maxRestarts`, `diagnostics`.	Manifest
`outputStyles`	Documented: An official docs page names this item.	Lists style files or folders.	Replaces `output-styles/`.	Manifest
`workflows`	Documented: An official docs page names this item.	Lists workflow `.js` files or folders.	Replaces `workflows/`.	Manifest
`experimental.themes`	Documented: An official docs page names this item. Experimental: The program or the official docs call this experimental or beta.	Lists theme files or folders.	Replaces `themes/`. A top-level `themes` key still loads. It gives a warning.	Manifest
`experimental.monitors`	Documented: An official docs page names this item. Experimental: The program or the official docs call this experimental or beta.	Declares background watchers.	Items: `name`, `command`, `description`, `when` (`always` or `on-skill-invoke:<skill>`). Interactive sessions only. Since `2.1.310`, they also run on Bedrock, Vertex, and Foundry, and with telemetry or nonessential traffic off (v2.1.310 release).	Manifest
`experimental.evals`	Documented: An official docs page names this item. Experimental: The program or the official docs call this experimental or beta.	Names the eval folder.	Default `evals/`. `claude plugin eval` uses it.	Manifest
`experimental.syntaxHighlighting.hljsLanguages`	Undocumented: Only the program shows this item. It can change without notice. Experimental: The program or the official docs call this experimental or beta.	Adds highlight.js languages.	Up to 16 items. `id` matches `^[a-z][a-z0-9_-]*$` (64 characters at most). `remote` is `npm:<pkg>[@ver]` or `github:<owner>/<repo>@<ref>#<path>.js`. `integrity` is an SRI hash with `sha256-`, `sha384-`, or `sha512-`. Strict.	Manifest
`binaries`	Undocumented: Only the program shows this item. It can change without notice.	Lists files fetched into `bin/` at install.	A map of base name to `{ "sha256": <64 hex> }`. At most 64 entries. Names match `^[a-z0-9](?:[a-z0-9._-]*[a-z0-9_-])?$`. The env var `CLAUDE_CODE_PLUGIN_BINARY_ASSETS` also exists.	Manifest

`userConfig` Option Keys

Each key under userConfig is the name of one option. The name must match ^[A-Za-z_]\w*$. Claude Code passes the value to hooks as the env var CLAUDE_PLUGIN_OPTION_<KEY>. The same option shape works inside channels.

Option	Status	What It Does	How It Works
`type`	Documented: An official docs page names this item.	Sets the value type.	`string`, `number`, `boolean`, `directory`, or `file`.
`title`, `description`	Documented: An official docs page names this item.	Label and help text in the dialog.	Both are required.
`required`, `default`	Documented: An official docs page names this item.	Say whether an empty value is allowed, and what the start value is.	A default is a string, number, boolean, or array of strings.
`multiple`, `sensitive`	Documented: An official docs page names this item.	Allow a list, or mark a secret.	A `sensitive` value goes to secure storage, not to settings.
`min`, `max`	Documented: An official docs page names this item.	Bound a number.	`number` type only.
`options`	Documented: An official docs page names this item.	Gives fixed choices.	`string` type only, not `multiple`, not `sensitive`. Each choice is 1 to 64 characters. Needs Claude Code `2.1.271` or later.

Components and Layout

my-plugin/
- .claude-plugin/
  
  plugin.json
- skills/ one folder per skill, each with SKILL.md
- commands/ command files
- agents/ agent .md files
- hooks/
  
  hooks.json hooks, inside a hooks wrapper
- output-styles/
- workflows/
- themes/
- bin/ programs added to the Bash tool PATH
- .mcp.json MCP servers
- .lsp.json language servers
- monitors/
  
  monitors.json
- settings.json plugin settings

Item	Status	What It Does	How It Works
`skills/`, `commands/`, `agents/`, `output-styles/`, `workflows/`, `themes/`	Documented: An official docs page names this item.	Default places for components.	A manifest key adds to or replaces the folder, as the table above says.
`hooks/hooks.json`	Documented: An official docs page names this item.	Holds the plugin hooks.	Keys: `hooks`, and also `modules` (one path to a hooks module) and `description`. The old `surface` key is gone.
`.mcp.json`, `.lsp.json`, `monitors/monitors.json`, `settings.json`	Documented: An official docs page names this item.	Config files at fixed places.	Claude Code loads these before it reads manifest entries.
`bin/`	Documented: An official docs page names this item.	Puts programs on the `PATH` of the Bash tool.	claude.ai and Cowork do not install a plugin that has a `bin/` folder.
Root `SKILL.md`	Documented: An official docs page names this item.	Makes a single-skill plugin.	The loader uses it only when there is no `skills/` folder and no `skills` key.
Root `CLAUDE.md`	Documented: An official docs page names this item.	The loader does not load it.	`claude plugin validate` warns about it.

Example

.claude-plugin/plugin.json
{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Skills and a hook for our deploy flow.",
  "author": { "name": "Platform Team", "email": "platform@example.com" },
  "defaultEnabled": true,
  "userConfig": {
    "REGION": {
      "type": "string",
      "title": "Region",
      "description": "Region to deploy to.",
      "options": ["eu-west-1", "us-east-1"],
      "default": "eu-west-1"
    },
    "API_TOKEN": {
      "type": "string",
      "title": "API Token",
      "description": "Token for the deploy API.",
      "sensitive": true
    }
  },
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

Hooks of this plugin see CLAUDE_PLUGIN_OPTION_REGION and CLAUDE_PLUGIN_OPTION_API_TOKEN in their env.

How It Works

Plugins for the overview.
Marketplaces for marketplace.json and plugin sources.
Plugin Loading for variables such as ${CLAUDE_PLUGIN_ROOT}.
Hooks, Plugins, and Skills Settings for pluginConfigs and enabledPlugins.

Rules​

Top-Level Keys​

userConfig Option Keys​

Components and Layout​

Example​

How It Works​

Related Pages​