mod-builder 是一个 Claude Code 插件(mod)构建技能,来源为 karanb192/claude-code-mods,地址 https://www.skills.sh/karanb192/claude-code-mods/mod-builder。
一、基本定义 按资料说明,一个 mod 就是 Claude Code 插件,其 hooks/hooks.json 在 modules 下命名一个 hooks 模块。该模块导出 register(on, options),每个 hook 是一个函数 ($, e, next)。它运行在 Claude Code 自身进程内,并拥有用户的权限范围(reach)。Mod 需要 Claude Code 2.1.287 或更高版本,默认开启,旧的 early-access 标志会被忽略。
二、支撑该技能的三条事实
- claude plugin validate <dir> 会在任何代码运行前打印出每个被 hook 的事件、每次 $ 调用、每个 env 名称和每个 state 键。
- 从 --plugin-dir 或 dev-mods 文件夹进行的每次加载,都会把运行版本的精确声明写入 <mod>/.claude-plugin/types/;claude-code/index.d.ts 第 1 行标明该 build 版本,无需额外运行即可获得。
- --debug-file <path> 会记录每次模块加载,且据观察记录大多数带插件名的 $ 调用;$.state 调用不留下调用行,$.env.get 在探测运行中也不留行。
三、权威顺序与延迟规则 权威顺序为:所运行 build 的生成类型、claude plugin validate、文档页面、声明的公开 GitHub 副本(可能滞后)、内置与示例 mod 源码、社区 mod。若页面与类型不一致,以类型为准。该技能不重述任何形状(字段、签名、元素属性、联合成员、数量),而是去 grep gate 打印的类型;它只重述决策事实、流程事实和限制,且各带标记。
四、文件放置 把 mod 写到用户指定的目录,否则写到当前目录下的 ./<name>/。除非用户希望该 mod 立即在本会话生效,否则绝不写到 ~/.claude/dev-mods/ 下;若确需如此,应说明首次写入会询问“Enable for this session”,该文件夹会在 cleanupPeriodDays 后被删除,并在交接时把 mod 复制出去。不要为获取 API 事实而加载内置 plugin-authoring 技能:加载它会启动 dev-mods 监视,且其文本会指引你写到那里;应改为 grep 类型。
五、模式 包含 Learn(解释什么是 mod)、Discover(查找 mod)、Build(构建 mod,走完整流水线,步骤 0 到 8,以交接结束)、Review(审查)、Brainstorm(构思)、Migrate(迁移)、Debug(调试)、Prove(证明)、Publish(发布)等模式,分别对应不同的用户说法与读取文件。请求含糊时,用一行重述并只问一个问题。
六、构建流水线 步骤包括:0 gate(每次会话先运行 node <skill-dir>/scripts/gate.mjs [<mod-dir>]);1 container and plan(先跑 plan.md 中的 container test,写出 Observe 行与 Do 行,按 reach 规则分级,展示计划块并请求一次确认,这是唯一的阻塞性问题);2 shape check(对计划中每个事件和方法 grep 类型,写出 shapes 列表);3 write(按 build.md 写文件,含 .claude-plugin/plugin.json、hooks/hooks.json、hooks/register.ts、README.md、DECISIONS.md 和两行 .gitignore;测试文件留到步骤 5);4 footprint(运行 footprint.mjs 并原样粘贴输出);5 tests(写测试,须先见其失败再通过;未见失败过的测试不算数);6 prove(运行 prove.mjs,把 mod 复制到 harness home 下的运行目录,驱动子 claude 且使用独立配置目录,真实 ~/.claude 永不被写入,源码树永不被改动);7 threat model(五条,来自 footprint 输出);8 hand over。
七、交接契约 回复须按顺序以指定块结尾,被省略的块要写 skipped: <reason>。块包括:文件树、计划块、gate 行(claude、mods load、types、drift、verdict)、footprint 输出原文与差异判定行、shapes 列表、proof 状态块原文与运行目录、测试结果(Tests: N pass, M fail; seen failing: yes|no)、威胁模型、DECISIONS 摘要、运行与保留方式,以及 build 印记(built against Claude Code <version> via <PATH|binary>; baseline <api-map.json version>; drift: <counts or none>)。
八、禁止声明与三次失败规则 除紧邻读作 ran and passed 的阶段外,禁止声称 tested、works、loads、draws 或 verified 于任何地方;禁止使用脚本未打印的状态词(阶段词仅四个:ran and passed、ran and FAILED、not applicable、unverified);禁止把通过的 validate、通过的 tsc、从未失败过的测试当作行为证明;禁止把模型自身回复当作 hook 运行过的证据;禁止用渲染图像或仿终端文本块充当捕获;禁止把 /context 输出当作 token 度量;禁止把 -p 运行当作有任何绘制的证明;禁止在类型相反时凭记忆给出名称或形状。prove.mjs 在同一阶段三次相同失败后以退出码 3 停止,交接该阶段为 FAILED 及其首个错误行,不得第四次尝试同类修复;任何步骤同一消息连续失败三次也适用此规则;绝不用计算访问、别名或对 $ 的可选链来绕过 validator 拒绝。
九、脚本退出码 除 star-invitation.mjs 外,每个脚本都接受 --json。gate.mjs:0 继续,1 继续但引用部分过时,2 停止。footprint.mjs 与 api-check.mjs:0 正常,1 有发现,2 工具错误。prove.mjs:0 无阶段失败,1 某阶段失败,2 被阻塞,3 三次失败。list-mods.mjs:0,或 fetch 失败时 1(工具失败而非发现)。
资料中未提供该技能的费用、价格、平台支持范围、实际运行效果以及官方页面文本等信息。