--- title: "Plugins reference" description: "> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/plugins-reference source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:32:05.007Z license: CC-BY-4.0 attribution: "Plugins reference — Claudary (https://claudary.paisolsolutions.com/skills/plugins-reference)" --- # Plugins reference > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. ## Overview > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Plugins reference > Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications. Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces). This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools. A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors. ## Plugin components reference ### Skills Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke. **Location**: `skills/` or `commands/` directory in plugin root **File format**: Skills are directories with `SKILL.md`; commands are simple markdown files **Skill structure**: ```text theme={null} skills/ ├── pdf-processor/ │ ├── SKILL.md │ ├── reference.md (optional) │ └── scripts/ (optional) └── code-reviewer/ └── SKILL.md ``` **Integration behavior**: * Skills and commands are automatically discovered when the plugin is installed * Claude can invoke them automatically based on task context * Skills can include supporting files alongside SKILL.md For complete details, see [Skills](/en/skills). ### Agents Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate. **Location**: `agents/` directory in plugin root **File format**: Markdown files describing agent capabilities **Agent structure**: ```markdown theme={null} --- name: agent-name description: What this agent specializes in and when Claude should invoke it model: sonnet effort: medium maxTurns: 20 disallowedTools: Write, Edit --- Detailed system prompt for the agent describing its role, expertise, and behavior. ``` Plugin agents support `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, and `isolation` frontmatter fields. The only valid `isolation` value is `"worktree"`. For security reasons, `hooks`, `mcpServers`, and `permissionMode` are not supported for plugin-shipped agents. **Integration points**: * Agents appear in the `/agents` interface * Claude can invoke agents automatically based on task context * Agents can be invoked manually by users * Plugin agents work alongside built-in Claude agents For complete details, see [Subagents](/en/sub-agents). ### Hooks Plugins can provide event handlers that respond to Claude Code events automatically. **Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json **Format**: JSON configuration with event matchers and actions **Hook configuration**: ```json theme={null} { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh" } ] } ] } } ``` Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks): | Event | When it fires | | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | `SessionStart` | When a session begins or resumes | | `UserPromptSubmit` | When you submit a prompt, before Claude processes it | | `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion | | `PreToolUse` | Before a tool call executes. Can block it | | `PermissionRequest` | When a permission dialog appears | | `PermissionDenied` | When a tool call is denied by the auto mode classifier. Return `{retry: true}` to tell the model it may retry the denied tool call | | `PostToolUse` | After a tool call succeeds | | `PostToolUseFailure` | After a tool call fails | | `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call | | `Notification` | When Claude Code sends a notification | | `SubagentStart` | When a subagent is spawned | | `SubagentStop` | When a subagent finishes | | `TaskCreated` | When a task is being created via `TaskCreate` | | `TaskCompleted` | When a task is being marked as completed | | `Stop` | When Claude finishes responding | | `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored | | `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle | | `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session | | `ConfigChange` | When a configuration file changes during a session | | `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv | | `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch | | `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior | | `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes | | `PreCompact` | Before context compaction | | `PostCompact` | After context compaction completes | | `Elicitation` | When an MCP server requests user input during a tool call | | `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server | | `SessionEnd` | When a session terminates | **Hook types**: * `command`: execute shell commands or scripts * `http`: send the event JSON as a POST request to a URL * `mcp_tool`: call a tool on a configured [MCP server](/en/mcp) * `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context) * `agent`: run an agentic verifier with tools for complex verification tasks ### MCP servers Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services. **Location**: `.mcp.json` in plugin root, or inline in plugin.json **Format**: Standard MCP server configuration **MCP server configuration**: ```json theme={null} { "mcpServers": { "plugin-database": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], "env": { "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data" } }, "plugin-api-client": { "command": "npx", "args": ["@company/mcp-server", "--plugin-mode"], "cwd": "${CLAUDE_PLUGIN_ROOT}" } } } ``` **Integration behavior**: * Plugin MCP servers start automatically when the plugin is enabled * Servers appear as standard MCP tools in Claude's toolkit * Server capabilities integrate seamlessly with Claude's existing tools * Plugin servers can be configured independently of user MCP servers ### LSP servers Looking to use LSP plugins? Install them from the official marketplace: search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace. Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase. LSP integration provides: * **Instant diagnostics**: Claude sees errors and warnings immediately after each edit * **Code navigation**: go to definition, find references, and hover information * **Language awareness**: type information and documentation for code symbols **Location**: `.lsp.json` in plugin root, or inline in `plugin.json` **Format**: JSON configuration mapping language server names to their configurations **`.lsp.json` file format**: ```json theme={null} { "go": { "command": "gopls", "args": ["serve"], "extensionToLanguage": { ".go": "go" } } } ``` **Inline in `plugin.json`**: ```json theme={null} { "name": "my-plugin", "lspServers": { "go": { "command": "gopls", "args": ["serve"], "extensionToLanguage": { ".go": "go" } } } } ``` **Required fields:** | Field | Description | | :-------------------- | :------------------------------------------- | | `command` | The LSP binary to execute (must be in PATH) | | `extensionToLanguage` | Maps file extensions to language identifiers | **Optional fields:** | Field | Description | | :---------------------- | :-------------------------------------------------------- | | `args` | Command-line arguments for the LSP server | | `transport` | Communication transport: `stdio` (default) or `socket` | | `env` | Environment variables to set when starting the server | | `initializationOptions` | Options passed to the server during initialization | | `settings` | Settings passed via `workspace/didChangeConfiguration` | | `workspaceFolder` | Workspace folder path for the server | | `startupTimeout` | Max time to wait for server startup (milliseconds) | | `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) | | `restartOnCrash` | Whether to automatically restart the server if it crashes | | `maxRestarts` | Maximum number of restart attempts before giving up | **You must install the language server binary separately.** LSP plugins configure how Claude Code connects to a language server, but they don't include the server itself. If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary for your language. **Available LSP plugins:** | Plugin | Language server | Install command | | :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- | | `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` | | `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` | | `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) | Install the language server first, then install the plugin from the marketplace. ### Monitors Plugins can declare background monitors that Claude Code starts automatically when the plugin is active. Each monitor runs a shell command for the lifetime of the session and delivers every stdout line to Claude as a notification, so Claude can react to log entries, status changes, or polled events without being asked to start the watch itself. Plugin monitors use the same mechanism as the [Monitor tool](/en/tools-reference#monitor-tool) and share its availability constraints. They run only in interactive CLI sessions, run unsandboxed at the same trust level as [hooks](#hooks), and are skipped on hosts where the Monitor tool is unavailable. Plugin monitors require Claude Code v2.1.105 or later. **Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json` **Format**: JSON array of monitor entries The following `monitors/monitors.json` watches a deployment status endpoint and a local error log: ```json theme={n --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/plugins-reference) · https://claudary.paisolsolutions.com