steel-skill-creator

Steel Skill Creator

将重复执行的网页任务转化为 Agent 技能。用户描述任务并提供一组示例输入。你将在真实的 Steel 浏览器中端到端执行两次任务（一次使用示例输入，一次使用变更后的输入），通过 Steel CLI 捕获两次操作轨迹，编写参数化的 SKILL.md，安装该技能，并使用第三组输入进行验证。

用户不会提供会话 ID。你需要自行生成两个会话。

此技能基于的原则

Steel Agent 操作轨迹已经包含了 SKILL.md 所需内容的 80%。其中包含按质量优先级排序的稳定选择器（testId → id → aria → name → CSS）、每个已点击元素的 accessibleNames、页面边界、标记等待点的空闲间隔，以及以 URL 查询字符串和表单输入形式内嵌的参数值。你的主要工作是并排阅读两条操作轨迹，并补上其中尚未包含的部分：目标、参数名称、成功标准，以及用于生产环境回放的恰当 Steel 会话配置（隐身、代理、凭据、配置文件）。

之所以由你自行生成两条操作轨迹，是因为对照同一流程使用不同输入运行两次，就能可靠地提取参数。对应位置上凡是不同的内容都是参数；相同的内容则是不变量。单条操作轨迹无法让你在不猜测的情况下得出这些信息，而让用户录制两次会增加一倍工作量。还是由你来完成更好。

不要试图以编程方式处理所有边缘情况。参考目录会告诉你要查找什么；其余工作就是阅读和编写代码。

前提条件

• 已安装 steel CLI，并完成身份验证，可用于驱动浏览器。
• 已提供 steel-browser 技能——你将使用相同的基本操作（steel browser start、navigate、snapshot、click、fill、wait 等）来驱动两次录制会话。
• 任务描述足够清晰，可以执行。如果描述过于模糊（例如“自动化我的浏览”），请先询问具体需求，再进行其他操作。

工作流

步骤 1 — 收集任务描述和示例输入

你需要向用户收集三项内容：

1. 技能名称 — kebab-case 格式的标识符（例如 flight-price-probe、weekly-traffic-report）。如果用户尚未提供，请根据流程用途提出一个，并请用户确认。
2. 单行目标 — 用用户自己的话说明该技能的用途（“查找给定日期范围内两个机场之间最便宜的直飞航班”）。这将作为生成技能描述的依据。
3. 一组示例输入 — 能完整执行整个流程的具体值。不要只说“搜索航班”；要说“搜索 SPU → FCO，出发日期为 2026-06-13，返程日期为 2026-06-18”。信息要足够具体，让你无需再次询问就能实际执行任务。

如果有任何信息缺失或含糊，只需简洁地询问一次。不要让用户经历冗长的问答。

步骤 2 — 录制前确认安全性

在首次运行任务之前，先考虑可能产生的副作用：

• 只读流程（抓取、搜索、阅读报告、查询价格）→ 使用不同输入安全运行两次。继续执行。
• 有副作用的流程（预订、付款、发送消息、提交会触发电子邮件或收费的表单、创建账户、发布内容）→ 停止并询问。 使用任意输入运行两次可能会产生费用、骚扰他人或留下真实记录。向用户提供以下三个选项：
  1. 两次运行都使用沙盒、测试账户或测试输入。
  2. 只录制一次，接受参数化质量较低的结果（生成的技能必须根据启发式方法而非对比证据来推测部分参数），并在技能描述中明确标注为“单条操作轨迹草稿”。
  3. 放弃在此处自动化，将步骤用通俗文字写成文档，而不是可执行的技能。

绝不要在未告知用户的情况下运行有副作用的流程两次。用户的信任比技能更重要。

第 3 步 — 亲自执行任务，记录轨迹 #1

使用 steel-browser 原语，结合第 1 步中的示例输入，端到端地执行任务。启动会话（根据 references/steel-primitives.md 使用正确的配置），然后导航、点击、等待、提取——使用的模式应与替用户运行 /steel-browser 时完全相同。

沿途截取屏幕截图并生成快照，确认每一步都成功。如果某一步失败，请像处理普通 Steel 会话一样进行调试——不要在状态异常时强行继续。

任务达到成功状态时（数据已提取、表单已提交、确认页面已呈现），停止会话。保存会话 ID——第 5 步会用到。

第 4 步 — 使用变更后的输入重放任务，记录轨迹 #2

选取变更后的输入。针对第 1 步中的每个示例值，选择一个能执行相同流程的合理替代值：

• 日期 → 同月或相邻月份中的另一个日期。
• 搜索词 → 语义不同但格式正确的内容（不同的机场、产品类别或人名）。
• ID → 另一个已知有效的 ID。

目标是不同输入，相同意图。目标轨迹应沿着相同的概念路径执行，以便差异能清晰地体现参数变化。

使用变更后的输入，在一个全新的 Steel 会话中再次运行任务。使用相同配置、相同起始 URL 和相同的逻辑操作顺序。

如果轨迹 #2 与轨迹 #1 不一致——例如遇到轨迹 #1 中没有的登录拦截、遇到 CAPTCHA，或进入结构不同的页面——请停止并调查。查阅 references/steel-primitives.md，判断是否应添加 Steel 会话选项（隐身、代理、CAPTCHA 求解），或者是否需要升级给用户处理。不要掩盖差异。

保存第二个会话 ID。

第 5 步 — 获取两条轨迹

node scripts/fetch_trace.mjs <session-id-1>
node scripts/fetch_trace.mjs <session-id-2>

该脚本会调用 steel --json sessions traces <session-id>，将规范化后的轨迹 JSON 写入临时文件，并打印文件路径。轨迹包含带有 accessibleName、选择器、页面 URL、值字段和时间戳的事件——有关需要查看的内容，请参阅 references/trace-anatomy.md。

第 6 步 — 编写生成的技能

现在你有两份跟踪记录。请将它们放在一起阅读。对应位置的差异是参数；相似之处则是不变量。

按顺序参考以下文档：

• references/trace-anatomy.md — 如何读取每个事件，以及如何对齐两份跟踪记录。
• references/steel-primitives.md — 凭据、配置文件、隐身模式、代理和 CAPTCHA 的决策树。这决定生成的技能如何创建 Steel 会话。
• references/skill-template.md — 要填写的框架。

生成的技能在运行时依赖 steel-browser 技能，不会在行内嵌入 CLI 命令。每个生成的技能都必须包含一个 ## Prerequisites 部分（模板中给出了准确措辞），指引用户运行 curl -fsS https://setup.steel.dev | sh，此命令会安装 steel CLI 和 steel-browser 技能。正文步骤用通俗文字描述意图，并将元素名称设为斜体；执行器会使用 steel-browser 的基本操作，将其转换为 snapshot → click → fill → wait 序列。

生成的技能选择定位器时，按以下优先级：

1. 元素文本或 accessibleName（最稳健，能经受大多数 DOM 改写）。
2. 如果存在，则使用 data-testid。
3. 如果存在且看起来是有意设置的，则使用 id。
4. aria-label 或 name。
5. 最后才使用 CSS 选择器；除非别无选择，否则不要使用 :nth-of-type 链。

将 target.selector 作为可用选择器的依据，但如果可访问名称足够具体，应优先采用易读的语义化步骤。例如，写“点击 Direct only 复选框”，而不是暴露原始选择器。

参数名称应表达其含义，而不是形式。用 depart_date，不要用 param_2。之后使用生成技能的模型不会预先了解这些名称；清晰度很重要。

目标应使用祈使句来写（“查找 {origin} → {destination} 之间 {depart} 至 {return} 的最低直飞往返价格”）。成功标准应说明返回的内容，而不是点击了什么。

第 7 步 — 安装技能

node scripts/install_skill.mjs <skill-name> --skill-md <path-to-generated-SKILL.md>

脚本会写入 ~/.claude/skills/<skill-name>/，并告知你最终路径。默认情况下，生成的技能会安装到系统范围，因此用户可在任何项目中调用它。

第 8 步 — 运行新技能进行验证

选择第三组输入，与第 1 步（示例输入）和第 4 步（变更后的输入）都不同。在新的 Steel 会话中，用这组输入调用刚安装的技能。记录生成的会话 ID，并获取跟踪记录 #3。

第 9 步 — 判断保真度

阅读 references/llm-judge-rubric.md。结合三份跟踪记录、生成的技能源文件，以及你收集的输入和输出，给出判断：

• 跟踪记录 #3 是否达到了与跟踪记录 #1 和 #2 相同类型的成功信号？
• 第三组输入是否顺利替换进 URL 和表单值？
• 额外步骤（Cookie 横幅、模态框）是否得到处理，还是导致流程失败？
• 是否有步骤被跳过？如果有，是否造成影响？

不要运行结构化差异比较。请自行判断。

如果判断结果良好：告知用户技能已安装及其位置，并展示一个带有具体输入的调用示例。

如果判断结果一般：用通俗语言向用户说明诊断结果，并提出修改方案——通常问题出在以下一项：等待时机不当、选择器过于具体、本应拆分为两个的参数被合并，或遗漏了 Steel 会话选项。

决策要点：何时询问用户，何时直接继续

以下情况请询问用户：

• 任务描述过于模糊，以至于你必须自行编造输入（步骤 1）。
• 任务会产生副作用，无法安全地重放两次（步骤 2）。
• 首次运行时，网站触发了登录流程，而 Steel 尚未配置该网站的凭据。将凭据存入保险库前，你需要征得用户同意。
• 步骤 4 中的重放在以下情况下遇到 CAPTCHA：用户没有购买 Steel 付费套餐；或者遇到地理限制，需要使用用户尚未授权的地区。
• 你无法根据两条跟踪记录判断某个操作究竟是有意设置的参数，还是意外噪声（例如，用户是否有意滚动到 437px 的位置，还是只是偶然滚到那里？）。

以下情况无需询问，直接继续：

• 选择选择器——根据优先级列表自行判断。
• 参数命名——先拟定名称；如果用户愿意，之后可以自行更改。
• 设置等待点——空闲间隔和页面切换都是可靠的信号。
• 步骤 4 中选择要更改的输入——选一个合理的值，继续操作。
• 是否在生成的技能中启用 stealth/proxy/CAPTCHA——references/steel-primitives.md 中的决策树给出了明确指引。

注意事项

• 不要使用正则表达式在跟踪记录 JSON 中查找参数。 阅读跟踪记录并分析。对比两条跟踪记录是思维过程，不是字符串比较操作。
• 不要在生成的技能中加入跟踪记录 ID、会话 ID 或时间戳。 这些是本次编译过程产生的内容，不应出现在可复用技能中。
• 不要编写上百行的 SKILL.md。 生成的技能应简洁——正文控制在 40–80 行。Steel 跟踪记录是源代码；SKILL.md 是其抽象概述。
• 不要编造两条跟踪记录中都未出现的步骤。 如果两次录制都没有包含“关闭 Cookie 横幅”，生成的技能就不应假装包含这一步。如果该横幅之后在生产环境中出现，验证环节会发现它。
• 未经用户同意，不要重复执行有副作用的流程。 这一点值得再次强调。

输出

成功运行后，用户将获得：

• 位于 ~/.claude/skills/<skill-name>/ 的新技能。
• 一个可供复制粘贴的示例调用。
• 一条简短的注意事项（例如：“需要先配置 foo.com 的 Steel 凭据；首次使用前运行一次 steel credentials create --origin https://foo.com”）。
• 一条来自验证环节的单行保真度结论。