Claude Code 插件怎么写:自定义命令、Hook 到 Mod,我的上手笔记
Claude Code 插件怎么写?清单、自定义命令、Hook,再到 Mod,我按官方文档捋了一遍最小能跑的写法,顺便说说我最想先写的“交作业”面板。

这篇是我自己琢磨 Claude Code 插件怎么写的笔记,不是装机清单。只想找现成的、装上就能用的,我另外整理过一篇Claude Code Mods 推荐。这里反过来,自己动手写。一个插件可以小到只有一条自定义斜杠命令,也可以挂上 Hook;10 月起还能带 Mod,就是跑在 Claude Code 里面、连面板都能画的 JavaScript。说实话让我真想动手的是最后这个:Claude Code 能给自己写扩展,写完直接加载进当前会话。
用 AI 做事,总有一些要求要反复交代:“把来源留下”“改完跑一下检查”“告诉我还有哪里没做”。现在,我们有机会把其中一部分做进工具里。我最希望的是,不用一直盯着 AI 干活。
Anthropic 在 2026 年 10 月 1 日的发布文章里,用一句话概括了这种玩法:
“You can also use Claude Code to mod Claude Code.”
Anthropic · Customize Claude Code with mods
Claude Mods 怎么改造 Claude Code
翻过来就是:用 Claude Code 改造 Claude Code。这个说法容易让人联想到 AI 自我进化,实际开放的是 Claude Code 这层软件。模型本身没有因此换代,你能改的是它周围的工具调用、操作流程和部分界面。
原理也不玄乎。提交提示、调用工具、绘制界面,都会产生事件。Mod 用 JavaScript 或 TypeScript 注册处理函数,在这些位置观察、修改或接管事件。比如工具调用前先做判断,调用后整理结果,再把你关心的信息显示在旁边。扩展装在普通插件里,可以安装、分享,也能让 Claude 帮你写。具体接口见官方文档。
Skills、MCP、Hooks 原本就能让用户给 AI 写规矩、接工具、挂脚本。Mods 继续往 Claude Code 内部开放,尤其是界面和交互:你能把自己的判断流程做成一个面板、一组按钮,跟着会话一起工作。官方能力对照。想搞明白 Claude Code 插件怎么写,先把这点理清:Mod 只是插件的一种,同一个插件里可以同时放 Skill、Hook 和 Mod。
如果你想先装现成的插件,Anthropic 官方的 skills 套件和社区精选都整理在我们的Claude Code Mods 推荐清单里。
Claude Code 插件怎么写:先搭一个最小能跑的
动手前我把官方的插件文档过了一遍,最小的插件比我想的还小。就是一个文件夹,里面放 .claude-plugin/plugin.json,写个 name(不能有空格,它会变成插件里所有东西的前缀),想写的话再加描述和版本号。这就是清单文件。其他目录都放在 .claude-plugin/ 旁边,别放进去。文档里反复强调这一点,估计踩坑的人不少。
我会先放一条自定义命令。现在自定义命令已经并进了 Skills,所以是建一个 skills/handoff/SKILL.md:顶上几行 YAML,写 description,只想自己手动触发就加 disable-model-invocation: true,下面就是大白话指令。放在插件里会带命名空间,变成 /my-plugin:handoff。老的 commands/ 目录放平铺的 Markdown 也还能用,只是旧写法。我这条的内容,其实就是平时反复粘贴的那三句:留来源,跑检查,告诉我还差什么。
Hook 管的是“每次都必须执行”的规矩,不靠 Claude 自觉。插件里写在 hooks/hooks.json,格式和设置文件里的 hooks 一样。文档自带的例子是一个 PostToolUse Hook,matcher 写 Write|Edit,每次改完文件就跑一遍 lint。这个我基本会原样抄。
再往上才是 Mod。Mod 其实就是多了一个 hooks 模块的插件:hooks/register.js 导出 register(on),监听 tool.call、ui.render 这类事件。官方示例数工具调用次数、把数字挂在 spinner 旁边,二十来行。终端里要 Claude Code v2.1.287 以上才支持 Mods。
my-plugin/
├── .claude-plugin/plugin.json
├── skills/handoff/SKILL.md
└── hooks/
├── hooks.json
└── register.js
调试阶段不需要什么插件市场。claude plugin validate ./my-plugin 检查清单和 frontmatter,claude --plugin-dir ./my-plugin 只在这一次会话里加载,改完文件跑 /reload-plugins 就生效,不用重启。懒得自己敲也行,直接描述你想要什么,Claude Code 自带一个写 Mod 用的 plugin-authoring skill。不过它写的每一行我还是会看(原因放在文末)。Claude Code 插件怎么写,说到底就这些。真正难的是想清楚什么值得放进去。
一句话总结就是四步:写好清单,加一个 Skill 当自定义命令,把必须每次执行的规矩写进 hooks/hooks.json,真需要界面再上 Mod。每加一步就用 --plugin-dir 加载试一次,哪块坏了一眼就知道。
3 个实用的 Claude Mods 插件示例
看官方的三个示例就明白了。Token Weather 把上下文占用摆出来,让你知道什么时候该整理信息;Blast Radius 在部分危险命令执行前展示预计影响,给你继续或取消的选择;Replay Theater 则把上一轮改动逐项回放。想知道它到底改了哪儿,现在翻起来方便多了。
这些小功能放在功能列表里并不起眼。有人想盯着上下文,有人习惯逐项审阅改动,有人需要一边读来源、一边整理结论。厂商很难把每个人的习惯都做进去。现在用户可以围绕自己的任务补这一块,做得顺手了,还能把扩展分享出去。这三个示例本身也是学 Claude Code 插件怎么写的好材料,每个 README 都写了是怎么做出来的。
Claude Mods 与 DeepSeek Harness 有什么不同
DeepSeek 更早就在探索这个方向。2026 年 8 月的Harness 历史源码里,模型适配器、工具注册表、会话日志、Agent 执行循环都已经做成插件;同期的动态插件工具也允许 AI 检查并扩展当前运行环境,包括 Web 界面。今天官方介绍的 Creator 模式,就是把检查运行时、试验和创建扩展放到一套使用流程里。
两家的开放范围不完全一样:Claude Mods 让你定制现有的 Claude Code,DeepSeek Harness 把更多核心部件交给插件组合。时间线能说明 DeepSeek 更早有相关实现,单凭这一点,还没法判断谁借鉴了谁。更值得留意的共同点是:用户开始能把 AI 的工作环境一起改了。
工具设计到底能帮 AI 做成多少
工具和反馈会影响 AI 最后能做成多少,SWE-agent 的研究给过一个具体例子。NeurIPS 2024 的这篇论文,用同一个 GPT-4 Turbo 跑 SWE-bench Lite 的 300 个任务:Shell-only 环境加上示例,解决率是 11%;换成专门设计的 Agent-computer interface,解决率到了 18%,提高 7 个百分点。同一论文还比较了编辑接口:加入代码检查后,解决率从 15% 到了 18%。论文表 1、表 3
这是旧模型、特定基准上的结果,不能拿来给今天的 Mods 报提效数字。但它说明了一件事:工具怎么组织、出错后怎么反馈,会影响 Agent 最后能做成多少。给它一个有用的检查结果,再让它继续修,值得认真设计。

然后还得看,它替人省下了什么。METR 在 2026 年 5 月发布的一项调查覆盖了 349 名技术工作者:自报的任务速度倍数中位数是 3 倍,三种“工作价值”问法得到的自报倍数中位数则是 1.4—2 倍。这里的倍数是受访者自己估计的,样本也有选择偏差,不能当成计时测出来的收益。调查原文。这组数据提醒我,做得更快、做得更多,与最终交付有多大价值,要分开看。
放到 Mods 上,我的标准很简单:装上以后,能不能少追问几遍、少翻几屏记录、少返工一次?如果 AI 每轮输出都很热闹,我却得花更多时间替它收拾后续,那这个扩展对我就没什么吸引力。我评价一个 Agent,也会看它交付之后还留下多少活给我做。如果它写代码很快,但最后要我花一小时收拾,这一小时也应该算进去。
我想写的第一个插件:交作业面板
Claude Code 插件怎么写,落到我自己身上就是一个问题:先写什么?我想先做一个“交作业”面板。它的规格不用花哨,把三件事摆清楚就行:
- 改了什么:对应文件、页面入口和实际差异。
- 查了什么:运行过的检查、原始结果,以及失败的项目。
- 还差什么:没检查的地方,需要我决定的事项。

比如让 AI 修 Binmage 的语言切换,我想看到三种语言有没有切过、手机端有没有看过、首屏的问题有没有复现。点开结果就能检查,没做的项目就标明没做。这样我拿到的是一份能顺着往下查的交付,不用再从一长串“已优化、已修复、已完成”里猜进度。
安装 Claude Mods 前,要检查什么
这里还得留一道检查:面板汇总的信息,也要有可核对的出处。官方文档说明,Mods 能改写工具结果,甚至能在会话记录存储前修改其中的行。重要发布的检查,仍然值得交给权限分开的 CI 或受保护的检查程序;面板负责把结果拿来给我看。把“生成完成报告”和“验收通过”全交给同一套可改写的记录,我不会放心。这种担心并不多余:在 InnovationEval 评测里,就出现过AI 提交的科研报告和它自己的工作笔记对不上的情况。
真要安装扩展,也得按装代码来对待。就算你已经知道 Claude Code 插件怎么写、扩展是自己写的,也一样。Mods 会使用你的账户权限读写文件、启动进程和联网,官方明确说它没有安全沙箱。让 AI 帮忙写出来的代码,同样需要检查。面板做得好看,不代表背后的代码就安全。
这个“交作业”面板目前还是我的设想,上面讲的 Claude Code 插件怎么写,也还是照着文档捋的,不是我自己仓库里跑过的。做出来以后,我会拿实际的网站修改来试:有没有少追问,有没有更快发现没做完的地方,检查结果是不是方便重跑。它能让我少盯一会儿、又不至于漏掉问题,就值得留着。
2026-10-24 更新:geckobox,把 Claude Code 插件和 Agent 分发到多台机器
搞清楚 Claude Code 插件怎么写之后,下一步常常是想让 Agent 跑在别的机器上。geckobox(命令行叫 openspaces)就是干这个的新开源工具,许可证是 MIT。README 称,它能让 Claude Code 等编程 Agent 跑在本机、任何能 SSH 上去的机器,或者 Docker 容器里;一条命令就能把同一个任务分发到好几台机器。README 还称它不需要账号、不走中继,直接连你自己的机器(NAT 后面的机器,它建议配 Tailscale)。
安装就一条 npm 命令(要求 Node 20 以上)。openspaces ui 会在 127.0.0.1 开一个本地面板,命令行也能做同样的事:
npm install -g github:migasrias2/geckobox
openspaces ui
# 或者直接用命令行
openspaces computers add mini ssh:[email protected]
openspaces run --on local,mini,docker:ci "跑一遍测试,总结失败项"
它还很新:版本 0.1.0,仓库 2026 年 10 月 20 日才建。README 称只有 claude-code 和 shell 两个适配器做过实机测试,Codex、Gemini、OpenCode 还没有。我自己也还没在多台机器上跑过。
适合谁:手上已经有闲置 Mac mini、VPS 或 Docker 主机,想把同一件事(跑测试、查部署、清磁盘)一次发给几台机器,又不想注册托管服务的人。只用一台笔记本的话,用不上。
风险要单独说。--auto-approve 等于把全部权限交给 Agent:在 geckobox 源码里,它对应 Claude Code 的 --dangerously-skip-permissions(Codex 则是 --dangerously-bypass-approvals-and-sandbox)。再加上多机分发,一条写错的指令,或者网页里藏的注入指令,就可能同时在几台机器上执行任意命令。README 称默认只在 docker: 和 cua: 目标上跳过确认,local 和 ssh: 用的是 Claude Code 的 acceptEdits 模式。刚上手先别改:先在 Docker 或测试机上试,别让它碰存着生产密钥或用户数据的机器。
README 把它定位成付费产品 Cua Spaces 的独立替代品(与 Cua 无关联)。能核实的差别是:Cua 定价页写明,免费版通过 Cua 托管中继每月有 2 个并发会话、20 小时远程时长,Pro 按年付每月 15 美元(按月付 18 美元),有 5 个会话、200 小时,不过在你自己网络里直连的 Space 不走中继、不计额度;而 README 称 geckobox 根本没有中继,也就没有额度可算。
仓库地址:
资料核对日期:2026 年 10 月 3 日;插件、Skills、Hooks 文档于 2026 年 10 月 20 日复核。本文基于官方文档、历史源码和原始研究,暂未独立实测 Mods/Creator;“交作业”面板是作者提出的用法。