script-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

script-builder

You are converting testing/validation intent into a durable, re-runnable script committed to the target project's

scripts/

directory. The output is context-optimal: a single PASS/FAIL line +

/tmp

log path on success, full verbose output redirected to a timestamped log file, and an

<important if>

block in

CLAUDE.md

AGENTS.md

so future agents discover the script when the relevant testing intent recurs.

你需要将测试/验证意图转换为持久化、可重复运行的脚本，并提交到目标项目的

scripts/

目录中。输出需符合上下文最优要求：成功时输出单行PASS/FAIL信息及

/tmp

日志路径，完整详细输出重定向至带时间戳的日志文件，同时在

CLAUDE.md

AGENTS.md

中添加

<important if>

代码块，以便后续Agent在遇到相关测试意图时能发现该脚本。

Working Agreement

工作约定

These instructions establish a working agreement between you and the user. The key principles are:

AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, preferences, decisions, confirmations), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.
Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.
Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

以下指令确立了你与用户之间的工作约定，核心原则如下：

AskUserQuestion是你的主要沟通工具 - 无论何时你需要向用户询问任何内容（澄清、偏好、决策、确认），都要使用AskUserQuestion工具。不要以纯文本形式输出问题，务必使用结构化工具以便用户高效回复。
提前确认偏好 - 在工作流开始时就询问用户偏好，不要等到用户可能想要结束时才问。
自主模式指导交互程度 - 用户选择的自主级别决定了你需要多久确认一次，但AskUserQuestion始终是所有问题的沟通机制。

When to Use

使用场景

This skill activates when:

User invokes
```
/script-builder
```
command

Another skill references

**OPTIONAL SUB-SKILL:** desplega:script-builder

A
```
planning
```
,
```
qa
```
, or
```
verifying
```
flow needs a re-runnable validation script that doesn't yet exist
The user expresses intent to "turn X into a script", "wrap this validation into something reusable", or "I want to test X end-to-end" with no existing script

当出现以下情况时，该技能将激活：

用户调用
```
/script-builder
```
命令

其他技能引用

**OPTIONAL SUB-SKILL:** desplega:script-builder

```
planning
```
、
```
qa
```
或
```
verifying
```
流程需要一个尚未存在的可重复运行验证脚本
用户表达类似“把X转成脚本”、“把这个验证逻辑包装成可复用的内容”或“我想端到端测试X”且当前无对应脚本的意图

Autonomy Mode

自主模式

Adapt your behavior based on the autonomy mode:

Mode	Behavior
Autopilot	Detect mode, draft, syntax-check, document, and (if escalation tier) run + iterate without intermediate confirmations. Pause only at hard blockers or destructive side-effects.
Critical (Default)	Confirm at each tier boundary (after draft, before doc edit, before run). Use AskUserQuestion for fix application during iterate loop.
Verbose	Confirm before each step. Show every diff. Walk through detection reasoning out loud.

The autonomy mode is passed by the invoking command. If not specified, default to Critical.

根据自主模式调整你的行为：

模式	行为
Autopilot	检测模式、起草脚本、语法检查、生成文档，若属于升级层级则无需中间确认直接运行并迭代。仅在遇到硬阻塞或破坏性副作用时暂停。
Critical（默认）	在每个层级边界确认（起草后、编辑文档前、运行前）。在迭代循环中使用AskUserQuestion工具确认修复方案。
Verbose	每一步操作前都确认。展示所有差异。详细说明检测推理过程。

自主模式由调用命令传入。若未指定，默认使用Critical模式。

Process Steps

流程步骤

Step 1: Detect Mode (Retrospective vs Forward-Declared)

步骤1：检测模式（回顾式 vs 前瞻式）

Decide silently — do not ask the user "which mode?". Use the following heuristics:

Scan recent session tool-use history (the last ~20 tool calls in the current conversation) for test/validation-shaped activity:
```
curl
```
/
```
fetch
```
calls,
```
bun run
```
/
```
python
```
/
```
pytest
```
, database queries,
```
qa-use
```
browser actions, repeated
```
grep
```
/log inspection of a single endpoint or table. If ≥2 such actions targeting the same area exist → retrospective mode.
Parse the user's invocation message for cues:
- Narrative cues → retrospective: "we just figured out", "turn this into a script", "wrap that in", "that thing we just did".
- Intent cues → forward-declared: "I want to test", "validate that", "smoke check", "check before deploy".
Fallback: when ambiguous, default to forward-declared.

Retrospective first action: summarize the observed activity back to the user as plain text (≤6 lines: what was probed, against what, with what success signal), then go to Step 3 with a confirmation prompt instead of Q&A.

Forward first action: skip directly to Step 3's Q&A.

自行判断——不要询问用户“使用哪种模式？”。请遵循以下启发式规则：

扫描近期会话工具使用历史（当前对话中最近约20次工具调用），查找测试/验证类操作：
```
curl
```
/
```
fetch
```
调用、
```
bun run
```
/
```
python
```
/
```
pytest
```
、数据库查询、
```
qa-use
```
浏览器操作、针对单个端点或表的重复
```
grep
```
/日志检查。若存在≥2个针对同一领域的此类操作 → 回顾式模式。
解析用户的调用消息寻找线索：
- 叙事线索 → 回顾式：“我们刚弄清楚”、“把这个转成脚本”、“把那个包装成”、“我们刚做的那件事”。
- 意图线索 → 前瞻式：“我想测试”、“验证一下”、“冒烟测试”、“部署前检查”。
回退方案：若存在歧义，默认使用前瞻式模式。

回顾式模式首个操作：以纯文本形式向用户总结观察到的活动（≤6行：探测内容、目标对象、成功信号），然后进入步骤3并发送确认提示而非问答。

前瞻式模式首个操作：直接跳至步骤3的问答环节。

Step 2: Scan Existing Scripts for Overlap

步骤2：扫描现有脚本以排查重叠

Resolve the scripts directory in this order:

Check
```
CLAUDE.md
```
for a
```

```
marker. If present, use that path.
If
```
scripts/
```
exists at the repo root, use it.

Use AskUserQuestion with options:

scripts/ (Recommended) | custom path | skip dir persistence for this run

Edge case — directory absent: if the resolved path doesn't exist, skip the dedup scan, print a one-line note (

No existing scripts directory at <path> — proceeding to intent gathering

), and remember to optionally offer to create the directory before Step 5.

When the directory exists:

List files in the scripts directory (top-level only for v1).
For each file, read the top of the file (header comment) and capture the file-name tokens.
Read
```
CLAUDE.md
```
/
```
AGENTS.md
```
for
```
<important if="...">
```
blocks that point at scripts in this directory and capture the trigger phrases.
Fuzzy-match the current intent string against (file-name tokens ∪ header keywords ∪ trigger phrases). A "plausible match" is shared keyword + same area noun (e.g.,
```
auth
```
,
```
health
```
,
```
webhook
```
).
If ≥1 plausible match → use AskUserQuestion with options:
```
Reuse <name> as-is | Extend <name> | Generate new anyway
```
.

Never silently skip dedup on borderline matches — surface and let the user decide. The Extend branch appends a sub-command/flag to the existing script (do not create a new file); document the new flag in the script's header comment and the existing

<important if>

block.

按以下顺序确定脚本目录：

检查
```
CLAUDE.md
```
中是否存在
```

```
标记。若存在，使用该路径。
若仓库根目录存在
```
scripts/
```
，则使用该目录。

使用AskUserQuestion工具提供选项：

scripts/ (推荐) | 自定义路径 | 本次运行跳过目录持久化

。

边缘情况——目录不存在：若解析后的路径不存在，跳过重复项扫描，打印一行提示（

No existing scripts directory at <path> — proceeding to intent gathering

），并记住在步骤5前可选择创建该目录。

当目录存在时：

列出脚本目录中的文件（v1版本仅支持顶层文件）。
针对每个文件，读取文件顶部内容（头部注释）并提取文件名标识。
读取
```
CLAUDE.md
```
/
```
AGENTS.md
```
中指向该目录脚本的
```
<important if="...">
```
代码块，并提取触发语句。
将当前意图字符串与（文件名标识 ∪ 头部关键字 ∪ 触发语句）进行模糊匹配。“合理匹配”指存在共享关键字+同一领域名词（例如：
```
auth
```
、
```
health
```
、
```
webhook
```
）。
若存在≥1个合理匹配 → 使用AskUserQuestion工具提供选项：
```
直接复用<name> | 扩展<name> | 仍生成新脚本
```
。

对于边界匹配情况，切勿静默跳过重复项排查——需告知用户并让其决定。扩展分支会在现有脚本中添加子命令/标志（不创建新文件）；在脚本头部注释及现有

<important if>

代码块中记录新标志。

Step 3: Gather Intent

步骤3：收集意图信息

Both modes converge on the same internal intent structure:

{ what, success_signal, failure_signal, inputs, env, side_effects }

Forward mode — use AskUserQuestion (one or two questions, not five):

Question	Options
"What are we validating, and what's the success signal?"	[Free text — collect what + success signal in one answer]
"Any required env vars, inputs, or side-effects to flag (e.g., writes to prod, costs money)?"	[Free text — optional; skip if forward intent already specified them]

Retrospective mode — present the summary from Step 1 and use AskUserQuestion with:

That's the flow | Close but fix X | Start over

. On Close but fix X, ask for the correction inline; on Start over, fall through to forward-mode Q&A.

Persist the resolved intent in working memory (do not write to disk yet).

两种模式最终都会收敛到相同的内部意图结构：

{ what, success_signal, failure_signal, inputs, env, side_effects }

。

前瞻式模式——使用AskUserQuestion工具（1-2个问题，而非5个）：

问题	选项
“我们要验证什么，成功信号是什么？”	[自由文本——在一个回答中收集验证内容+成功信号]
“是否需要标记任何必需的环境变量、输入或副作用（例如：写入生产环境、产生费用）？”	[自由文本——可选；若前瞻意图已指定则跳过]

回顾式模式——展示步骤1的总结内容，并使用AskUserQuestion工具提供选项：

这就是流程 | 接近但需要修正X | 重新开始

。若选择接近但需要修正X，则在线询问修正内容；若选择重新开始，则进入前瞻式模式问答环节。

将解析后的意图信息保存在工作内存中（暂不写入磁盘）。

Step 4: Detect Language

步骤4：检测语言

Priority order — first match wins, with override paths:

TypeScript —
```
package.json
```
+
```
tsconfig.json
```
exist.
- Bun if
```
bun.lock
```
  or
```
bunfig.toml
```
  is present.
- else tsx if
```
tsx
```
  appears in
```
package.json
```
  devDependencies.
- else compiled Node (note in script header: requires
```
tsc
```
  build).
Python —
```
pyproject.toml
```
or
```
uv.lock
```
or
```
requirements.txt
```
exists.
- uv if
```
uv.lock
```
  exists or
```
pyproject.toml
```
  has
```
[tool.uv]
```
  configured (sets
```
{{UV_METADATA}}
```
  ).
- else vanilla python3 (
```
{{UV_METADATA}}
```
  substituted with empty string).
Both TS and Python detected — count source files in
```
src/
```
/top-level and ask AskUserQuestion tiebreaker with the dominant one Recommended.
```
Cargo.toml
```
/
```
go.mod
```
only → fall back to bash (note: TS/Python/Bash only in v1).
Nothing matched → bash.

Task-driven override: if the gathered intent is clearly shell-y ("verify three docker containers respond", "tail this log file for an error"), propose bash even in a TS/Python project.

Confirm via AskUserQuestion with the detected language as the first option (Recommended). Skip in Autopilot.

优先级顺序——首个匹配项生效，同时支持覆盖路径：

TypeScript — 存在
```
package.json
```
+
```
tsconfig.json
```
。
- 若存在
```
bun.lock
```
  或
```
bunfig.toml
```
  ，则使用Bun。
- 否则，若
```
package.json
```
  的devDependencies中包含
```
tsx
```
  ，则使用tsx。
- 否则使用编译后的Node（在脚本头部注明：需要
```
tsc
```
  构建）。
Python — 存在
```
pyproject.toml
```
、
```
uv.lock
```
或
```
requirements.txt
```
。
- 若存在
```
uv.lock
```
  或
```
pyproject.toml
```
  配置了
```
[tool.uv]
```
  ，则使用uv（设置
```
{{UV_METADATA}}
```
  ）。
- 否则使用原生python3（
```
{{UV_METADATA}}
```
  替换为空字符串）。
同时检测到TS和Python — 统计
```
src/
```
/顶层目录中的源文件数量，使用AskUserQuestion工具进行决胜，推荐使用占比更高的语言。
仅存在
```
Cargo.toml
```
/
```
go.mod
```
→ 回退到bash（注意：v1版本仅支持TS/Python/Bash）。
无匹配项 → bash。

任务驱动覆盖：若收集到的意图明显偏向shell操作（“验证三个docker容器响应”、“跟踪此日志文件查找错误”），即使在TS/Python项目中也建议使用bash。

通过AskUserQuestion工具确认，将检测到的语言作为第一个选项（推荐）。Autopilot模式下可跳过确认。

Step 5: Draft the Script

步骤5：起草脚本

Pick the template:

cc-plugin/base/skills/script-builder/templates/{typescript.ts.tmpl|python.py.tmpl|bash.sh.tmpl}

Resolve substitution markers from gathered intent:
- ```
{{SCRIPT_NAME}}
```
  ← proposed file-name stem (see naming table).
- ```
{{WHAT}}
```
  /
```
{{WHEN}}
```
  /
```
{{ENV}}
```
  /
```
{{EXAMPLE}}
```
  ← intent fields.
- ```
{{UV_METADATA}}
```
  ← per Step 4.
Generate
{{TEST_BODY}}
from the intent. Keep it minimal: a single concrete probe + assertion, not a battery. Re-read the templates' README (
```
templates/README.md
```
) for the contract — the body must respect the PASS/FAIL surface. Throw/raise/
```
exit 1
```
on failure; let the template's outer try/trap convert it into the FAIL line.
Propose a file name matching the intent shape — see the prefix table below. Use AskUserQuestion with the proposed name first (Recommended) and
```
custom name
```
as the alternative.

Naming conventions (advisory — skill proposes, user overrides):

Prefix	When	Example
`e2e-*`	End-to-end flows across multiple components	`e2e-auth-flow.ts`
`check-*`	Idempotent single-probe verifications	`check-db-boundary.sh`
`smoke-*`	Minimal-viability post-deploy checks	`smoke-prod-api.ts`
`measure-*`	Performance / size / token measurements	`measure-tool-tokens.ts`
`seed-` / `generate-`	Data seeding or artifact generation (rare for validation)	`seed-api-keys.sh`

If the intent doesn't match any prefix cleanly, propose a free-form name like

validate-<area>.<ext>

Write the file to the resolved scripts directory. Make it executable (
```
chmod +x
```
).

选择模板：

cc-plugin/base/skills/script-builder/templates/{typescript.ts.tmpl|python.py.tmpl|bash.sh.tmpl}

。

从收集到的意图中解析替换标记：
- ```
{{SCRIPT_NAME}}
```
  ← 建议的文件名主干（见命名表）。
- ```
{{WHAT}}
```
  /
```
{{WHEN}}
```
  /
```
{{ENV}}
```
  /
```
{{EXAMPLE}}
```
  ← 意图字段。
- ```
{{UV_METADATA}}
```
  ← 来自步骤4。
根据意图生成
{{TEST_BODY}}
。保持极简：单个具体探测+断言，而非一组测试。重新阅读模板的README（
```
templates/README.md
```
）以遵循约定——主体必须符合PASS/FAIL输出要求。失败时抛出/触发/
```
exit 1
```
；由模板的外层try/trap将其转换为FAIL行。
建议文件名以匹配意图类型——见下方前缀表。使用AskUserQuestion工具，将建议的文件名作为第一个选项（推荐），并提供
```
自定义名称
```
作为替代选项。

命名约定（建议性——技能提出建议，用户可覆盖）：

前缀	使用场景	示例
`e2e-*`	跨多个组件的端到端流程	`e2e-auth-flow.ts`
`check-*`	幂等性单探测验证	`check-db-boundary.sh`
`smoke-*`	部署后的最小可行性检查	`smoke-prod-api.ts`
`measure-*`	性能/大小/令牌度量	`measure-tool-tokens.ts`
`seed-` / `generate-`	数据填充或制品生成（验证场景中较少使用）	`seed-api-keys.sh`

若意图与任何前缀均不匹配，建议使用自由格式名称，例如

validate-<area>.<ext>

。

将文件写入解析后的脚本目录。设置为可执行权限（
```
chmod +x
```
）。

Step 6: Syntax/Type-Check

步骤6：语法/类型检查

Run the appropriate checker:

Language	Checker (in priority order)
TypeScript	`bunx tsc --noEmit <file>` if Bun present, else `npx tsc --noEmit <file>`
Python	`python3 -m py_compile <file>` (always) + `ruff check <file>` if `ruff` is on PATH
Bash	`shellcheck <file>` if available, else `bash -n <file>`

On success: log a single line (

syntax check OK

) and proceed to Step 7.

On failure:

Print the error (≤10 lines, not the full output).
Propose a concrete one-edit fix (the exact
```
Edit
```
you'd apply).
Use AskUserQuestion with
```
Apply fix | Investigate | Stop
```
.
- Apply fix → edit the script and re-run the checker (loop, no hardcoded cap).
- Investigate → drop into discussion with the user; do not auto-apply anything.
- Stop → leave script in place at its path; print the path; do not delete.

运行相应的检查工具：

语言	检查工具（优先级顺序）
TypeScript	若存在Bun则使用 `bunx tsc --noEmit <file>` ，否则使用 `npx tsc --noEmit <file>`
Python	始终使用 `python3 -m py_compile <file>` + 若PATH中存在 `ruff` 则使用 `ruff check <file>`
Bash	若可用则使用 `shellcheck <file>` ，否则使用 `bash -n <file>`

检查成功：记录单行日志（

syntax check OK

）并进入步骤7。

检查失败：

打印错误信息（≤10行，而非完整输出）。
提出具体的单次修复方案（你将执行的精确
```
Edit
```
操作）。
使用AskUserQuestion工具提供选项：
```
应用修复 | 排查问题 | 停止
```
。
- 应用修复 → 编辑脚本并重新运行检查工具（循环，无硬编码上限）。
- 排查问题 → 与用户展开讨论；不自动应用任何修复。
- 停止 → 将脚本保留在当前路径；打印路径；不删除。

Step 7: Document the Script

步骤7：生成脚本文档

Auto-edit the target project's

CLAUDE.md

and/or

AGENTS.md

so future agents discover this script when the matching intent recurs.

Block template (the literal markdown the skill emits):

markdown

<important if="[TRIGGER: e.g., you are testing the auth flow]">

自动编辑目标项目的

CLAUDE.md

和/或

AGENTS.md

，以便后续Agent在遇到匹配意图时能发现该脚本。

代码块模板（技能生成的原始markdown内容）：

markdown

<important if="[TRIGGER: e.g., you are testing the auth flow]">

[Area] validation

Run

scripts/<name>

to [one-liner]. Requires [env/deps]. Example:

<cmd>

. Full log at

/tmp/<name>-*.log

Generated/maintained via

/script-builder

</important> ```

Behavior:

Target file selection: edit
```
CLAUDE.md
```
and
```
AGENTS.md
```
if both exist; edit only what exists. Never create either file from scratch — if neither exists, print a one-line note (
```
No CLAUDE.md or AGENTS.md found — script generated but not documented
```
) and skip this step.
Placement heuristic: search the file for the first heading matching
```
Test|Testing|Validation|Scripts
```
(case-insensitive). If found, append the new block within/after that section. Otherwise, append a new
```
## Scripts for testing & validation
```
section near the end of the file but before any heading matching
```
License|Acknowledg|Maintain|Contributors
```
.
Idempotency: if a block referencing
```
scripts/<name>
```
already exists (i.e., a prior
```
/script-builder
```
run for the same script name), update it in place — replace the entire
```
<important if=...>...</important>
```
block, do not append a duplicate.
Scripts-dir marker: if Step 2 resolved the scripts directory by user choice (not from an existing marker), insert
```

```
near the top of
```
CLAUDE.md
```
(after the title) so subsequent runs are silent. Skip if the marker already exists.
Show the diff: run the equivalent of
```
git diff CLAUDE.md AGENTS.md
```
and print a 5-line summary of what changed. Never auto-stage — the user commits.

Run

scripts/<name>

to [one-liner]. Requires [env/deps]. Example:

<cmd>

. Full log at

/tmp/<name>-*.log

Generated/maintained via

/script-builder

</important> ```

行为规则：

目标文件选择：若
```
CLAUDE.md
```
和
```
AGENTS.md
```
均存在则编辑两者；仅编辑存在的文件。切勿从头创建任一文件——若两者均不存在，打印一行提示（
```
No CLAUDE.md or AGENTS.md found — script generated but not documented
```
）并跳过此步骤。
放置规则：在文件中查找首个匹配
```
Test|Testing|Validation|Scripts
```
的标题（不区分大小写）。若找到，在该章节内/后添加新代码块。否则，在文件末尾附近添加新的
```
## Scripts for testing & validation
```
章节，但要在任何匹配
```
License|Acknowledg|Maintain|Contributors
```
的标题之前。
幂等性：若已存在引用
```
scripts/<name>
```
的代码块（即之前通过
```
/script-builder
```
生成过同名脚本），则就地更新——替换整个
```
<important if=...>...</important>
```
代码块，不添加重复内容。
脚本目录标记：若步骤2通过用户选择确定了脚本目录（而非来自现有标记），则在
```
CLAUDE.md
```
顶部（标题后）插入
```

```
，以便后续运行无需再询问。若标记已存在则跳过。
展示差异：运行等效于
```
git diff CLAUDE.md AGENTS.md
```
的命令，并打印5行变更摘要。切勿自动暂存——由用户提交。

Step 8: Offer Escalation

步骤8：提供升级选项

After the doc edit, decide whether to proceed to the run-and-iterate tier.

Autonomy	Behavior
Autopilot	Auto-escalate to Step 9 unless the intent flagged side-effects (writes to prod, sends real money, mutates a shared resource). On flagged side-effects, fall through to Critical behavior.
Critical (Default)	Use AskUserQuestion: `Run it now to confirm it works
Verbose	Same as Critical, plus offer the proposed run command for review before executing.

If the user picks "I'll run it myself later" or "Just generate, don't run" → skip directly to Step 10.

完成文档编辑后，决定是否进入运行并迭代层级。

自主模式	行为
Autopilot	自动升级至步骤9，除非意图标记了副作用（写入生产环境、产生实际费用、修改共享资源）。若标记了副作用，则遵循Critical模式的行为。
Critical（默认）	使用AskUserQuestion工具：`现在运行以确认可用
Verbose	与Critical模式相同，额外提供建议的运行命令供用户审核后再执行。

若用户选择“我稍后自行运行”或“仅生成脚本，不运行” → 直接跳至步骤10。

Step 9: Iterate on Failures (Escalated Tier Only)

步骤9：失败迭代（仅升级层级）

A bounded-by-the-human loop. Never auto-apply a fix outside Autopilot.

Run the script with the proposed example invocation (no
```
--verbose
```
, no
```
--json
```
). Capture exit code and
```
tail -n 40
```
of the
```
/tmp
```
log.
If exit code 0 → report PASS (echo the script's PASS line) and proceed to Step 10.
If exit code non-zero:
- Summarize the failure in 1–3 lines: error class (timeout / 4xx / 5xx / assertion / dependency-missing / etc.) + likely cause (grep the log for known signatures:
```
ECONNREFUSED
```
  ,
```
Traceback
```
  ,
```
non-zero exit
```
  ,
```
command not found
```
  , etc.).
- Propose a concrete diff — the exact
```
Edit
```
  you would apply to the script. Show old → new.
- Use AskUserQuestion:
```
Apply fix | Investigate differently | Stop
```
  .
  - Apply fix → edit the script, log the change, loop back to (1).
  - Investigate differently → drop into discussion; do not auto-apply.
  - Stop → leave the script in place, print its path; do not revert.

No hardcoded retry cap — the human is the implicit bound.

Side-effect flag: if the intent declared side-effects (Step 3) and Autopilot is active, surface a one-line

WARNING: this script <does X> against <target>

before the first run and require explicit confirmation via AskUserQuestion even in Autopilot mode.

由人工控制的循环。Autopilot模式外切勿自动应用修复。

运行脚本，使用建议的示例调用方式（不使用
```
--verbose
```
或
```
--json
```
）。捕获退出码及
```
/tmp
```
日志的
```
tail -n 40
```
内容。
若退出码为0 → 报告PASS（回显脚本的PASS行）并进入步骤10。
若退出码非0：
- 用1-3行总结失败情况：错误类型（超时/4xx/5xx/断言/依赖缺失/等）+ 可能原因（在日志中查找已知特征：
```
ECONNREFUSED
```
  、
```
Traceback
```
  、
```
non-zero exit
```
  、
```
command not found
```
  等）。
- 提出具体差异——你将对脚本执行的精确
```
Edit
```
  操作。展示旧代码→新代码。
- 使用AskUserQuestion工具提供选项：
```
应用修复 | 换种方式排查 | 停止
```
  。
  - 应用修复 → 编辑脚本，记录变更，回到(1)循环。
  - 换种方式排查 → 展开讨论；不自动应用任何修复。
  - 停止 → 将脚本保留在当前路径，打印路径；不回滚。

无硬编码重试上限——人工操作是隐含的边界。

副作用标记：若步骤3中意图声明了副作用且处于Autopilot模式，在首次运行前展示一行警告

WARNING: this script <does X> against <target>

，并即使在Autopilot模式下也需通过AskUserQuestion工具获得明确确认。

Step 10: Handoff

步骤10：移交

How the skill exits depends on how it was invoked:

Invoked as a sub-skill (from

planning

qa

verifying

): Return control to the parent skill with a structured summary:

{ script_path, status: "pass"|"fail"|"unrun", log_path?, doc_files_edited: [...] }

Invoked directly (

/script-builder

): Use AskUserQuestion:

Run it with /qa | Run /verify-plan | Commit the script and doc changes | Done

Run with /qa → invoke
```
desplega:qa
```
with the script path as the source.
Run /verify-plan → invoke
```
desplega:verifying
```
if a plan path is in current context.
Commit → propose a commit message (
```
feat(scripts): add scripts/<name> for <area> validation
```
) and stage only the generated script + the CLAUDE.md/AGENTS.md edits. Do not auto-commit; show the proposed
```
git add
```
and
```
git commit
```
commands and require user confirmation.
Done → print the script path + log path (if escalation ran) and exit.

Abort path (Stop selected at any earlier gate): leave the generated script in place, leave any CLAUDE.md/AGENTS.md edit in place if Step 7 ran, and print a one-liner:

Aborted. Script: <path>. Doc edits: <files or "none">. Re-run /script-builder or git checkout to discard.

Do not

git restore

on the user's behalf.

技能的退出方式取决于调用方式：

作为子技能调用（来自

planning

、

qa

、

verifying

）：向父技能返回结构化摘要：

{ script_path, status: "pass"|"fail"|"unrun", log_path?, doc_files_edited: [...] }

。

直接调用（

/script-builder

）：使用AskUserQuestion工具：

通过/qa运行 | 运行/verify-plan | 提交脚本及文档变更 | 完成

。

通过/qa运行 → 调用
```
desplega:qa
```
并传入脚本路径作为源。
运行/verify-plan → 若当前上下文存在计划路径，则调用
```
desplega:verifying
```
。
提交 → 建议提交信息（
```
feat(scripts): add scripts/<name> for <area> validation
```
），仅暂存生成的脚本及CLAUDE.md/AGENTS.md的编辑内容。不自动提交；展示建议的
```
git add
```
和
```
git commit
```
命令并需用户确认。
完成 → 打印脚本路径+日志路径（若已升级运行）并退出。

中止路径（在任一早期环节选择停止）：保留生成的脚本，若已执行步骤7则保留CLAUDE.md/AGENTS.md的编辑内容，并打印一行信息：

Aborted. Script: <path>. Doc edits: <files or "none">. Re-run /script-builder or git checkout to discard.

切勿代表用户执行

git restore

操作。

Learning Capture

学习捕获

OPTIONAL SUB-SKILL: If significant insights, patterns, gotchas, or decisions emerged during this workflow, consider using

desplega:learning

to capture them via

/learning capture

. Focus on learnings that would help someone else in a future session.

OPTIONAL SUB-SKILL: 若在工作流中获得重要见解、模式、注意事项或决策，可考虑使用

desplega:learning

通过

/learning capture

进行记录。重点记录能帮助未来会话中其他人的学习内容。