Plugin manifest reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A plugin manifest is the plugin.json file in a plugin’s .claude-plugin/ directory. It carries the plugin’s metadata and the userConfig values that Claude Code prompts the user for.
It also declares any component that you define inline or keep outside its default location . This reference is for plugin creators, and for marketplace owners who put component fields in a marketplace entry. These cases are covered on other pages: Learning to build a plugin : start with Create a plugin What each component does at runtime : see Plugin components Start at the section that matches what you’re looking up: A field: the Fields table gives each field’s type, whether it’s required, its default, and what it accepts.
Path rules covers the ./ prefix and containment for every component path A userConfig option or a channels entry: the User configuration and Channels schemas ${CLAUDE_PLUGIN_ROOT} or another variable a plugin can reference: Environment variables Where each component’s files go: Standard layout A message from claude plugin validate : the troubleshooting page lists each message with its fix and links to the relevant sections on this page Manifest file The manifest is optional.
Without it, Claude Code loads the components it finds in the standard layout . The plugin name then comes from the marketplace entry, or from the directory name when you load the plugin with --plugin-dir . Write a manifest when you want metadata, a component outside its default directory, userConfig , or an inline component definition. Save the manifest at .claude-plugin/plugin.json under the plugin root. Put every other plugin file at the plugin root, not inside .claude-plugin/ .
That includes skills/ , commands/ , and hooks/ . The following example sets most of the keys in the Fields table . It passes validation in a plugin directory that contains each referenced path. { "name" : "deploy-tools" , "displayName" : "Deploy Tools" , "version" : "1.2.0" , "description" : "Deployment commands, a review agent, and a status monitor" , "author" : { "name" : "Example Team" , "email" : "dev@example.com" , "url" : "https://example.com" }, "homepage" : "https://example.com/docs/deploy-tools" , "repository" : "https://github.com/example/deploy-tools" , "license" : "MIT" , "keywords" : [ "deployment" , "ci" ], "defaultEnabled" : true , "dependencies" : [ "secrets-vault" ], "metadata" : { "catalogId" : "cat-123" }, "skills" : [ "./extra-skills/" ], "commands" : { "status" : { "source" : "./commands/status.md" , "description" : "Show the current deployment status" }, "about" : { "content" : "Explain what the deploy-tools plugin provides." , "description" : "Describe this plugin" } }, "agents" : [ "./agents/reviewer.md" ], "hooks" : "./config/extra-hooks.json" , "mcpServers" : { "deploy-api" : { "command" : "node" , "args" : [ "${CLAUDE_PLUGIN_ROOT}/server.js" ] } }, "lspServers" : "./.lsp.json" , "outputStyles" : "./styles/" , "experimental" : { "themes" : "./themes/" , "monitors" : "./config/monitors.json" }, "userConfig" : { "api_token" : { "type" : "string" , "title" : "API token" , "description" : "Token for the deployment API" , "sensitive" : true } } } Unrecognized fields An unrecognized top-level key is stripped, and an unrecognized key inside a userConfig option, channels entry, lspServers config, or monitors entry is rejected: Top-level fields : the field is stripped and the plugin loads. claude plugin validate reports each unrecognized top-level field as a warning Strict objects : userConfig options, channels entries, lspServers configs, and monitors entries are strict.
An unknown key inside one is an error, and the plugin doesn’t load Validate the manifest claude plugin validate is the authoritative check for a manifest. Run it from your shell against the plugin directory: claude plugin validate ./my-plugin The command reports one of these results: Validation passed : the manifest loads Validation passed with warnings : the manifest loads, but the validator found something to fix, such as an unknown top-level field that Claude Code strips, a name that isn’t kebab-case, or a missing version , description , or author .
Pass --strict to turn warnings into failures in CI Validation failed : the manifest has a type mismatch, a path that is missing or escapes the plugin root, or an unknown key inside a userConfig option, channels entry, lspServers config, or monitors entry. Claude Code reports the same problem when it loads the plugin The command also checks each MCP server entry the plugin declares in .mcp.json , in a .json file that mcpServers names, or inline in plugin.json .
These MCP checks require Claude Code v2.1.281 or later and include: Errors : an entry Claude Code would drop when it loads the plugin, a ${user_config.KEY} reference to an option the manifest doesn’t declare, and a remote url that isn’t a valid absolute URL Warnings : an http:// or ws:// URL to a non-loopback host, and a header value that looks like a literal credential Fields The table lists top-level keys in plugin.json . name is the only required key.
Where a field name is a link, the linked section has its full rules. For component keys such as commands and hooks , Component path forms shows each accepted shape with an example, and every path follows the path rules for the ./ prefix, extensions, and containment. Field Type Description $schema String JSON Schema URL for editor autocomplete. Claude Code ignores it at load time name String Plugin identifier, required.
Use kebab-case. Every component is namespaced under it displayName String Name shown in UI in place of name version String Version string. Setting it keeps users on that version until you change it description String Short explanation of what the plugin provides author Object name , which is required, plus optional email and url homepage String Documentation URL. Must parse as a URL, or the plugin fails to load repository String Source repository URL.
Not validated license String SPDX identifier such as MIT or Apache-2.0 keywords Array of strings Discovery tags metadata Object Free-form object for your own data. Claude Code doesn’t read it icon String Icon for the plugin’s listing in Anthropic’s directory. Claude Code doesn’t read it documentationUrl String Documentation link for the plugin’s listing in Anthropic’s directory. Claude Code doesn’t read it supportUrl String Support link for the plugin’s listing in Anthropic’s directory.
Claude Code doesn’t read it privacyPolicyUrl String Privacy policy link for the plugin’s listing in Anthropic’s directory. Claude Code doesn’t read it termsOfServiceUrl String Terms of service link for the plugin’s listing in Anthropic’s directory. Claude Code doesn’t read it defaultEnabled Boolean Whether the plugin starts enabled when the user hasn’t set it. Defaults to true engines Object The Claude Code versions that the plugin works on, as a semver range under the claude-code key, such as "engines": { "claude-code": ">=2.1.400" } .
Requires Claude Code v2.1.323 or later. To keep the plugin working on v2.0.15 through v2.1.75, omit engines . Those versions reject the manifest with an Unrecognized key error when it has the field dependencies Array of strings or objects Plugins that must be enabled for this one to work network Object The hosts your plugin reaches, such as "network": { "hosts": ["api.example.com"] } , in sandbox.network.allowedDomains syntax. claude plugin validate lists them.
The field doesn’t allow or block any host. Requires Claude Code v2.1.328 or later userConfig Object Values Claude Code prompts the user for when the plugin is enabled types Path A .d.ts file that declares the $.state values and $ nouns of a m
The rest of this page is on the live site.