step-by-step

GG → Step by Step → Workflow

概述

使用此技能，将任务列表、计划清单、研究部署流程或手动验证矩阵转换为一次仅执行一个步骤的工作流。它会先验证可验证的内容，明确告知用户当前要做什么，提供可选的帮助和自动化路径，将工作状态保存到带时间戳的会话文件夹中，并且只有在当前步骤解决后才会进入下一步。

何时使用此技能

在以下情况触发：

• 任务同时包含 Agent 工作，以及由用户执行的手动操作或验证。
• 执行过程需要在各步骤之间由人在环确认。
• 计划、研究或任务包含按顺序执行的部署、设置或验证清单。
• 用户明确要求逐步指导，或询问接下来该做什么。

在以下情况跳过：

• Agent 无需用户参与即可自主完成整个任务。
• 用户希望一次性查看完整清单，而不是以交互方式获得指导。
• 无法识别或安全创建有序步骤队列。

常见误解

#	误解	修正	关键概念
1	Agent 应一次性展示所有步骤，让用户了解完整计划。	每次只展示一个当前步骤；完整队列可在会话产物中查看。	单个当前步骤
2	如果某个步骤看起来很简单，Agent 可以在没有证据的情况下将其标记为已解决。	每次解决步骤都需要提供与该步骤验证方法相符的证据。	证据门控
3	如果对话上下文较短，会话文件夹就不是必需的。	始终初始化会话文件夹，并将状态保存到带时间戳的文件夹中；这样可避免交接时丢失上下文。	持久化
4	可选项只是出于礼貌的建议，可以省略。	每个当前步骤说明都必须包含 AUTOMATION_OPTIONS、HELP_OPTIONS 和 CONTROL_OPTIONS。	可选项
5	如果用户说某个步骤已完成，Agent 就应立即进入下一步。	进入下一步前，应通过仓库状态、命令输出或明确证明重新检查该步骤是否已解决。	验证后再推进
6	所有步骤都可以自动化。	有些步骤只能由人完成（手动审核、决策、确认）。	仅限人工的步骤
7	步骤队列是静态的。	依赖关系发生变化或步骤拆分时，重新规范化队列。	动态队列
8	预检是可选的。	提示用户之前，始终先运行预检验证。	预检验证

快速决策指南

场景	使用此技能	改用
执行前在多个选项中做选择	否	decisions/SKILL.md
执行完全可自动化的批处理	否	直接由 Agent 执行
指导手动部署或设置清单	是	--
继续执行已完成研究的验证清单	是	研究本身使用 study/SKILL.md
为外部任务跟踪工具跟踪清单项	是	保留本地完成记录，并返回简洁的交接摘要
制定包含需要指导的手动步骤的计划	是	计划本身使用 plan/SKILL.md

步骤质量检查清单

呈现任何活动步骤前，请使用此检查清单。每一项都是一道关卡——满足所有必需项后，该步骤才算准备就绪。

#	检查项	重要性	关卡
1	队列已规范化 — 有序步骤队列包含 STEP_ID 和状态	支持单一活动步骤	步骤前
2	会话文件夹已初始化 — .tmp/step-by-step/ 中有带时间戳的文件夹	支持持久化	步骤前
3	已确定下一步 — 优先级最高的未解决步骤	防止跳过步骤	步骤前
4	已运行预检 — 已完成 Agent 可验证的检查	减轻用户负担	步骤前
5	已区分责任方 — 清楚区分 Agent 与用户的操作	防止混淆	起草时
6	标题简洁 — 步骤标题是一个清晰的句子	便于快速浏览	起草时
7	已列出前置条件 — 明确列出依赖项	防止顺序错误	起草时
8	已说明验证方法 — 明确解决步骤所需的证据	支持验证	起草时
9	已提供可选选项 — 包含 AUTOMATION/HELP/CONTROL 选项	赋予用户自主权	起草时
10	解决标准明确 — 明确说明何为“完成”	防止重新开启	收尾时
11	已保持持久化 — 每次变更后保存状态	支持恢复	收尾时
12	交接已就绪 — 已准备好用于技能转换的输出	支持协作	收尾时

质量等级

等级	标准	适用情形
最低	第 1–3、6、10 项	简单的单步骤任务
标准	第 1–8、10–11 项	包含人工操作的多步骤工作流
完整	全部 12 项	需要跨技能协作的复杂部署

步骤前验证

呈现活动步骤前，请验证：

□ Step queue normalized with STEP_IDs and positions
□ Session folder initialized in .tmp/step-by-step/
□ Next unresolved step identified
□ Preflight checks completed (agent-verifiable items)
□ Agent vs user actions separated
□ Title is concise (< 60 chars)
□ Prerequisites listed with dependencies
□ Verification method stated with exact evidence
□ Chooseable options included (AUTOMATION/HELP/CONTROL)
□ Resolution criteria clear
□ State will be persisted after this step

步骤一致性验证器

呈现步骤前，请运行以下一致性检查。任何一项检查未通过，都必须先修正步骤再呈现。

一致性检查矩阵

检查项	验证内容	修正方法
步骤与前置条件	此步骤的前置条件均已解决	重新排序队列
步骤与验证	验证方法确实能证明任务已完成	完善验证方法
步骤与选项	选项与此步骤的操作相关	更新选项
步骤与交接	如需进行技能转换，交接输出已就绪	准备输出
队列与依赖项	依赖项符合实际前置条件链	重新规范化

危险信号（绝不可呈现）

存在以下任一情况的步骤，必须先修正再呈现：

• 步骤没有验证方法
• 步骤的前置条件无法解决
• 步骤没有可选选项
• 会话文件夹尚未初始化
• 将 Agent 的操作说成只能由用户执行
• 将用户的操作说成只能由 Agent 执行

不可妥协的政策

1. 呈现第一个活动步骤前，将每项任务规范化为明确的有序步骤队列。
2. 每次只呈现一个活动步骤。
3. 每个步骤前都要运行预检；Agent 能直接验证的内容，绝不可交由用户验证。
4. 每个步骤说明中都要区分 Agent 可执行的工作与只能由用户执行的操作。
5. 每份活动步骤说明都必须遵循 references/step-presentation-contract.md，并提供可选的自动化、帮助和控制选项；既要以打印出的令牌形式呈现，也要在该工具可用时使用 Harness 的“询问用户”选项器（chooseable-options/references/ask-user-harness.md）。
6. 只有在证据符合验证方法要求后，才能将步骤标记为已解决；若证据不完整，须明确说明缺少什么，并保持步骤处于活动状态。
7. 第一步之前，先初始化带时间戳的会话文件夹；每次状态变更后都要持久化保存状态，并保留队列，直至所有步骤均已解决、延期或阻塞。

会话持久化

每次引导式运行都会在 .tmp/step-by-step/YYYY-MM-DD-HHmmss-<session-slug>/ 下创建一个被 git 忽略的会话文件夹。使用一个 根据任务标题或清单主题生成的简短 slug。按照 references/session-artifact-contract.md 存储工件。

必须持久化的最低限度输出：规范化队列快照、每个步骤的当前状态、 活动步骤数据包、解决证据摘要以及最终会话摘要。

步骤队列规范化

按以下优先顺序，从最佳可用来源规范化步骤队列：

1. 用户明确提供的清单。
2. 活动的 .plans/... 清单或执行部分。
3. 活动的学习部署或验证列表。
4. 活动的外部任务跟踪器清单或手动跟进部分。
5. 根据当前对话创建的仅限本会话使用的备用列表。

使用以下信息规范化每个步骤：

• STEP_ID
• 队列位置
• 易于理解的标题
• 负责人（user、agent 或 shared）
• 前置条件
• 验证方法
• 可接受的完成证据
• Agent 可提供的自动化
• 当前状态（pending、active、resolved、deferred、blocked）

如果上游工件已包含排序，除非依赖关系冲突迫使重新排序，否则应保留原顺序；如果确需调整， 请在继续之前说明原因。

单步交互循环

1. 构建或载入有序步骤队列。
2. 初始化带时间戳的 .tmp/ 会话文件夹，并持久化初始队列快照。
3. 找出下一个尚未解决的步骤。
4. 在提示用户之前运行预检并收集本地证据。
5. 使用 references/step-presentation-contract.md 中的格式呈现活动步骤数据包。仅当该契约有要求时，才包含 STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION。
6. 持久化活动步骤数据包和当前会话状态。
7. 如果用户选择自动化选项，先执行安全的 Agent 侧工作。
8. 等待用户提供证据、确认或后续问题。
9. 根据仓库状态、命令输出、屏幕截图、日志或用户明确提供的证明，重新检查是否已解决。
10. 将更新后的状态持久化到会话文件夹；如果存在活动计划、学习项目或任务工件，也同步更新其中的状态。
11. 立即转到下一个尚未解决的步骤；如果当前步骤仍未完成，则继续处理该步骤。
12. 队列已处理完毕或无法继续时，以简短摘要说明已完成或受阻状态。

可接受的回复模式

用户进行以下操作时，当前步骤仍保持活动状态：

• 选择一个选项标记。
• 请求澄清。
• 要求提供更多自动化。
• 粘贴证据或命令输出。
• 表示步骤已完成。
• 表示步骤受阻。
• 要求将步骤拆分成更小的子步骤。

接受原生选择器选项、自然语言回复和明确的选择器标记。如果用户的回复含糊不清， 不要推进；重述当前活动步骤，并仅询问缺失的澄清信息。

故障排查

症状	可能原因	修复方法
用户被队列压得喘不过气	显示的步骤太多或标题不清晰	使用更短的标题和更严格的依赖顺序重新规范化队列。
步骤反复重新打开	验证方法过于含糊或证据不足	完善验证方法，在 Resolution Check 中明确列出具体证据。
会话状态似乎丢失	状态更改后未持久化	检查 .tmp/step-by-step/ 中最新的会话文件夹，并对照 queue.json 核对 session-state.json。
用户想跳过阻塞步骤	该步骤阻塞了队列中的剩余步骤	将该步骤标记为 blocked，说明对下游步骤的影响，并保留队列。
跨技能交接时丢失步骤上下文	未传递会话目录路径	交接输出中始终包含会话目录路径、currentStepId 和 queue.json。

常见陷阱

1. 忘记初始化会话文件夹。 在呈现第一个待执行步骤之前，务必创建带时间戳的文件夹。参见 references/session-artifact-contract.md。
2. 混淆仅限 Agent 和仅限用户执行的操作。 将 Agent 可以执行的操作与用户必须执行的操作分开。用户操作放在 What You Need To Do 中，Agent 操作放在 What I Can Do For You 中。
3. 对含糊的回复继续推进。 如果用户的回复不明确，请重述当前步骤并请求澄清，不要猜测。
4. 状态变更后未持久化。 在队列规范化后、每次呈现当前步骤说明后、每次证据变更后，以及移交任何技能之前，都要持久化状态。
5. 将子步骤作为顶层步骤呈现。 如果一个步骤被拆分，请用新增的子步骤更新规范化队列并重新编号，不要临时呈现。
6. 省略前置条件摘要。 每份步骤说明都必须包含前置条件摘要，让用户了解依赖关系。

跨技能协调

• plan/SKILL.md — 当计划中包含手动执行、设置或验证步骤，且需要交互式引导而非一次性列出时使用。
• study/SKILL.md — 当已完成的研究需要移交部署、复现或验证清单时使用。
• decisions/SKILL.md — 在多个选项中做出选择时使用 decisions；确定方向后，如果用户需要引导式执行，则返回此处。
• chooseable-options/SKILL.md — 负责呈现打印令牌和原生的 Ask User 选项。
• research-online/SKILL.md — 当解决当前步骤前需要核查最新外部文档或产品行为时使用。
• instrumentation/SKILL.md — 仅当 references/step-presentation-contract.md 有规定时，才提供 STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION。选择该选项并不会解决该步骤。

移交输出

移交给上游工作流技能

• 含步骤状态的规范化队列。
• 当前待执行的 STEP_ID。
• 已解决步骤收集到的证据。
• 任何未解决的当前步骤的阻碍摘要。
• 分步会话目录路径。
• 建议的下一步或明确的阻塞状态。

移交给 plan/SKILL.md

• 从计划中提取的手动步骤队列。
• 已完成和剩余步骤。
• 交互循环期间产生的验证证据。
• 应重新添加到计划中作为阻碍或后续事项的任何步骤。

移交给 instrumentation/SKILL.md

仅当操作员选择 STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION 后：

• STEP_ID
• 会话目录
• 该步骤要验证的行为
• 一次运行必须回答的问题

在收到证据之前，该步骤保持待执行状态。此移交不会解决该步骤。

在明确请求时移交给下游任务跟踪

• 跟踪器 URL/ID（如有）。
• 会话期间完成的清单项目。
• 值得持久化到任务正文中的证据或输出片段。
• 分步会话目录路径。
• 必须在任务跟踪中保持可见的延期或阻塞步骤。

按任务类型加载参考文件

对于诊断请求，在加载任何参考文件之前，先检查 .tmp/step-by-step/ 中最新的会话文件夹。

任务类型	加载这些文件	跳过
设置或恢复会话	session-artifact-contract.md	step-presentation-contract.md
呈现或审查步骤说明	step-presentation-contract.md	session-artifact-contract.md
调试持久化或恢复问题	session-artifact-contract.md	step-presentation-contract.md
优化步骤结构或选项	step-presentation-contract.md	session-artifact-contract.md

仅加载任务所需的部分。

本地语料库布局

references/ 文件夹是扁平结构（没有子文件夹），包含 2 个文件：

文件	描述
session-artifact-contract.md	必需的 .tmp/ 会话文件夹布局、队列快照和步骤记录的文件名、持久化时机规则，以及恢复规则。
step-presentation-contract.md	活动步骤数据包的确切结构、必需的可选择选项组，以及解决情况检查规则。

步骤生成模板

呈现活动步骤时使用此模板。为每个部分填写具体内容。

活动步骤数据包结构

# Step: [STEP_ID] - [Concise title]
**Status:** active
**Quality Tier:** [Minimal | Standard | Full]
**Owner:** [user | agent | shared]
**Session:** [path to session folder]

## What This Step Does
[Brief description of what needs to happen]

## Prerequisites
- [ ] [Prerequisite step ID]: [What must be completed first]
- [ ] [Artifact path]: [Required artifact or context]

## What I Can Do For You
[Any agent-verifiable checks or automation]

## What You Need To Do
[Specific manual action with clear instructions]

## Verification Method
[How to verify this step is complete]
- Required evidence: [Specific output, screenshot, or confirmation]
- Agent will verify: [What the agent can check automatically]

## AUTOMATION_OPTIONS
- `STEP_[ID]_AUTOMATE_[ACTION]`: [Description of automation]

## HELP_OPTIONS
- `STEP_[ID]_HELP_[TOPIC]`: [Description of help topic]

## CONTROL_OPTIONS
- `STEP_[ID]_SKIP`: Skip this step
- `STEP_[ID]_DEFER`: Defer to later
- `STEP_[ID]_SPLIT`: Split into substeps

## Next Step
**Following:** [Next STEP_ID or "Queue exhausted"]

STEP_[ID]_AUTOMATE_IMPROVE_INSTRUMENTATION 并非每个数据包都必需。仅当 references/step-presentation-contract.md 指出该验证属于项目行为，且预检未发现命令或页面时，才将其包含在内。

步骤规范化模板

{
  "STEP_ID": "STEP_001",
  "title": "Concise step title",
  "owner": "user|agent|shared",
  "prerequisites": ["STEP_000"],
  "verificationMethod": "How to verify completion",
  "acceptableEvidence": ["output", "screenshot", "confirmation"],
  "status": "pending|active|resolved|deferred|blocked",
  "automations": ["what the agent can offer"],
  "options": {
    "automation": ["STEP_001_AUTOMATE_*"],
    "help": ["STEP_001_HELP_*"],
    "control": ["STEP_001_SKIP", "STEP_001_DEFER", "STEP_001_SPLIT"]
  }
}

快捷命令

# Initialize a step-by-step session
# Runner alternatives: bunx tsx / pnpm dlx tsx / deno run -A npm:tsx / node --import tsx / yarn dlx tsx
npx tsx .agents/skills/step-by-step/scripts/init-session.ts --name <session-name> --source <source-plan-or-study>

# Check step completeness (12-item checklist)
npx tsx .agents/skills/step-by-step/scripts/check-step-completeness.ts --step <step-id>
npx tsx .agents/skills/step-by-step/scripts/check-step-completeness.ts --session <session-dir>

# Normalize a step queue from an artifact
npx tsx .agents/skills/step-by-step/scripts/normalize-queue.ts --source <artifact-path>

# Verify step resolution
npx tsx .agents/skills/step-by-step/scripts/verify-step.ts --step <step-id> --evidence <evidence-path>

捆绑资源

文件	描述
assets/icon-small.svg	用于 IDE Agent 列表的小型技能图标。
assets/icon-large.png	用于 IDE Agent 列表的大型技能图标。

---

指导一致性：按照 AGENTS.md 一致地应用仓库指导。如果更新此技能文件，请运行 npm run skills:sync，让 IDE 立即获取新版本。