Plugins reference

​

Plugin components reference

​

Skills

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

• 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

---
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.

• Agents appear in the @-mention typeahead under their scoped name, such as my-plugin:code-reviewer, once the plugin is enabled
• 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

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

• 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
• 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

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

• 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

• 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

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Monitors

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

​

Themes

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

​

Plugin installation scopes

​

Skills-directory plugins

​

Choose where the plugin loads from

• MCP servers it declares go through the same per-server approval as a project .mcp.json
• LSP servers start only after you trust the workspace
• Background monitors do not load

​

Edit, reload, and disable a skills-directory plugin

claude plugin disable my-tool@skills-dir

​

Plugin manifest schema

​

Complete schema

{
  "name": "plugin-name",
  "displayName": "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"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Required fields

​

Unrecognized fields

claude plugin validate ./my-plugin --strict

​

Metadata fields

​

Default enablement

• The user’s setting: an entry for the plugin in enabledPlugins at any settings scope. Once written, it persists across plugin updates and reinstalls, so changing defaultEnabled in a later release does not flip an existing user.
• A dependency requirement: when a plugin is required by another one that is active, Claude Code writes true for it at install or enable time. That gives it an explicit setting, so its own default no longer applies. See Enable or disable a plugin with dependencies.

​

Component path fields

​

Experimental components

​

User configuration

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

​

Channels

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

​

Path behavior rules

• Replaces the default: commands, agents, outputStyles, experimental.themes, experimental.monitors. For example, when the manifest specifies commands, the default commands/ directory is not scanned. To keep the default and add more, list it explicitly: "commands": ["./commands/", "./extras/"]
• Adds to the default: skills. The default skills/ directory is always scanned, and directories listed in skills are loaded alongside it. Exception: for a marketplace entry whose source resolves to the marketplace root, declaring specific subdirectories replaces the default skills/ scan
• Own merge rules: hooks, MCP servers, and LSP servers. See each section for how multiple sources combine

• All paths must be relative to the plugin root and start with ./
• Components from custom paths use the same naming and namespacing rules
• Multiple paths can be specified as arrays
• When a skill path points to a directory that contains a SKILL.md directly, for example "skills": ["./"] pointing to the plugin root, the frontmatter name field in SKILL.md determines the skill’s invocation name. This gives a stable name regardless of the install directory. If name is not set in the frontmatter, the directory basename is used as a fallback.

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

​

Environment variables

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

Persistent data directory

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Plugin caching and file resolution

• Through claude --plugin-dir or claude --plugin-url, for the duration of a session.
• Through a marketplace, installed for future sessions.

​

Path traversal limitations

​

Share files within a marketplace with symlinks

• Within the plugin’s own directory: the symlink is preserved as a relative symlink in the cache, so it keeps resolving to the copied target at runtime.
• Elsewhere within the same marketplace: the symlink is dereferenced. The target’s content is copied into the cache in its place. This lets a meta-plugin’s skills/ directory link to skills defined by other plugins in the marketplace.
• Outside the marketplace: the symlink is skipped for security. This prevents plugins from pulling arbitrary host files such as system paths into the cache.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Plugin directory structure

​

Standard plugin layout

enterprise-plugin/
├── .claude-plugin/           # Metadata directory (optional)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills as flat .md files
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Output style definitions
│   └── terse.md
├── themes/                   # Color theme definitions
│   └── dracula.json
├── monitors/                 # Background monitor configurations
│   └── monitors.json
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── bin/                      # Plugin executables added to PATH
│   └── my-tool               # Invokable as bare command in Bash tool
├── settings.json            # Default settings for the plugin
├── .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

​

CLI commands reference

​

plugin init

claude plugin init <name> [options]

• <name>: Plugin name. Becomes the skill namespace and the directory name under ~/.claude/skills/, so it cannot contain spaces or path separators.

# Scaffold a minimal plugin
claude plugin init my-helper

# Scaffold with skill and hook folders
claude plugin init my-helper --with skills hooks

# Overwrite an existing scaffold
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

• <plugin>: Plugin name or plugin-name@marketplace-name for a specific marketplace

# 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]

• <plugin>: Plugin name or plugin-name@marketplace-name

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin>: Plugin name or plugin-name@marketplace-name

​

plugin disable

claude plugin disable [plugin] [options]

• [plugin]: Plugin name or plugin-name@marketplace-name. Optional when using --all

​

plugin update

claude plugin update <plugin> [options]

• <plugin>: Plugin name or plugin-name@marketplace-name

​

plugin list

claude plugin list [options]

• Plugins loaded from skills directories appear in the /plugin interface and in claude plugin list, but not in the inline /plugin list output.
• Plugins loaded for the session with --plugin-dir or --plugin-url appear in the /plugin interface, and in claude plugin list only when the same flag precedes the subcommand, as in claude --plugin-dir <dir> plugin list. They have no installed record, so a bare claude plugin list doesn’t show them.

​

plugin details

claude plugin details <name>

• <name>: Plugin name or plugin-name@marketplace-name

• Always-on: tokens added to every session by the plugin’s listing text, such as skill descriptions, agent descriptions, and command names, regardless of whether any component fires.
• On-invoke: tokens a component costs when it fires. Shown per component, not as a plugin total, because a typical session invokes only a subset of components.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin tag

claude plugin tag [path] [options]

• [path]: Path to the plugin directory. Defaults to the current directory.

​

Debugging and development tools

​

Debugging commands

• Which plugins are being loaded
• Any errors in plugin manifests
• Skill, agent, and hook registration
• MCP server initialization

​

Common issues

​

Example error messages

• Invalid JSON syntax: Unexpected token } in JSON at position 142: check for missing commas, extra commas, or unquoted strings
• Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: a required field is missing
• Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON syntax error

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: command path exists but contains no valid command files
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: the source path in marketplace.json points to a non-existent directory
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: remove duplicate component definitions or remove strict: false in marketplace entry

​

Hook troubleshooting

1. Check the script is executable: chmod +x ./scripts/your-script.sh
2. Verify the shebang line: First line should be #!/bin/bash or #!/usr/bin/env bash
3. Check the path uses ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. Test the script manually: ./scripts/your-script.sh

1. Verify the event name is correct (case-sensitive): PostToolUse, not postToolUse
2. Check the matcher pattern matches your tools: "matcher": "Write|Edit" for file operations
3. Confirm the hook type is valid: command, http, mcp_tool, prompt, or agent

​

MCP server troubleshooting

1. Check the command exists and is executable
2. Verify all paths use ${CLAUDE_PLUGIN_ROOT} variable
3. Check the MCP server logs: claude --debug shows initialization errors
4. Test the server manually outside of Claude Code

1. Ensure the server is properly configured in .mcp.json or plugin.json
2. Verify the server implements the MCP protocol correctly
3. Check for connection timeouts in debug output

​

Directory structure mistakes

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Only manifest here
├── commands/            ← At root level
├── agents/              ← At root level
└── hooks/               ← At root level

1. Run claude --debug and look for “loading plugin” messages
2. Check that each component directory is listed in the debug output
3. Verify file permissions allow reading the plugin files

​

Distribution and versioning reference

​

Version management

1. The version field in the plugin’s plugin.json
2. The version field in the plugin’s marketplace entry in marketplace.json
3. The git commit SHA of the plugin’s source, for github, url, git-subdir, and relative-path sources in a git-hosted marketplace
4. unknown, for npm sources or local directories not inside a git repository

​

See also

• Plugins - Tutorials and practical usage
• Plugin marketplaces - Creating and managing marketplaces
• Skills - Skill development details
• Subagents - Agent configuration and capabilities
• Hooks - Event handling and automation
• MCP - External tool integration
• Settings - Configuration options for plugins