本页目录10
- 插件技能自动带命名空间前缀(如 `/my-plugin:hello`),有效避免多插件命名冲突
- 插件根目录存放 `skills/`、`agents/`、`hooks/` 等目录,切勿误放入 `.claude-plugin/` 内部
- 开发期用 `--plugin-dir` 加载本地目录或 ZIP 包,`/reload-plugins` 支持热更新无需重启
- 插件可扩展 LSP 语言服务器、后台监控(`monitors.json`)和默认设置(`settings.json`)
- 社区 Marketplace 投稿前须先通过 `claude plugin validate` 本地校验
- 现有 `.claude/` 配置可迁移为可分发插件,迁移后记得删除原始文件避免重复加载
本文是对 Claude Code 官方文档「Create plugins」的中文要点摘要,完整内容以原文为准。原文链接:https://code.claude.com/docs/en/plugins
插件 vs 独立配置:如何选择
Claude Code 扩展功能有两种方式,区别主要在于共享范围:
| 方式 | 技能调用名 | 适用场景 |
|---|---|---|
独立配置(.claude/ 目录) | /hello | 单项目个人工作流、快速实验 |
| 插件(含清单文件的独立目录) | /my-plugin:hello | 团队共享、跨项目复用、社区分发 |
建议:先在 .claude/ 中独立配置快速迭代,确认可行后再打包为插件进行分发。
快速入门:创建第一个插件
前提条件:已安装并完成认证的 Claude Code。若看不到
/plugin命令,请先升级到最新版本。
第一步:创建目录与清单文件
mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin
在 my-first-plugin/.claude-plugin/plugin.json 中定义元数据:
{
"name": "my-first-plugin",
"description": "A greeting plugin",
"version": "1.0.0",
"author": { "name": "Your Name" }
}
name 字段同时作为技能命名空间前缀(如 /my-first-plugin:hello)。version 若省略且插件通过 git 分发,则以 git commit SHA 作为版本标识,且每次提交都算作新版本。
第二步:添加技能
在 skills/hello/SKILL.md 写入 YAML 前置元数据和指令内容:
---
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.
第三步:本地加载测试
claude --plugin-dir ./my-first-plugin
启动后运行 /my-first-plugin:hello 触发技能。在 SKILL.md 中使用 $ARGUMENTS 占位符可接收用户传入的参数,例如:
/my-first-plugin:hello Alex
修改文件后执行 /reload-plugins 即可热重载,无需重启 Claude Code。
插件目录结构
| 目录/文件 | 位置 | 作用 |
|---|---|---|
.claude-plugin/ | 插件根目录 | 存放 plugin.json 清单(可选) |
skills/ | 插件根目录 | 技能定义(<name>/SKILL.md) |
commands/ | 插件根目录 | 旧式平铺 Markdown 技能(新插件推荐用 skills/) |
agents/ | 插件根目录 | 自定义 Agent 定义 |
hooks/ | 插件根目录 | hooks.json 事件处理器 |
.mcp.json | 插件根目录 | MCP 服务器配置 |
.lsp.json | 插件根目录 | LSP 语言服务器配置 |
monitors/ | 插件根目录 | 后台监控 monitors.json |
bin/ | 插件根目录 | 插件启用期间加入 Bash PATH 的可执行文件 |
settings.json | 插件根目录 | 插件启用时的默认设置 |
常见错误:
skills/、agents/、hooks/等目录必须放在插件根目录,切勿放入.claude-plugin/内部。
开发更复杂的插件
LSP 语言服务器
在插件根目录添加 .lsp.json,为 Claude 提供实时代码智能(补全、诊断等)。官方已为 TypeScript、Python、Rust 等主流语言提供预置插件,仅在需要支持其他语言时才需自建:
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": { ".go": "go" }
}
}
用户安装插件后,需在本机自行安装对应的语言服务器二进制文件。
后台监控器(Monitors)
在 monitors/monitors.json 中配置后台监控任务,插件激活后 Claude Code 自动启动每个监控器,无需指示 Claude 手动开启。命令的每行标准输出在会话期间实时作为通知推送给 Claude:
[
{
"name": "error-log",
"command": "tail -F ./logs/error.log",
"description": "Application error log"
}
]
默认设置(settings.json)
插件携带的 settings.json 可在插件启用时自动激活自定义 Agent 作为默认主线程(套用其系统提示、工具限制与模型),目前仅支持 agent 和 subagentStatusLine 两个字段;settings.json 优先级高于 plugin.json 中声明的 settings,未知字段会被静默忽略:
{ "agent": "security-reviewer" }
本地测试技巧
--plugin-dir支持目录或.zip压缩包(需 Claude Code v2.1.128+)- 多次指定该 flag 可同时加载多个插件:
claude --plugin-dir ./p1 --plugin-dir ./p2 - 用
--plugin-url加载远程 ZIP 存档(如 CI 构建产物),支持空格分隔多 URL 或多次指定 flag - 本地插件与已安装同名插件冲突时,本地版本在该会话中优先生效(但受管理员强制启用/禁用设置约束)
分发与发布
- 用
claude plugin init my-tool在~/.claude/skills/下快速初始化个人插件,下次启动以my-tool@skills-dir自动加载(前提是该工作区已被信任,详见官方 Skills-directory plugins 参考) - 提交前运行
claude plugin validate进行本地校验(审核流水线执行相同检查,并附带自动安全筛查) - Anthropic 维护两个公共 Marketplace:
claude-plugins-official:官方策划,不接受申请,由 Anthropic 自主决定收录claude-community:开放社区投稿,审核通过后收录;用/plugin marketplace add anthropics/claude-plugins-community订阅
- 提交入口:claude.ai 管理设置(需 Team/Enterprise 组织且具备目录管理权限,组织 Owner 默认拥有)或 Console 表单(不属于 Team/Enterprise 组织的个人开发者可用)
- 社区目录每晚同步,审核通过到上线之间可能存在延迟,可在社区 catalog 中搜索插件名确认
从现有配置迁移到插件
将 .claude/ 中已有的命令、Agent、Hook 迁移为插件分四步:
- 创建插件目录并添加
.claude-plugin/plugin.json - 将
commands/、agents/、skills/复制到插件根目录 - 将
settings.json中的hooks对象提取为hooks/hooks.json(格式完全相同) - 运行
claude --plugin-dir ./my-plugin验证各组件正常工作
完成迁移后,记得删除 .claude/ 中的原始文件以避免重复加载——项目和用户目录中的同名 Agent 定义会覆盖插件版本,只有删除原始文件后插件版本才会生效。