workflow-skill-creator

工作流转技能提炼器

将已完成的工作流转化为可复用的 Agent 技能。具体来说，该技能会从已经发生的交互或工作流中提取模式，并将其打包。

注意

**编写任何代码或 SKILL.md 内容之前，必须先完成第 1 阶段（头脑风暴）。**跳过头脑风暴会导致技能过于僵化或过于含糊。头脑风暴对话是此流程中最重要的部分。

第 1 阶段：头脑风暴（必做）

与用户进行多轮往返对话。不要一次性提出所有问题。从下面的问题库中，每轮挑选 2–3 个相关问题，逐步完善理解，并提出后续问题。

第 1 轮：了解工作流

先总结你从工作流中观察到的内容，然后询问：

1. “我对工作流的理解如下：[摘要]。准确吗？你会做哪些调整？”
2. “此工作流的预期输入和输出是什么？”
3. “你预计多久运行一次此工作流？它是周期性任务还是一次性任务？”

第 2 轮：灵活性与错误处理

针对工作流中确定的每个步骤，明确其刚性要求：

1. “对于[步骤 X]，如果主要方案失败（例如 API 宕机或没有结果），Agent 应该：（a）向你寻求指导，（b）自动尝试其他方案，还是（c）直接报错并明确说明失败？”
2. “是否有任何步骤必须采用特定方法（例如必须使用特定数据库），而其他步骤则可以采用任何合理方法？”
3. “技能应静默处理边缘情况，还是将其告知用户？”

第 3 轮：依赖项与资源

提出这些问题前，先检查你已安装的技能中哪些与此工作流有重叠。如果科学工具包中的现有技能涵盖了某个步骤，新技能必须引用该技能——不要提供独立实现的选项。

1. “我注意到此工作流使用了[现有技能 X、技能 Y]所涵盖的功能。新技能会引用这些技能，而不是重新实现相关功能。还有其他工具或技能是你希望我纳入的吗？”
2. “此工作流所用服务是否存在尚未由现有技能涵盖的 API 速率限制，需要我注意？”
3. “是否有可为创建此技能提供重要科学背景的特定文件？例如 API 文档、参考论文、示例数据集或特定领域的笔记。如果有，请分享给我，我会将其内容纳入技能的参考资料。”

第 4 轮：范围与形式

1. “我们的工作流涵盖了 [X, Y, Z]。我应该将这些内容全部提炼到技能中，还是还有其他重要功能需要纳入？ 反过来说，是否应该省略其中某些内容？”
2. 确定技能是否需要代码。如果任何步骤涉及调用 API、处理数据、读写文件或计算结果，技能就需要代码，此时应默认采用 CLI 模式。只有当每个步骤都纯粹涉及推理、协调现有工具，或遵循完全不涉及编程操作的书面协议时，才使用纯文本指令技能。用通俗易懂的语言向用户确认你的判断：
   • 如果需要代码：“其中一些步骤涉及[从 API 获取数据／处理文件／计算结果]，因此我会创建一个助手脚本，供 Agent 运行。脚本会提供 search、fetch、analyze 等简单命令——你无需自己编写任何代码。这样可以吗？”
   • 如果不需要代码：“这个工作流完全是遵循一系列步骤并使用现有工具——不需要编写新代码。我会将其写成一组清晰的指令，供 Agent 遵循。这样可以吗？”
3. 如果将创建助手脚本：“我考虑让脚本提供以下命令：[用通俗易懂的语言描述拟定的命令，例如‘搜索蛋白质’、‘获取结果’、‘比较序列’]。你会想添加或修改什么吗？”
4. “这个技能应该叫什么？建议名称：[suggestion]。”

第 5 轮：测试（可选）

1. “你能提供一个示例查询和预期答案，让我验证技能是否按预期工作吗？例如：‘如果我问[问题]，技能应该给出[答案]。’这是可选项，但有助于我在开发过程中验证技能。”

头脑风暴完成标准

当你能有把握地回答以下所有问题时，即可进入第 2 阶段：

• 工作流的目的和范围是什么？
• 输入和输出是什么？
• 哪些步骤是严格固定的，哪些是灵活的？
• 应参考哪些现有技能？
• 需要哪些新脚本（如果有）？
• 有哪些速率限制？
• 应如何处理错误？
• 工作流是否需要代码？（如果需要 → CLI 模式；如果不需要 → 仅使用指令）
• 技能应安装在哪里？（本地、全局或自定义路径）
• 是否有用于验证的示例查询／答案？

第 2 阶段：技能设计

编写一份设计文档（作为产出物／实施计划），并提交给用户审批。文档必须包括：

1. 技能名称和描述（遵循 YAML frontmatter 规则：名称不超过 64 个字符，使用小写字母和连字符；描述不超过 1024 个字符）。
2. 目录结构，列出所有计划创建的文件和安装位置（本地、全局或自定义路径——参见规则 7）。
3. 所引用的现有技能及各自的理由。
4. 新脚本（如果有），包括拟定的子命令和参数。
5. 对任何现有技能未覆盖的 API 制定速率限制策略。
6. 错误处理策略，按步骤说明。

在继续第 3 阶段之前，等待用户明确批准。

第 3 阶段：实施

指导原则

技能实现的一般指南：

• 使用 uv run，不要使用 python 或 python3。
• 优先使用默认 Python 3 安装自带的标准库（优先使用 urllib）；尽可能避免使用需要额外安装的库。
• 必须在文档中说明并在代码中遵守速率限制。优先采用基于文件锁的速率限制，确保共享同一台机器的并发子 Agent 能共同遵守限制。跨进程安全实现的规范示例，请参阅 Science Skills 套件中的其他技能。
• 技能输出必须少于 500 行，否则应重定向到文件。应以编程方式处理较长的输出文件，提取相关字段。
• 技能名称和 YAML name: 字段建议使用连字符。

规则 1：复用现有技能

如果工作流使用的功能已由现有已安装技能提供，新建的 SKILL.md 必须按名称引用该技能，而不是重新实现。请在 SKILL.md 中加入 Dependencies 部分，列出所需技能，并简要说明各自的用途。

规则 2：为新 API 实施速率限制

对于任何未由现有技能涵盖的 API 交互，生成的 CLI 脚本必须实施速率限制。编写任何速率限制代码前，查阅 API 的官方速率限制指南：先检查用户在构思过程中提供的文档，然后在线搜索该 API 的公开文档。如果找不到已记录的速率限制，则默认每秒 1 个请求。速率限制模式已内置于 CLI 模板 references/cli_script_template.py 中——请参阅 RateLimitError 类和 API 客户端的 _request 方法。

关键要求：

• 使用 time.monotonic() 进行计时（不要使用 time.time()）。
• 根据已记录的速率限制计算延迟。
• 对可恢复的错误（5xx）实施指数退避重试。
• 收到 HTTP 429 时，抛出专用的 RateLimitError。
• 将重试尝试记录到 stderr，以便 Agent 跟踪进度。
• 在错误消息中包含 URL 和速率限制值。
• 对于不可重试的 HTTP 错误（例如 400、403、404），读取响应正文并将其包含在错误消息中，而不只是包含状态码。API 响应正文包含可用于采取行动的详细信息（例如“参数无效”），可帮助 Agent 自行纠正。

规则 3：CLI 脚本模式（需要代码时的默认选择）

这是默认选择。 如果工作流中的任何步骤涉及 API 调用、数据处理、文件 I/O、计算或任何其他编程工作，请使用带有子命令的 argparse 编写多命令 CLI 脚本。遵循 references/cli_script_template.py 中的模板。

关键要求：

• 每个主要工作流步骤都应成为一个子命令。
• 所有子命令都应支持使用 --output 将结果写入文件。
• 使用 json.dump 并设置 indent=2 输出 JSON。
• 打印包含输出文件路径的成功消息。
• 出错时以代码 1 退出。
• 将 --limit 等参数设为必填项（不要设置静默默认值）。这样可强制 Agent 明确指定数值，避免它误以为已获取“全部”结果，实际结果却在不知情的情况下被截断。

规则 4：默认写入文件

所有脚本和工作流必须将输出写入文件，而不是 stdout。stdout 中只能包含简短的状态消息（例如“成功！数据已写入：results.json”）。这点至关重要，因为：

• API 响应可能很大，会在终端输出中被截断。
• 将输出写入文件可节省 token——Agent 只需使用 jp 或 Python 单行命令读取所需字段。
• 大量 stdout 输出会浪费上下文窗口空间。

规则 5：仅指令模式（仅在不需要代码时使用）

仅当工作流完全不需要编程时，才使用此模式——也就是说，每个步骤都只是编排、推理、多技能协调或遵循书面协议。如果任何步骤需要代码（API 调用、数据处理、文件 I/O 等），请改用规则 3 中的 CLI 模式。生成一个包含结构化工作流章节的 SKILL.md：

## Workflow

### 1. Step Name
- Description of what to do
- Which skill to use and how

### 2. Next Step
...

规则 6：SKILL.md 结构

每个生成的 SKILL.md 都必须遵循以下结构：

---
name: {skill-name}
description: >-
  {description}
---

# {Skill Title}

## Overview
{Brief description of what the skill does.}

## Dependencies
{List of required skills, if any.}

## Quick Start
{Minimal example to get started.}

## Utility Scripts (if CLI-based)
{Document each subcommand with examples.}

## Workflow (if instruction-only)
{Numbered steps with clear instructions.}

## Rate Limiting (if applicable)
{Document rate limits and how they are enforced.}

## Common Mistakes
{List 2-3 common pitfalls.}

规则 7：技能安装位置

技能可以本地安装（特定于项目，适用于单个工作区），也可以全局安装（适用于所有项目）。询问用户希望本地安装、全局安装，还是使用自定义安装路径。

按 Agent CLI 列出的技能路径（本地路径相对于项目根目录）：

• Claude Code：本地 .claude/skills/，全局 ~/.claude/skills/
• Codex：本地 .agents/skills/，全局 ~/.agents/skills/
• Antigravity 2.0：本地 .agents/skills/，全局 ~/.gemini/config/skills/
• Gemini CLI：本地 .gemini/skills/，全局 ~/.gemini/skills/
• OpenCode：本地 .opencode/skills/，全局 ~/.config/opencode/skills/

对于其他 CLI，请自行查找本地和全局技能路径。

阶段 4：验证

实现完成后：

1. 手动测试技能：使用自然语言提示词调用 Agent，该提示词应能触发新技能。

2. 如果头脑风暴期间提供了示例查询/回答，请通过该技能运行示例，并确认输出符合预期。