Claude Code 插件系统完整参考（组件、CLI、manifest）

本文是对官方参考页的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/plugins-reference

概述

Plugin（插件） 是一个自包含的组件目录，用于扩展 Claude Code 功能。支持的组件类型：Skills（技能）、Agents（子代理）、Hooks（钩子）、MCP 服务器、LSP 服务器、Monitors（监控器）、Output Styles（输出样式）。

插件组件参考

Skills（技能）

SKILL.md frontmatter 字段：

目录结构示例：

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md（可选）
│   └── scripts/（可选）
└── code-reviewer/
    └── SKILL.md

Agents（子代理）

Agent frontmatter 支持字段（所有字段均为可选）：

安全限制：插件级 Agent 不支持 hooks、mcpServers、permissionMode 字段。

Hooks（钩子）

Hook 类型：

Hook 事件（与用户自定义 Hook 事件相同）：

MCP 服务器

配置对象常用字段：

LSP 服务器

LSP 必填字段：

LSP 可选字段：

注意： LSP 插件不包含语言服务器本体，需用户自行安装对应二进制文件。若出现 Executable not found in $PATH，检查 /plugin 错误标签页。

官方 marketplace 可用 LSP 插件：

Monitors（监控器）

Output Styles（输出样式）

插件 manifest 模式（plugin.json）

文件位置： .claude-plugin/plugin.json（整个 manifest 为可选）

省略 manifest 时，Claude Code 从默认位置自动发现组件，并从目录名派生插件名。

完整 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" }
  ]
}

必填字段

组件命名空间示例：插件 plugin-dev 下的 agent agent-creator 在 UI 中显示为 plugin-dev:agent-creator。

元数据字段

组件路径字段

所有路径须相对于插件根目录，以 ./ 开头。可指定为单值字符串或字符串数组。若要保留默认目录并追加，需显式列出默认路径。

dependencies 字段

数组，每项可以是：

• 字符串形式："helper-lib"
• 对象形式：{ "name": "secrets-vault", "version": "~2.1.0" }

手动安装的插件不会被 plugin prune 移除；只有作为依赖自动安装的才会被清理。

userConfig 字段

让用户通过配置对话框填写插件选项。键名须为合法标识符。

访问方式：

channels 字段

声明注入对话的消息频道，需绑定插件提供的 MCP 服务器。

关于未识别字段

• 无法识别的顶层字段：claude plugin validate 报告为警告（非错误），插件仍可加载
• 字段类型错误：报告为错误，导致加载失败
• 字段名偏差 1-2 字符时，给出可能的正确字段名提示
• --strict 标志：将警告升级为错误，建议在 CI 中使用
• Claude Code 忽略不认识的顶层字段，因此 plugin.json 可兼容 VS Code/Cursor 扩展 manifest、npm package.json、MCPB/DXT bundle manifest 等生态

环境变量

在 skill/agent 内容、hook 命令、monitor 命令及 MCP/LSP 服务器配置中均可使用：

CLI 命令参考

所有命令以 claude plugin 为前缀；交互式会话中对应 /plugin <subcommand>。

plugin init

初始化插件脚手架。

plugin install

从 marketplace 安装插件。参数 <plugin> 格式：plugin-name 或 plugin-name@marketplace-name

plugin uninstall

别名： remove、rm

plugin prune

移除不再被任何已安装插件依赖的自动安装依赖。别名： autoremove（需 v2.1.121+）

plugin enable / plugin disable

启用或禁用已安装插件。启用时会同步启用其声明的依赖。

plugin update

更新插件到最新版本。

plugin list

列出已安装插件（版本、来源 marketplace、启用状态）。

交互式会话中可用 /plugin list；支持 --enabled/--disabled 过滤和 ls 简写。

plugin details

显示插件的组件清单和预计 token 消耗。

claude plugin details <name>

输出按 Skills、Agents、Hooks、MCP servers、LSP servers 分组，提供两类 token 估算：

plugin validate

验证插件目录配置。

claude plugin validate <path> [--strict]

插件目录结构

标准布局

my-plugin/
├── .claude-plugin/
│   └── plugin.json         ← manifest（可选）
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── commands/
│   └── my-command.md
├── agents/
│   └── my-agent.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json
├── output-styles/
│   └── my-style.md
└── SKILL.md                ← 单技能插件可直接放根目录

默认文件位置参考

插件缓存与文件解析

缓存机制

仅 marketplace 安装的插件才被复制到缓存；通过 --plugin-dir 或 --plugin-url 安装的插件原地使用。

路径限制

已安装插件不能引用插件目录之外的文件（../ 路径遍历无效，外部文件未被复制进缓存）。

符号链接处理规则

使用 --plugin-dir 或本地路径安装的插件：仅保留指向自身目录内的符号链接，其余跳过。

路径字段行为规则汇总