文档索引

获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后进一步探索。

插件参考

Claude Code 插件系统的完整技术参考，包括模式、CLI 命令和组件规范。

本参考提供 Claude Code 插件系统的完整技术规范，包括组件模式、CLI 命令和开发工具。

插件是一个自包含的组件目录，通过自定义功能扩展 Claude Code。插件组件包括技能、代理、hooks、MCP 服务器、LSP 服务器和监视器。

插件组件参考

技能

插件向 Claude Code 添加技能，创建你或 Claude 可以调用的 /name 快捷方式。

位置：插件根目录中的 skills/ 或 commands/ 目录，或插件根目录中的单个 SKILL.md 文件

文件格式：技能是包含 SKILL.md 的目录；命令是简单的 markdown 文件

技能结构：

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

集成行为：

• 安装插件时会自动发现技能和命令
• Claude 可以根据任务上下文自动调用它们
• 技能可以在 SKILL.md 旁边包含支持文件

有关完整详情，请参阅技能。

代理

插件可以为特定任务提供专用子代理，Claude 可以在适当时自动调用。

位置：插件根目录中的 agents/ 目录

文件格式：描述代理能力的 Markdown 文件

代理结构：

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

插件代理支持 name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background 和 isolation frontmatter 字段。唯一有效的 isolation 值是 "worktree"。出于安全原因，插件附带的代理不支持 hooks、mcpServers 和 permissionMode。

集成点：

• 代理出现在 /agents 界面中
• Claude 可以根据任务上下文自动调用代理
• 用户可以手动调用代理
• 插件代理与内置 Claude 代理协同工作

有关完整详情，请参阅子代理。

Hooks

插件可以提供自动响应 Claude Code 事件的事件处理器。

位置：插件根目录中的 hooks/hooks.json，或内联在 plugin.json 中

格式：包含事件匹配器和操作的 JSON 配置

Hook 配置：

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

插件 hooks 响应与用户定义 hooks 相同的生命周期事件：

Hook 类型：

• command：执行 shell 命令或脚本
• http：将事件 JSON 作为 POST 请求发送到 URL
• mcp_tool：调用已配置的 MCP 服务器上的工具
• prompt：使用 LLM 评估提示词（使用 $ARGUMENTS 占位符表示上下文）
• agent：运行带有工具的代理验证器，用于复杂的验证任务

MCP 服务器

插件可以捆绑模型上下文协议（MCP）服务器，将 Claude Code 连接到外部工具和服务。

位置：插件根目录中的 .mcp.json，或内联在 plugin.json 中

格式：标准 MCP 服务器配置

MCP 服务器配置：

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

集成行为：

• 插件 MCP 服务器在插件启用时自动启动
• 服务器作为标准 MCP 工具出现在 Claude 的工具包中
• 服务器功能与 Claude 现有工具无缝集成
• 插件服务器可以独立于用户 MCP 服务器进行配置

LSP 服务器

插件可以提供语言服务器协议（LSP）服务器，为 Claude 在处理代码库时提供实时代码智能。

LSP 集成提供：

• 即时诊断：Claude 在每次编辑后立即看到错误和警告
• 代码导航：跳转到定义、查找引用和悬停信息
• 语言感知：代码符号的类型信息和文档

位置：插件根目录中的 .lsp.json，或内联在 plugin.json 中

格式：将语言服务器名称映射到其配置的 JSON 配置

.lsp.json 文件格式：

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

内联在 plugin.json 中：

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

必填字段：

可选字段：

可用的 LSP 插件：

先安装语言服务器，然后从市场安装插件。

监视器

插件可以声明后台监视器，Claude Code 在插件活动时自动启动。每个监视器在会话生命周期内运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，因此 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视。

插件监视器使用与监视器工具相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，以与 hooks 相同的信任级别在非沙箱环境中运行，并在监视器工具不可用的主机上被跳过。

位置：插件根目录中的 monitors/monitors.json，或内联在 plugin.json 中

格式：监视器条目的 JSON 数组

以下 monitors/monitors.json 监视部署状态端点和本地错误日志：

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

要内联声明监视器，将 plugin.json 中的 experimental.monitors 设置为相同的数组。要从非默认路径加载，将 experimental.monitors 设置为相对路径字符串，如 "./config/monitors.json"。监视器是实验性组件。

必填字段：

可选字段：

command 值支持与 MCP 和 LSP 服务器配置相同的变量替换：{{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}、{{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA}、{{CONTENT}}amp;#123;CLAUDE_PROJECT_DIR}、${user_config.*} 以及环境中的任何 {{CONTENT}}amp;#123;ENV_VAR}。如果脚本需要从插件自身的目录运行，请在命令前加上 cd "{{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}" && 。

在会话中禁用插件不会停止已经运行的监视器。它们在会话结束时停止。

主题

插件可以附带颜色主题，这些主题与内置预设和用户的本地主题一起出现在 /theme 中。主题是 themes/ 中的 JSON 文件，包含 base 预设和稀疏的 overrides 颜色令牌映射。主题是实验性组件。

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

选择插件主题会在用户配置中持久化 custom:<plugin-name>:<slug>。插件主题是只读的；在 /theme 中按 Ctrl+E 会将其复制到 ~/.claude/themes/，以便用户可以编辑副本。

插件安装范围

安装插件时，你选择一个范围，决定插件在哪里可用以及谁可以使用它：

插件使用与其他 Claude Code 配置相同的范围系统。有关安装说明和范围标志，请参阅安装插件。有关范围的完整说明，请参阅配置范围。

插件清单模式

.claude-plugin/plugin.json 文件定义插件的元数据和配置。本节介绍所有支持的字段和选项。

清单是可选的。如果省略，Claude Code 会在默认位置自动发现组件，并从目录名称派生插件名称。当你需要提供元数据或自定义组件路径时使用清单。

完整模式

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "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" }
  ]
}

必填字段

如果你包含清单，name 是唯一的必填字段。

此名称用于组件的命名空间。例如，在 UI 中，名为 plugin-dev 的插件的代理 agent-creator 将显示为 plugin-dev:agent-creator。

未识别的字段

Claude Code 会忽略它不识别的顶层字段。你可以在 plugin.json 中保留来自其他生态系统的元数据，插件仍然会加载。这使得维护一个同时充当 VS Code 或 Cursor 扩展清单、npm package.json 或 MCPB/DXT 包清单的清单变得实用。

claude plugin validate 将未识别的字段报告为警告而非错误。如果某个字段与已识别字段相差一两个字符，警告会建议可能的正确名称。只有未识别字段警告的插件仍然通过验证并在运行时加载。

类型错误的字段仍然会导致失败。例如，keywords 值是字符串而不是数组就是加载错误，claude plugin validate 会将其报告为错误。

传递 --strict 将警告视为错误。在 CI 中使用它可以在发布前捕获拼写错误的字段名或来自其他工具清单的遗留字段，即使插件在运行时会加载。

claude plugin validate ./my-plugin --strict

元数据字段

组件路径字段

实验性组件

experimental 键下的组件（themes 和 monitors）的清单模式可能在版本之间发生变化，因为它们仍在稳定中。你在哪里声明它们是单独的迁移：顶层仍然有效，claude plugin validate 会发出警告，未来的版本将要求使用 experimental.*。

用户配置

userConfig 字段声明 Claude Code 在启用插件时提示用户输入的值。使用此选项代替要求用户手动编辑 settings.json。

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

键必须是有效的标识符。每个选项支持以下字段：

每个值都可以作为 {{CONTENT}}amp;#123;user_config.KEY} 在 MCP 和 LSP 服务器配置、hook 命令和监视器命令中替换。非敏感值也可以在技能和代理内容中替换。所有值都作为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量导出到插件子进程。

非敏感值存储在 settings.json 的 pluginConfigs[<plugin-id>].options 下。敏感值存储在系统钥匙串中（在钥匙串不可用时存储在 ~/.claude/.credentials.json 中）。钥匙串存储与 OAuth 令牌共享，总限制约为 2 KB，因此请保持敏感值较小。

通道

channels 字段允许插件声明一个或多个将内容注入对话的消息通道。每个通道绑定到插件提供的 MCP 服务器。

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

server 字段是必填的，必须与插件的 mcpServers 中的键匹配。可选的每通道 userConfig 使用与顶层字段相同的模式，允许插件在启用时提示输入 bot 令牌或所有者 ID。

路径行为规则

自定义路径是替换还是扩展插件的默认目录取决于字段：

• 替换默认值：commands、agents、outputStyles、experimental.themes、experimental.monitors。例如，当清单指定 commands 时，不会扫描默认的 commands/ 目录。要保留默认值并添加更多，请明确列出："commands": ["./commands/", "./extras/"]
• 添加到默认值：skills。默认的 skills/ 目录始终被扫描，skills 中列出的目录与其一起加载
• 有自己的合并规则：hooks、MCP 服务器和 LSP 服务器。参阅各节了解多个源如何组合

当插件同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本会在 /doctor、claude plugin list 和 /plugin 详情视图中标记被忽略的文件夹。插件仍然使用清单路径加载。当清单键指向默认文件夹内时，例如 "commands": ["./commands/deploy.md"]，不会显示警告，因为在这种情况下文件夹被显式引用。

对于所有路径字段：

• 所有路径必须相对于插件根目录并以 ./ 开头
• 自定义路径中的组件使用相同的命名和命名空间规则
• 多个路径可以指定为数组
• 当技能路径指向直接包含 SKILL.md 的目录时，例如 "skills": ["./"] 指向插件根目录，SKILL.md 中的 frontmatter name 字段决定技能的调用名称。这提供了稳定的名称，与安装目录无关。如果 frontmatter 中未设置 name，则使用目录基名作为回退。

在插件根目录有 SKILL.md、没有 skills/ 子目录且没有 skills 清单字段的插件在 Claude Code v2.1.142 及更高版本中会自动作为单技能插件加载。你不需要为此布局在 plugin.json 中设置 "skills": ["./"]。技能的调用名称遵循与上述相同的规则：frontmatter name 字段，或目录基名作为回退。

路径示例：

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

环境变量

Claude Code 提供三个变量用于引用路径。所有变量都在技能内容、代理内容、hook 命令、监视器命令以及 MCP 或 LSP 服务器配置中出现的任何位置内联替换。所有变量也作为环境变量导出到 hook 进程和 MCP 或 LSP 服务器子进程。

{{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}：插件安装目录的绝对路径。使用此路径引用与插件捆绑的脚本、二进制文件和配置文件。在 hook 命令中，使用带有 args 的 exec 形式，以便路径作为单个参数传递，无需引号。在 shell 形式的 hooks 和监视器命令中，用双引号包装，如 "{{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}"。此路径在插件更新时会更改。前一版本的目录在更新后大约七天内保留在磁盘上，然后才会被清理，但请将其视为临时性的，不要在此处写入状态。

当插件在会话中更新时，hook 命令、监视器、MCP 服务器和 LSP 服务器继续使用前一版本的路径。运行 /reload-plugins 将 hooks、MCP 服务器和 LSP 服务器切换到新路径；监视器需要重新启动会话。

{{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA}：用于在更新中保留的插件状态的持久目录。使用此目录存储已安装的依赖项（如 node_modules 或 Python 虚拟环境）、生成的代码、缓存以及应跨插件版本保留的任何其他文件。此变量首次被引用时会自动创建目录。

{{CONTENT}}amp;#123;CLAUDE_PROJECT_DIR}：项目根目录。这与 hooks 在其 CLAUDE_PROJECT_DIR 变量中接收的目录相同。使用此路径引用项目本地脚本或配置文件。用引号包装以处理带空格的路径，例如 "{{CONTENT}}amp;#123;CLAUDE_PROJECT_DIR}/scripts/server.sh"。MCP 服务器也可以调用 MCP roots/list 请求，该请求返回 Claude Code 启动时的目录。

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

持久数据目录

{{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA} 目录解析为 ~/.claude/plugins/data/{id}/，其中 {id} 是插件标识符，a-z、A-Z、0-9、_ 和 - 之外的字符被替换为 -。对于安装为 formatter@my-marketplace 的插件，目录为 ~/.claude/plugins/data/formatter-my-marketplace/。

常见用途是一次性安装语言依赖项，并在会话和插件更新之间重用它们。由于数据目录比任何单个插件版本都持久存在，仅检查目录存在无法检测更新何时更改了插件的依赖清单。推荐的模式是将捆绑的清单与数据目录中的副本进行比较，并在不同时重新安装。

此 SessionStart hook 在首次运行时安装 node_modules，并在插件更新包含更改的 package.json 时再次安装：

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

当存储的副本缺失或与捆绑的副本不同时，diff 以非零值退出，涵盖首次运行和更改依赖项的更新。如果 npm install 失败，尾部的 rm 会移除复制的清单，以便下次会话重试。

捆绑在 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT} 中的脚本可以针对持久化的 node_modules 运行：

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

当你从最后安装的范围卸载插件时，数据目录会自动删除。/plugin 界面会显示目录大小并在删除前提示。CLI 默认删除；传递 --keep-data 以保留它。

插件缓存和文件解析

插件通过两种方式之一指定：

• 通过 claude --plugin-dir 或 claude --plugin-url，仅在会话期间有效。
• 通过市场，安装供未来会话使用。

出于安全和验证目的，Claude Code 将市场插件复制到用户的本地插件缓存（~/.claude/plugins/cache）而不是就地使用。在开发引用外部文件的插件时，理解此行为很重要。

每个已安装的版本是缓存中的单独目录。当你更新或卸载插件时，前一版本目录被标记为孤立，并在 7 天后自动删除。宽限期让已经加载旧版本的并发 Claude Code 会话可以继续运行而不会出错。

Claude 的 Glob 和 Grep 工具在搜索时会跳过孤立的版本目录，因此文件结果不包含过时的插件代码。

路径遍历限制

已安装的插件无法引用其目录外的文件。遍历插件根目录外的路径（如 ../shared-utils）在安装后将不起作用，因为这些外部文件不会被复制到缓存中。

使用符号链接在市场内共享文件

如果你的插件需要与同一市场的其他部分共享文件，可以在插件目录内创建符号链接。当插件被复制到缓存时，符号链接的处理方式取决于其目标解析的位置：

• 在插件自身的目录内： 符号链接作为相对符号链接保留在缓存中，因此它在运行时继续解析到复制的目标。
• 在同一市场内的其他位置： 符号链接被解引用。目标内容被复制到缓存中替换它。这允许元插件的 skills/ 目录链接到市场中其他插件定义的技能。
• 在市场外部： 符号链接因安全原因被跳过。这防止插件将任意主机文件（如系统路径）拉入缓存。

对于使用 --plugin-dir 或从本地路径安装的插件，只有解析在插件自身目录内的符号链接才会被保留。所有其他符号链接都被跳过。

以下命令从市场插件内部创建指向兄弟插件定义的共享技能的链接。在 Windows 上，使用提升权限的命令提示符中的 mklink /D 或启用开发者模式：

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

这在维护缓存系统安全优势的同时提供了灵活性。

插件目录结构

标准插件布局

完整的插件遵循此结构：

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

插件根目录的 CLAUDE.md 文件不会作为项目上下文加载。插件通过技能、代理和 hooks 而不是 CLAUDE.md 来贡献上下文。要附带加载到 Claude 上下文中的说明，请将它们放在技能中。

文件位置参考

CLI 命令参考

Claude Code 提供用于非交互式插件管理的 CLI 命令，适用于脚本和自动化。

plugin install

从可用市场安装插件。

claude plugin install <plugin> [options]

参数：

• <plugin>：插件名称或 plugin-name@marketplace-name 用于特定市场

选项：

范围决定已安装插件添加到哪个设置文件。例如，--scope project 写入 .claude/settings.json 中的 enabledPlugins，使插件对克隆项目仓库的每个人可用。

示例：

# 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@marketplace-name

选项：

别名：remove、rm

默认情况下，从最后剩余的范围卸载也会删除插件的 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA} 目录。使用 --keep-data 保留它，例如在测试新版本后重新安装时。

plugin prune

移除不再被任何已安装插件需要的自动安装插件依赖项。Claude Code 为满足另一个插件的 dependencies 字段而拉入的依赖项会被移除；你直接安装的插件永远不会被触及。

claude plugin prune [options]

选项：

别名：autoremove

该命令列出孤立的依赖项，并在移除前请求确认。要一步移除插件并清理其依赖项，运行 claude plugin uninstall <plugin> --prune。

plugin enable

启用已禁用的插件。如果插件声明了依赖项，Claude Code 会在相同范围传递性地启用它们，当依赖项未安装时命令会失败。

claude plugin enable <plugin> [options]

参数：

• <plugin>：插件名称或 plugin-name@marketplace-name

选项：

plugin disable

禁用插件而不卸载它。当另一个已启用的插件依赖于目标时会失败。错误消息包含一个链式命令，先禁用每个依赖项。

claude plugin disable <plugin> [options]

参数：

• <plugin>：插件名称或 plugin-name@marketplace-name

选项：

plugin update

将插件更新到最新版本。

claude plugin update <plugin> [options]

参数：

• <plugin>：插件名称或 plugin-name@marketplace-name

选项：

plugin list

列出已安装的插件及其版本、源市场和启用状态。

claude plugin list [options]

选项：

plugin details

显示插件的组件清单和预计 token 成本。输出列出插件贡献的所有组件，按技能、代理、Hooks、MCP 服务器和 LSP 服务器分组，以及它为每个会话添加的 token 估计量。技能组包括 skills/ 和 commands/ 条目。

claude plugin details <name>

参数：

• <name>：插件名称或 plugin-name@marketplace-name

选项：

输出显示每个组件的两个成本数字：

• 常驻： 无论任何组件是否触发，插件的列表文本（如技能描述、代理描述和命令名称）为每个会话添加的 token。
• 调用时： 组件触发时消耗的 token。按组件显示，而非插件总计，因为典型会话仅调用组件的子集。

此示例显示具有两个技能的插件的输出：

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

常驻总计通过活动模型的 count_tokens API 计算。每组件数字从该总计按比例缩放。如果 API 不可达，命令会回退到基于字符的估计。

plugin tag

为当前目录中的插件创建发布 git 标签。从插件文件夹内运行。参阅标记插件发布。

claude plugin tag [options]

选项：

调试和开发工具

调试命令

使用 claude --debug 查看插件加载详情：

这会显示：

• 正在加载哪些插件
• 插件清单中的任何错误
• 技能、代理和 hook 注册
• MCP 服务器初始化

常见问题

示例错误消息

清单验证错误：

• Invalid JSON syntax: Unexpected token } in JSON at position 142：检查缺少的逗号、多余的逗号或未引用的字符串
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required：缺少必填字段
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...：JSON 语法错误

插件加载错误：

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.：命令路径存在但不包含有效的命令文件
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.：marketplace.json 中的 source 路径指向不存在的目录
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.：移除重复的组件定义或移除市场条目中的 strict: false

Hook 故障排除

Hook 脚本未执行：

1. 检查脚本是否可执行：chmod +x ./scripts/your-script.sh
2. 验证 shebang 行：第一行应为 #!/bin/bash 或 #!/usr/bin/env bash
3. 检查路径是否使用 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}："command": "\"{{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
4. 手动测试脚本：./scripts/your-script.sh

Hook 未在预期事件上触发：

1. 验证事件名称是否正确（区分大小写）：PostToolUse，而非 postToolUse
2. 检查匹配器模式是否匹配你的工具："matcher": "Write|Edit" 用于文件操作
3. 确认 hook 类型有效：command、http、mcp_tool、prompt 或 agent

MCP 服务器故障排除

服务器未启动：

1. 检查命令是否存在且可执行
2. 验证所有路径使用 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT} 变量
3. 检查 MCP 服务器日志：claude --debug 显示初始化错误
4. 在 Claude Code 外部手动测试服务器

服务器工具未出现：

1. 确保服务器在 .mcp.json 或 plugin.json 中正确配置
2. 验证服务器正确实现了 MCP 协议
3. 检查调试输出中的连接超时

目录结构错误

症状：插件加载但组件（技能、代理、hooks）缺失。

正确结构：组件必须在插件根目录，而不是在 .claude-plugin/ 内。只有 plugin.json 属于 .claude-plugin/。

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

如果你的组件在 .claude-plugin/ 内，请将它们移到插件根目录。

调试清单：

1. 运行 claude --debug 并查找 "loading plugin" 消息
2. 检查每个组件目录是否在调试输出中列出
3. 验证文件权限允许读取插件文件

分发和版本控制参考

版本管理

Claude Code 使用插件的版本作为缓存键，决定是否有可用更新。当你运行 /plugin update 或自动更新触发时，Claude Code 计算当前版本，如果与已安装的匹配则跳过更新。

版本从以下设置的第一个解析：

1. 插件 plugin.json 中的 version 字段
2. 插件在 marketplace.json 中的市场条目的 version 字段
3. 插件源的 git commit SHA，适用于 git 托管市场中的 github、url、git-subdir 和相对路径源
4. unknown，适用于 npm 源或不在 git 仓库中的本地目录

这为你提供了两种版本化插件的方式：

如果你使用显式版本，请遵循语义版本控制（MAJOR.MINOR.PATCH）：破坏性更改更新 MAJOR，新功能更新 MINOR，错误修复更新 PATCH。在 CHANGELOG.md 中记录更改。

另请参阅

• 插件 - 教程和实际用法
• 插件市场 - 创建和管理市场
• 技能 - 技能开发详情
• 子代理 - 代理配置和能力
• Hooks - 事件处理和自动化
• MCP - 外部工具集成
• 设置 - 插件的配置选项