Plugins Reference

Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications. Source: /Users/parhumm/Projects/jaan-to/website/plugins-reference.md Added: 2026-01-29

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

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

Agents

Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically.

Location: agents/ directory in plugin root

File format: Markdown files describing agent capabilities

---
description: What this agent specializes in
capabilities: ["task1", "task2", "task3"]
---

# Agent Name

Detailed description of the agent's role, expertise, and when Claude should invoke it.

## Capabilities
- Specific task the agent excels at
- Another specialized capability

## Context and examples
Provide examples of when this agent should be used.

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

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Available events:

Event	Description
`PreToolUse`	Before Claude uses any tool
`PostToolUse`	After Claude successfully uses any tool
`PostToolUseFailure`	After Claude tool execution fails
`PermissionRequest`	When a permission dialog is shown
`UserPromptSubmit`	When user submits a prompt
`Notification`	When Claude Code sends notifications
`Stop`	When Claude attempts to stop
`SubagentStart`	When a subagent is started
`SubagentStop`	When a subagent attempts to stop
`Setup`	When `--init`, `--init-only`, or `--maintenance` flags are used
`SessionStart`	At the beginning of sessions
`SessionEnd`	At the end of sessions
`PreCompact`	Before conversation history is compacted

Hook types:

command: Execute shell commands or scripts
prompt: Evaluate a prompt with an LLM (uses $ARGUMENTS placeholder)
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

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

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

Plugins can provide Language Server Protocol (LSP) servers to give Claude real-time code intelligence.

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

{
  "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

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 docs

Plugin Installation Scopes

Scope	Settings file	Use case
`user`	`~/.claude/settings.json`	Personal plugins available across all projects (default)
`project`	`.claude/settings.json`	Team plugins shared via version control
`local`	`.claude/settings.local.json`	Project-specific plugins, gitignored
`managed`	`managed-settings.json`	Managed plugins (read-only, update only)

Plugin Manifest Schema

Complete Schema

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

Required Fields

Field	Type	Description	Example
`name`	string	Unique identifier (kebab-case, no spaces)	`"deployment-tools"`

Metadata Fields

Field	Type	Description	Example
`version`	string	Semantic version	`"2.1.0"`
`description`	string	Brief explanation of plugin purpose	`"Deployment automation tools"`
`author`	object	Author information	`{"name": "Dev Team"}`
`homepage`	string	Documentation URL	`"https://docs.example.com"`
`repository`	string	Source code URL	`"https://github.com/user/plugin"`
`license`	string	License identifier	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Discovery tags	`["deployment", "ci-cd"]`

Component Path Fields

Field	Type	Description
`commands`	string\|array	Additional command files/directories
`agents`	string\|array	Additional agent files
`skills`	string\|array	Additional skill directories
`hooks`	string\|object	Hook config path or inline config
`mcpServers`	string\|object	MCP config path or inline config
`outputStyles`	string\|array	Additional output style files/directories
`lspServers`	string\|object	LSP config for code intelligence

Path Behavior Rules

Custom paths supplement default directories - they don't replace them.

If commands/ exists, it's loaded in addition to custom command paths
All paths must be relative to plugin root and start with ./
Commands from custom paths use the same naming and namespacing rules
Multiple paths can be specified as arrays for flexibility

Environment Variables

${CLAUDE_PLUGIN_ROOT}: Contains the absolute path to your plugin directory. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.

Plugin Caching and File Resolution

When you install a plugin, Claude Code copies the plugin files to a cache directory.

For marketplace plugins with relative paths: The path specified in source is copied recursively
For plugins with .claude-plugin/plugin.json: The implicit root directory is copied recursively

Path Traversal Limitations

Plugins cannot reference files outside their copied directory structure. Paths that traverse outside the plugin root (such as ../shared-utils) will not work after installation.

Working with External Dependencies

Option 1: Use symlinks — Create symbolic links within your plugin directory. Symlinks are honored during the copy process.

Option 2: Restructure your marketplace — Set the plugin path to a parent directory that contains all required files.

Plugin Directory Structure

Standard Plugin Layout

enterprise-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Default command location
│   ├── status.md
│   └── logs.md
├── agents/                   # Default agent location
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Agent Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history

File Locations Reference

Component	Default Location	Purpose
Manifest	`.claude-plugin/plugin.json`	Required metadata file
Commands	`commands/`	Skill Markdown files (legacy; use `skills/` for new skills)
Agents	`agents/`	Subagent Markdown files
Skills	`skills/`	Skills with `<name>/SKILL.md` structure
Hooks	`hooks/hooks.json`	Hook configuration
MCP servers	`.mcp.json`	MCP server definitions
LSP servers	`.lsp.json`	Language server configurations

CLI Commands Reference

plugin install

claude plugin install <plugin> [options]

Option	Description	Default
`-s, --scope <scope>`	Installation scope: `user`, `project`, or `local`	`user`

# Install to user scope (default)
claude plugin install formatter@my-marketplace

# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project

# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

claude plugin uninstall <plugin> [options]

Aliases: remove, rm

plugin enable / disable

claude plugin enable <plugin> [options]
claude plugin disable <plugin> [options]

plugin update

claude plugin update <plugin> [options]

Scope options: user, project, local, or managed

Debugging and Development Tools

Debugging Commands

claude --debug

Shows: which plugins are being loaded, errors in manifests, command/agent/hook registration, MCP server initialization.

Common Issues

Issue	Cause	Solution
Plugin not loading	Invalid `plugin.json`	Validate JSON with `claude plugin validate`
Commands not appearing	Wrong directory structure	Ensure `commands/` at root, not in `.claude-plugin/`
Hooks not firing	Script not executable	Run `chmod +x script.sh`
MCP server fails	Missing `${CLAUDE_PLUGIN_ROOT}`	Use variable for all plugin paths
Path errors	Absolute paths used	All paths must be relative, start with `./`
LSP `Executable not found`	Language server not installed	Install the binary

Hook Troubleshooting

Check the script is executable: chmod +x ./scripts/your-script.sh
Verify the shebang line: #!/bin/bash or #!/usr/bin/env bash
Check the path uses ${CLAUDE_PLUGIN_ROOT}
Test the script manually

MCP Server Troubleshooting

Check the command exists and is executable
Verify all paths use ${CLAUDE_PLUGIN_ROOT} variable
Check MCP server logs: claude --debug
Test the server manually outside of Claude Code

Distribution and Versioning Reference

Version Management

Follow semantic versioning: MAJOR.MINOR.PATCH

MAJOR: Breaking changes (incompatible API changes)
MINOR: New features (backward-compatible additions)
PATCH: Bug fixes (backward-compatible fixes)

Best practices:

Start at 1.0.0 for first stable release
Update the version in plugin.json before distributing changes
Document changes in a CHANGELOG.md file
Use pre-release versions like 2.0.0-beta.1 for testing

Sources

Anthropic Claude Code Documentation: Plugins Reference

Plugin Components Reference​

Skills​

Agents​

Hooks​

MCP Servers​

LSP Servers​

Plugin Installation Scopes​

Plugin Manifest Schema​

Complete Schema​

Required Fields​

Metadata Fields​

Component Path Fields​

Path Behavior Rules​

Environment Variables​

Plugin Caching and File Resolution​

Path Traversal Limitations​

Working with External Dependencies​

Plugin Directory Structure​

Standard Plugin Layout​

File Locations Reference​

CLI Commands Reference​

plugin install​

plugin uninstall​

plugin enable / disable​

plugin update​

Debugging and Development Tools​

Debugging Commands​

Common Issues​

Hook Troubleshooting​

MCP Server Troubleshooting​

Distribution and Versioning Reference​

Version Management​

Sources​