Plugins

Plugins are packages that extend Claude Code with new capabilities. A single plugin can bundle any combination of slash commands, skills (typeahead prompts), MCP servers, lifecycle hooks, LSP servers, and output styles. Plugins are installed from marketplaces — curated catalogs hosted on GitHub, npm, or other sources.

Plugin manifest

Every plugin has a plugin.json manifest (located in the .claude-plugin/ directory of the plugin repository). The manifest identifies the plugin and declares what it provides.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Adds code-review commands and a TypeScript language server.",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/you/my-plugin"
  },
  "homepage": "https://github.com/you/my-plugin",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT",
  "keywords": ["code-review", "typescript"],
  "commands": "./commands",
  "skills": "./skills",
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./server/index.js"],
      "type": "stdio"
    }
  },
  "lspServers": {
    "ts-server": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".ts": "typescript",
        ".tsx": "typescriptreact"
      }
    }
  }
}

Manifest fields

Field	Type	Description
`name`	string	Unique kebab-case identifier (no spaces).
`version`	string	Semantic version following semver.org.
`description`	string	User-facing summary shown in `/plugin` UI.
`author`	object	Author name, email, and URL.
`homepage`	string	URL to plugin documentation.
`repository`	string	Source code repository URL.
`license`	string	SPDX license identifier (e.g. `MIT`).
`keywords`	array	Tags for discovery and categorization.
`dependencies`	array	Other plugins that must be enabled for this one to work.
`commands`	string or array or object	Path(s) to command markdown files or a directory.
`skills`	string or array	Path(s) to skill directories containing `SKILL.md`.
`agents`	string or array	Path(s) to agent markdown files.
`mcpServers`	object or string	Inline MCP server configs or path to a `.json` config file.
`lspServers`	object or string	Inline LSP server configs or path to a `.lsp.json` file.
`hooks`	object or string	Lifecycle hooks or path to `hooks.json`.
`outputStyles`	string or array	Path(s) to output style definitions.
`userConfig`	object	User-configurable options prompted at install time.
`settings`	object	Settings values to merge when the plugin is enabled.

Installing a plugin

Open the plugin manager

Run /plugin in your Claude Code session to open the interactive plugin manager. From here you can browse the official marketplace or manage installed plugins.

Install from the marketplace

Use the /plugin install CLI command to install without the interactive UI:

claude plugin install my-plugin@my-marketplace

Or install a plugin by its bare name when it exists in a configured marketplace:

claude plugin install my-plugin

Choose an installation scope

The --scope flag controls where the plugin is recorded:

# Save to ~/.claude/settings.json (default)
claude plugin install my-plugin --scope user

# Save to .claude/settings.json in the current project
claude plugin install my-plugin --scope project

# Save to CLAUDE.local.md scope (not checked in)
claude plugin install my-plugin --scope local

Valid scopes are user, project, and local. The managed scope exists but is reserved for administrator-deployed plugins and cannot be used with the install command.

Installing a plugin adds it to the appropriate settings.json and caches the plugin files under ~/.claude/plugins/. The plugin is active the next time you start a Claude Code session (or after reloading plugins with /reload-plugins).

Managing plugins

Listing installed plugins

/plugin

The interactive UI shows all enabled and disabled plugins organized by marketplace. Builtin plugins appear in a separate section.

Uninstalling a plugin

claude plugin uninstall my-plugin@my-marketplace

Add --scope project or --scope user to target a specific scope. Uninstalling removes the plugin from settings and orphans its cached files for cleanup.

Enabling and disabling

claude plugin enable my-plugin@my-marketplace
claude plugin disable my-plugin@my-marketplace

Disabling a plugin removes it from active use but keeps it installed. Enable it again at any time without re-downloading.

Updating a plugin

claude plugin update my-plugin@my-marketplace --scope user

Valid scopes for the update command are user, project, local, and managed. The command downloads the latest version, calculates a new version hash, copies it to the versioned plugin cache, and updates the installation record. Changes take effect after restarting Claude Code.

Built-in plugins

Claude Code ships with built-in plugins — capabilities that appear in the /plugin UI and can be toggled on or off per user. Built-in plugin IDs follow the format {name}@builtin. Built-in plugins differ from marketplace plugins in that:

They ship with the Claude Code binary and require no download.
They are enabled by default (unless defaultEnabled: false is set).
Availability can be conditional on system capabilities.

Enable or disable a built-in plugin by toggling it in /plugin or with:

claude plugin enable my-builtin@builtin
claude plugin disable my-builtin@builtin

Commands and skills

Commands

Commands are markdown files in the plugin’s commands/ directory (or paths declared in the manifest commands field). Each file becomes a slash command named /<plugin-name>:<filename>. A command file can include frontmatter to set metadata:

---
description: "Run a security scan on the current file"
argument-hint: "[file]"
allowed-tools: Bash
---

Analyze the file $ARGUMENTS for security vulnerabilities...

Supported frontmatter keys include description, argument-hint, allowed-tools, model, effort, when_to_use, and user-invocable.

Skills

Skills are directories in skills/ (or paths declared in skills) that contain a SKILL.md file. Unlike commands, skills surface as typeahead suggestions in the prompt input and load additional context (the skill directory path) into the prompt automatically. A skill directory looks like:

skills/
  my-skill/
    SKILL.md          ← skill definition
    reference.md      ← can be @included
    examples/
      ...

The SKILL.md file uses the same frontmatter format as commands, and Claude Code substitutes ${CLAUDE_SKILL_DIR} with the skill’s directory path at runtime.

Variable substitution

Inside command and skill content, Claude Code substitutes the following variables at runtime:

Variable	Value
`${CLAUDE_PLUGIN_ROOT}`	Absolute path to the plugin’s root directory.
`${CLAUDE_PLUGIN_DATA}`	Path to the plugin’s writable data directory.
`${CLAUDE_SKILL_DIR}`	Absolute path to the current skill’s directory (skills only).
`${CLAUDE_SESSION_ID}`	Current session ID.
`${user_config.KEY}`	Value of a user-configured option named `KEY`.

User-configurable options

Plugins can declare options that are prompted at enable time:

{
  "userConfig": {
    "API_KEY": {
      "type": "string",
      "title": "API Key",
      "description": "Your service API key.",
      "required": true,
      "sensitive": true
    },
    "MAX_RESULTS": {
      "type": "number",
      "title": "Maximum results",
      "description": "Number of results to return per query.",
      "default": 10
    }
  }
}

Non-sensitive values are saved to settings.json under pluginConfigs. Sensitive values are stored in the system keychain (macOS Keychain or a .credentials.json file on other platforms). Values are available in command content as ${user_config.API_KEY} and in MCP/LSP server environment variables as CLAUDE_PLUGIN_OPTION_API_KEY.

Creating a plugin

Create the plugin repository structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json       ← manifest
├── commands/
│   └── review.md         ← /my-plugin:review command
├── skills/
│   └── explain/
│       └── SKILL.md      ← explain skill
└── README.md

Write the manifest

Create .claude-plugin/plugin.json with your plugin’s metadata and component declarations. Use kebab-case for the name field — spaces are not allowed.

Add commands

Create markdown files in commands/. Each file becomes a slash command. Use YAML frontmatter to set the description, argument hints, and allowed tools.

Publish to a marketplace

Create a marketplace.json file that lists your plugin as an entry, then host it in a GitHub repository. Users add your marketplace with /plugin add-marketplace github:owner/repo.

Plugin policy

Organizations can restrict which marketplaces and plugins are available using the blockedMarketplaces and strictKnownMarketplaces settings in their managed configuration. Blocked plugins cannot be installed or enabled, and attempting to do so returns a clear policy error.

Get Started

Core Concepts

Configuration

Guides

Reference

Plugin manifest

Manifest fields

Installing a plugin

Managing plugins

Listing installed plugins

Uninstalling a plugin

Enabling and disabling

Updating a plugin

Built-in plugins

Commands and skills

Commands

Skills

Variable substitution

User-configurable options

Creating a plugin

Plugin policy

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Reference

Documentation Index

​Plugin manifest

​Manifest fields

​Installing a plugin

​Managing plugins

​Listing installed plugins

​Uninstalling a plugin

​Enabling and disabling

​Updating a plugin

​Built-in plugins

​Commands and skills

​Commands

​Skills

​Variable substitution

​User-configurable options

​Creating a plugin

​Plugin policy

Build docs developers (and LLMs) love

Plugin manifest

Manifest fields

Installing a plugin

Managing plugins

Listing installed plugins

Uninstalling a plugin

Enabling and disabling

Updating a plugin

Built-in plugins

Commands and skills

Commands

Skills

Variable substitution

User-configurable options

Creating a plugin

Plugin policy