name: run-
description: Build, run, and drive . Use when asked to start , run its tests, build it, take a screenshot of its UI, or interact with the running app.

<One-sentence description: what this is and how an agent drives it.
Name the handle here - "drive it via
.claude/skills/run-<unit-name>/driver.mjs under xvfb" for a desktop
app, or "start the dev server then drive it via chromium-cli" for a
web app - so an agent knows where to look first.>

<一句话描述：这是什么，代理如何驱动它。
在这里写明操作入口——桌面应用写"在 xvfb 下通过
.claude/skills/run-<unit-name>/driver.mjs 驱动"，
web 应用写"启动开发服务器后通过 chromium-cli 驱动"——
让代理知道首先该看哪里。>

<If the unit isn't at repo root:>
<若该单元不在仓库根目录：>
All paths below are relative to <unit-dir>/.

以下所有路径均相对于 <unit-dir>/。

Prerequisites / 前提条件

<System-level requirements. The exact apt-get install line you ran -
not a generic list, the one that actually worked. Target Ubuntu.>

<系统级依赖。写出你实际运行的那条 apt-get install 命令——
不是通用清单，而是真正生效的那一条。目标系统为 Ubuntu。>

sudo apt-get update
sudo apt-get install -y <packages-you-actually-installed>

<Runtime versions if they matter:>
<若运行时版本有影响：>

# Example: Node 20 via nvm, Python 3.12 via uv, etc.

Setup / 安装配置

<One-time setup after clone: install deps, configure, apply any patches (feature-gate overrides, config stubs) with the exact command.>
<克隆后的一次性设置：安装依赖、配置、以精确命令应用
所有补丁（特性开关覆盖、配置桩）。>

<commands>

<Env vars - required vs optional, with sensible defaults:>
<环境变量——区分必填与可选，并给出合理默认值：>

export FOO_API_KEY=...   # required - get from <where>
export BAR_MODE=dev      # optional - default is prod

Build / 构建

<Skip if no separate build step. Otherwise the exact command:>
<如无独立构建步骤则省略本节。否则写精确命令：>

<command>

Run (agent path) / 运行（代理路径）

<This is the section a future agent actually uses. If you built a
driver/REPL/smoke script, this documents how to launch it and what it
does. If the app is simple enough that curl or a one-liner suffices,
that one-liner goes here.>

<这是未来的代理真正会使用的章节。如果你写了
driver/REPL/冒烟脚本，这里要写明如何启动它、它做什么。
如果应用简单到 curl 或一行命令即可，那一行命令就写在这里。>

<launch-the-driver-or-smoke-script>

<For REPL-style drivers, show the tmux wrapping. Poll for a ready marker between send-keys and capture-pane - faster than a fixed sleep and fails loudly instead of capturing a half-rendered screen:>
<对于 REPL 式 driver，展示 tmux 包装方式。在 send-keys 与
capture-pane 之间轮询就绪标记——比固定 sleep 更快，
且会明确报错而不是截取到渲染了一半的画面：>

tmux new-session -d -s app -x 200 -y 50
tmux send-keys -t app '<launch command>' Enter
timeout 30 bash -c 'until tmux capture-pane -t app -p | grep -q "<ready-marker>"; do sleep 0.2; done'
tmux send-keys -t app '<first driver command>' Enter
tmux capture-pane -t app -p

<Where artifacts land (screenshots, logs) - absolute paths:>
<产物（截图、日志）落盘位置——绝对路径：>

Screenshots -> /tmp/shots/. Logs -> /tmp/<app>.log.

截图 -> /tmp/shots/。日志 -> /tmp/<app>.log。

<If the driver has commands, a table:>
<若 driver 有命令，用表格：>

Run (human path) / 运行（人工路径）

<If meaningfully different from the agent path. Brief - agents won't use this, humans can figure it out.>
<仅当与代理路径有实质差异时才写。要简短——代理不会用这一节，
人类自己能弄明白。>

<command>   # -> <what happens>. <how to stop>.

Test / 测试

<command>

<Expected result - "N suites pass", or specific known-flaky tests.>
<预期结果——"N 个测试套件通过"，或指出特定的已知不稳定测试。>

<Optional sections below - include only if relevant and only with content you actually hit, not generic advice.>
<以下是可选章节——仅在相关时收录，且只写你真正遇到的
内容，不要写泛泛之谈。>

Gotchas / 陷阱

<Non-obvious traps. The things that look like they should work but don't, with the workaround. If this section is generic, delete it.>
<不明显的坑。那些看起来应该可行实际却不行的事，
连同绕过办法一起写。如果这一节内容很平庸，就删掉它。>

• <specific thing> - <why it breaks> -> <what to do instead>
<具体事物> - <为何会坏> -> <应当怎么做>

Troubleshooting / 故障排查

<Symptom -> fix. Only errors you actually encountered.>

<Symptom -> 修复方法。只收录你实际遇到的错误。

• <exact error message or symptom>: <cause>. <fix>.
  <精确的报错信息或症状>：<原因>。<修复方法>。

<---

NOTE ON THE FRONTMATTER ABOVE:
关于上方 front matter 的说明：

• Replace in both name: and description:. The name:
  becomes the slash command (/run-<unit-name>) and must match the
  directory name.

• 将 name: 和 description: 中的 都替换掉。name:
  会成为斜杠命令（/run-<unit-name>），必须与目录名一致。

• The description: is what Claude scans to decide whether to load this
  skill automatically. Keep the verbs - "start," "run," "build," "test,"
  "screenshot" - they're what an asking agent will actually type.

• description: 是 Claude 用来判断是否自动加载本技能的依据。
  保留那些动词——"start"、"run"、"build"、"test"、"screenshot"——
  它们正是发起询问的代理会实际输入的词。

NOTE ON THE DRIVER:
关于 driver 的说明：

• If you wrote a driver script, it lives in this same directory (next
  to this file) by default. Reference it from the Run section.

• 如果你写了 driver 脚本，默认它放在本目录（与本文件同级）。
  在 Run 章节中引用它。

• For a web app there's usually no driver file - the chromium-cli
  heredoc in the Run section is the harness.

• 对 web 应用通常没有 driver 文件——Run 章节中的 chromium-cli
  heredoc 就是测试装置。

• If the driver grows into something the project's test suite wants -
  shared launch helpers, a real e2e harness - move it to scripts/ or
  e2e/ in the unit, and update the paths here. The skill stays put.

• 如果 driver 成长为项目测试套件需要的东西——共享的启动辅助、
  真正的 e2e 装置——把它移到该单元的 scripts/ 或 e2e/ 中，
  并更新此处的路径。本技能文件保持在原地。

Delete everything from --- above onwards before committing. --->

提交前删除从上面的 --- 起及其后的全部内容。 --->