它到底是什么

/run-skill-generator 是 Claude Code 的一个捆绑 skill(bundled skill),属于元 skill:它不直接运行应用,而是为当前项目生成专属的 run skill——一套包含 SKILL.md 说明文档与可执行 driver 脚本的目录,让未来的 agent 能够构建、启动并以程序化方式操控这个项目的应用。

其内部 description 字段(控制 Claude 自动加载的字段)原文为:

"Author or improve the run-<unit> skill — a per-project skill that tells agents how to build, launch, and drive this project's app."

关于版本要求:问题描述中提到的 v2.1.145 版本号在本次访问的全部来源(含 code.claude.com 官方文档)中均未出现,无法核实,故不列入正文。

关于官方文档收录情况:截至 2026-06-14,code.claude.com 的 Commands 页与 Skills 页均未按名称收录 /run-skill-generator。此命令的系统提示内容来源于第三方项目 Piebald-AI/claude-code-system-prompts(该项目从 Claude Code 二进制中提取内置 skill 系统提示)。

怎么触发 / 怎么使用

1. 直接调用

/run-skill-generator

在项目目录的 Claude Code 会话里输入即可触发。Claude 进入此 skill 后执行以下工作流:

1. 检查现有 skill — 优先查找 .claude/skills/run-*/ 下已有内容;如有则以"更新"模式运行,不从零重写
2. 实际启动应用 — 真正执行 build + launch,不依赖 README 里的文字描述
3. 构建 driver 脚本 — 按应用类型分流:浏览器驱动型(browser-driven)应用用 dev server + chromium-cli 脚本驱动,Web server / API 型应用用后台启动 + curl 冒烟脚本,TUI / 交互式终端应用用 tmux wrapper 驱动,Electron / 桌面 GUI 应用用 xvfb 下的 Playwright _electron REPL driver(注意:tmux 与 Playwright/_electron/xvfb 是两类不同的驱动方式,分别对应终端型与桌面 GUI 型应用)
4. 写 SKILL.md — 将实测结果、遇到的障碍、troubleshooting 全部写入
5. 逐行跟随 SKILL.md 验证 — 严格按照刚写好的 SKILL.md 逐行执行一遍,确认 driver 与文档完全可复现、无遗漏

2. 生成物位置

<unit>/.claude/skills/run-<unit-name>/
├── SKILL.md       ← agent 读取的使用说明("driver 的 man page")
└── driver.mjs     ← 可执行 driver 脚本(或等价语言)

生成后,同一项目里的其他 agent 可通过 /run-<unit-name> 直接调用该 skill。

保存 / 配置 / 集成

生成的 skill 是普通文件,提交到 git 后全团队共享。SKILL.md 的 description 字段控制 Claude 是否自动加载:Claude 会根据当前请求语义扫描已知 skill 的 description 字段并决定是否自动挂载——无需手动键入 /run-<unit-name>。官方仅说明 description 字段控制自动加载,并未枚举任何具体触发词;此处的 "run"、"start"、"screenshot" 等动词仅为依据 description 语义推断的可能触发词,不应视为官方明示的清单。

跟同类原语对比

/run 与 run-skill-generator 使用相同的按项目类型模式作为兜底;/run-skill-generator 本质上是在为项目定制一个比兜底更精准的版本。

经典使用场景

• 新 clone 的前端仓库:agent 首次需要截图验证 UI 变更前,先调用 /run-skill-generator 生成带 Chromium driver 的 run skill,后续 /run 与 /verify 均可复用。
• 桌面 GUI 项目:手写 xvfb 下的 Playwright _electron REPL driver 成本高;让此 skill 实测启动流程后自动生成 driver 脚本。
• 接手含过时 run skill 的遗留项目:直接调用——skill 检测到现有内容后以"更新"模式运行,不从零开始。

常见坑

以下直接来自 skill 系统提示的"Red flags — you are about to ship the wrong thing"章节:

1. 没有截图就宣告 GUI 应用完成。对任何带界面的应用,必须有实际截图才算证明启动成功。
2. 没有 driver 脚本就提交 SKILL.md。skill 的交付物是 driver,"SKILL.md 是它的 man page"——缺 driver 等于任务未完成。
3. 生成内容与 README 重复。若输出内容与已有文档几乎相同,说明 agent 根本没有实际执行;真正遇到的障碍才是应写进 troubleshooting 的内容。
4. "平台不支持"未经验证就写入。不能仅凭声称就写平台限制,必须实际尝试启动后方可记录。

关闭 / 退出 / 卸载

/run-skill-generator 生成的 skill 以普通文件持久存在。若要移除:

rm -rf .claude/skills/run-<unit-name>/

来源

• Extend Claude with skills — code.claude.com
• Commands — code.claude.com
• skill-run-skill-generator.md — Piebald-AI/claude-code-system-prompts