Back to Details

workflow-skill-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workflow-to-Skill Distiller

工作流转Skill提炼工具

Turns a completed workflow into a reusable agent skill. Specifically, this skill extracts patterns from an interaction or workflow that already happened and packages them.
[!CAUTION] You MUST complete Phase 1 (Brainstorming) before writing any code or SKILL.md content. Skipping brainstorming produces skills that are either too rigid or too vague. The brainstorming conversation is the most important part of this process.
将已完成的工作流转化为可复用的Agent Skill。具体来说，此Skill会从已发生的交互或工作流中提取模式并进行打包。
[!CAUTION] 你必须先完成阶段1（头脑风暴），才能编写任何代码或SKILL.md内容。 跳过头脑风暴会导致Skill要么过于僵化，要么过于模糊。头脑风暴对话是此流程中最重要的部分。

Phase 1: Brainstorming (MANDATORY)

阶段1：头脑风暴（必填）

Have an iterative back-and-forth conversation with the user. Do NOT ask all questions at once. Pick 2-3 relevant questions per round from the bank below, refine your understanding, and ask follow-ups.
与用户进行迭代式的双向对话。不要一次性提出所有问题。从下方问题库中每轮选取2-3个相关问题，完善你的理解，然后提出后续问题。

Round 1: Understand the Workflow

第一轮：理解工作流

Start by summarizing what you observed from the workflow, then ask:
  1. "Here's my understanding of the workflow: [summary]. Is this accurate? What would you change?"
  2. "What are the expected inputs and outputs for this workflow?"
  3. "How often do you expect to run this workflow? Is it recurring or one-off?"
首先总结你从工作流中观察到的内容，然后询问：
  1. "以下是我对该工作流的理解：[总结内容]。是否准确？你有什么修改意见？"
  2. "此工作流的预期输入和输出是什么？"
  3. "你预计多久运行一次这个工作流？是周期性运行还是一次性运行？"

Round 2: Flexibility and Error Handling

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

For each step identified in the workflow, determine its rigidity:
  1. "For [step X], if the primary approach fails (e.g., API down, no results), should the agent: (a) ask you for guidance, (b) try alternative approaches automatically, or (c) fail loudly with an error?"
  2. "Are there any steps where the exact method matters (e.g., must use a specific database), vs. steps where any reasonable approach is fine?"
  3. "Should the skill handle edge cases silently or surface them to the user?"
针对工作流中识别出的每个步骤，确定其僵化程度：
  1. "对于[步骤X]，如果主要方法失败（例如API宕机、无结果返回），Agent应该：(a) 向你寻求指导，(b) 自动尝试替代方法，还是(c) 抛出明确错误并终止？"
  2. "是否存在某些步骤必须使用特定方法（例如必须使用特定数据库），而某些步骤只要是合理方法即可？"
  3. "Skill应该静默处理边缘情况，还是将其告知用户？"

Round 3: Dependencies and Resources

第三轮：依赖项与资源

Before asking these questions, check which of your installed skills overlap with the workflow. If an existing skill from the science bundle covers a step, the new skill MUST reference it — do not offer a self-contained option.
  1. "I noticed the workflow uses functionality covered by [existing skill X, skill Y]. The new skill will reference these rather than reimplementing them. Are there any other tools or skills you'd like me to incorporate?"
  2. "Are there any API rate limits I should be aware of for services used in this workflow that aren't already covered by an existing skill?"
  3. "Are there specific files that provide important scientific context for creating this skill? For example: API documentation, reference papers, example datasets, or domain-specific notes. If so, please share them and I will incorporate their content into the skill's reference materials."
在提出这些问题之前，检查已安装的Skill中有哪些与该工作流重叠。如果Science Bundle中的现有Skill涵盖了某个步骤，新Skill必须引用它——不要提供独立实现的选项。
  1. "我注意到该工作流使用了[现有Skill X、Skill Y]涵盖的功能。新Skill将引用这些Skill而非重新实现。你是否希望我整合其他工具或Skill？"
  2. "对于工作流中使用的、未被现有Skill覆盖的服务，是否有我需要了解的API速率限制？"
  3. "是否有提供创建此Skill所需重要科学背景的特定文件？例如：API文档、参考论文、示例数据集或领域特定笔记。如果有，请分享这些文件，我会将其内容整合到Skill的参考资料中。"

Round 4: Scope and Shape

第四轮：范围与形式

  1. "Our workflow covered [X, Y, Z]. Should I distill all of these into the skill, or is there additional functionality that's important to include? Conversely, should any of these be left out?"
  2. Determine whether the skill needs any code. If any step involves calling an API, processing data, reading/writing files, or computing results, the skill needs code and you should default to the CLI pattern. Only use a text-only instruction skill when every step is purely about reasoning, coordinating existing tools, or following a written protocol with no programmatic work at all. Confirm your assessment with the user in plain language:
    • If code is needed: "Some of these steps involve [fetching data from an API / processing files / computing results], so I'll create a helper script that the agent can run for you. The script will have simple commands like 
      search
      , 
      fetch
      , 
      analyze
      , etc. — you won't need to write any code yourself. Does that sound right?"
    • If no code is needed: "This workflow is entirely about following a set of steps and using existing tools — no new code is needed. I'll write it as a set of clear instructions the agent follows. Does that sound right?"
  3. If a helper script will be created: "I'm thinking the script should have these commands: [proposed commands in plain English, e.g. 'search for proteins', 'fetch results', 'compare sequences']. What would you add or change?"
  4. "What should the skill be called? Proposed name: 
    [suggestion]
    ."
  1. "我们的工作流涵盖了[X、Y、Z]。我应该将所有这些内容提炼到Skill中，还是有其他重要功能需要加入？反过来，是否有内容需要排除？"
  2. 判断Skill是否需要代码。如果任何步骤涉及调用API、处理数据、读写文件或计算结果，Skill需要代码，你应默认采用CLI模式。只有当每个步骤纯粹涉及推理、协调现有工具或遵循无需编程工作的书面协议时，才使用纯文本指令型Skill。用通俗易懂的语言向用户确认你的评估：
    • 如果需要代码："其中一些步骤涉及[从API获取数据/处理文件/计算结果]，因此我会创建一个Agent可以为你运行的辅助脚本。该脚本会包含
      search
      、
      fetch
      、
      analyze
      等简单命令——你无需自己编写任何代码。这样可以吗？"
    • 如果不需要代码："此工作流完全是关于遵循一系列步骤和使用现有工具——无需编写新代码。我会将其编写为Agent可遵循的清晰指令。这样可以吗？"
  3. 如果要创建辅助脚本："我认为该脚本应该包含这些命令：[用通俗易懂的英文描述的拟议命令，例如'search for proteins'、'fetch results'、'compare sequences']。你有什么添加或修改的意见？"
  4. "这个Skill应该叫什么名字？建议名称：
    [建议名称]
    。"

Round 5: Testing (Optional)

第五轮：测试（可选）

  1. "Can you provide a sample query and expected answer that I can use to verify the skill works as intended? For example: 'If I ask [question], the skill should produce [answer].' This is optional but helps me validate the skill during development."
  1. "你能否提供一个示例查询和预期答案，以便我验证Skill是否按预期工作？例如：'如果我问[问题]，Skill应该生成[答案]。'这是可选步骤，但有助于我在开发过程中验证Skill。"

Brainstorming Completion Criteria

头脑风暴完成标准

You are ready to move to Phase 2 when you can confidently answer ALL of:
  • What is the workflow's purpose and scope?
  • What are the inputs and outputs?
  • Which steps are strict vs. flexible?
  • Which existing skills should be referenced?
  • What new scripts (if any) are needed?
  • What rate limits apply?
  • How should errors be handled?
  • Does the workflow need any code? (If yes → CLI pattern; if no → instruction-only)
  • Is there a sample query/answer for validation?
当你能自信回答以下所有问题时，即可进入阶段2：
  • 工作流的目的和范围是什么？
  • 输入和输出是什么？
  • 哪些步骤是严格的，哪些是灵活的？
  • 应该引用哪些现有Skill？
  • 需要哪些新脚本（如果有）？
  • 适用哪些速率限制？
  • 应如何处理错误？
  • 工作流是否需要代码？（如果是→CLI模式；如果否→纯指令型）
  • 是否有用于验证的示例查询/答案？

Phase 2: Skill Design

阶段2：Skill设计

Produce a design document (as an artifact / implementation plan) and present it to the user for approval. The document must include:
  1. Skill name and description (following YAML frontmatter rules: name ≤64 chars, lowercase + hyphens; description ≤1024 chars).
  2. Directory structure showing all planned files.
  3. Existing skills referenced with rationale for each.
  4. New scripts (if any) with proposed subcommands and arguments.
  5. Rate limiting strategy for any APIs not covered by existing skills.
  6. Error handling strategy per step.
Wait for explicit user approval before proceeding to Phase 3.
生成一份设计文档（作为工件/实施计划）并提交给用户审批。文档必须包含：
  1. Skill名称和描述（遵循YAML前置规则：名称≤64字符，小写+连字符；描述≤1024字符）。
  2. 目录结构，展示所有计划文件。
  3. 引用的现有Skill及每个Skill的引用理由。
  4. 新脚本（如果有）的拟议子命令和参数。
  5. 速率限制策略，针对未被现有Skill覆盖的API。
  6. 每一步的错误处理策略。
在进入阶段3之前，等待用户明确批准。

Phase 3: Implementation

阶段3：实施

Guiding Principles

指导原则

General guidelines for skill implementation:
  • Use 
    uv run
    , never 
    python
    or 
    python3
    .
  • Prefer stdlib libraries that come with a default Python 3 installation (
    urllib
    preferred); Avoid libraries that require extra installation if possible.
  • Rate limits must be documented and respected in code. Prefer file-lock–based rate limiting so that concurrent sub-agents sharing the same machine collectively respect the limit. See other skills in the Science Skills bundle for the canonical cross-process–safe implementation.
  • Skill output must be <500 lines or redirected to a file. Long output files should be processed programmatically to extract relevant fields.
  • Hyphens are recommended for the skill name and YAML 
    name:
    field.
Skill实施的通用指南：
  • 使用
    uv run
    ，绝不要使用
    python
    或
    python3
    。
  • 优先使用默认Python 3安装自带的标准库（推荐
    urllib
    ）；尽可能避免需要额外安装的库。
  • 必须在代码中记录并遵守速率限制。优先采用基于文件锁的速率限制，以便共享同一机器的并发子Agent共同遵守限制。请参考Science Skills Bundle中的其他Skill，获取跨进程安全的标准实现方式。
  • Skill输出必须少于500行，或重定向到文件。长输出文件应通过编程方式处理，提取相关字段。
  • 推荐Skill名称和YAML
    name:
    字段使用连字符。

Rule 1: Reuse Existing Skills

规则1：复用现有Skill

When the workflow uses functionality covered by an existing installed skill, the new SKILL.md MUST reference it by name rather than reimplementing. Include a Dependencies section in the SKILL.md listing required skills with a brief rationale for each.
当工作流使用已安装的现有Skill涵盖的功能时，新的SKILL.md必须通过名称引用该Skill，而非重新实现。在SKILL.md中添加依赖项部分，列出所需Skill并简要说明每个Skill的引用理由。

Rule 2: Rate Limiting for New APIs

规则2：新API的速率限制

For any API interaction not covered by an existing skill, the generated CLI script MUST implement rate limiting. Before writing any rate-limiting code, look up the API's official rate-limit guidelines: check any documentation the user provided during brainstorming, then search the API's public documentation online. If no documented rate limit can be found, default to 1 request per second. The rate limiting pattern is built directly into the CLI template at 
references/cli_script_template.py
— see the 
RateLimitError
class and the 
_request
method of the API client.
Key requirements:
  • Use 
    time.monotonic()
    for timing (not 
    time.time()
    ).
  • Calculate delay from documented rate limits.
  • Implement retry with exponential backoff for transient errors (5xx).
  • Raise a dedicated 
    RateLimitError
    when HTTP 429 is received.
  • Log retry attempts to stderr so the agent can observe progress.
  • Include the URL and rate-limit value in error messages.
  • On non-retriable HTTP errors (e.g. 400, 403, 404), read and include the response body in the error message — not just the status code. API response bodies contain actionable details (e.g., "Invalid parameter") that enable the agent to self-correct.
对于未被现有Skill覆盖的任何API交互，生成的CLI脚本必须实现速率限制。在编写任何速率限制代码之前，查阅API的官方速率限制指南：检查用户在头脑风暴期间提供的任何文档，然后在线搜索API的公开文档。如果找不到记录的速率限制，默认每秒1次请求。速率限制模式已内置在
references/cli_script_template.py
的CLI模板中——请查看
RateLimitError
类和API客户端的
_request
方法。
关键要求：
  • 使用
    time.monotonic()
    进行计时（不要使用
    time.time()
    ）。
  • 根据记录的速率限制计算延迟时间。
  • 针对临时错误（5xx）实现指数退避重试机制。
  • 收到HTTP 429错误时抛出专门的
    RateLimitError
    。
  • 将重试尝试记录到stderr，以便Agent可以观察进度。
  • 在错误消息中包含URL和速率限制值。
  • 对于不可重试的HTTP错误（例如400、403、404），读取并在错误消息中包含响应体——而不仅仅是状态码。API响应体包含可操作的详细信息（例如“无效参数”），使Agent能够自我修正。

Rule 3: CLI Script Pattern (Default When Code Is Needed)

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

This is the default choice. If any step in the workflow involves API calls, data processing, file I/O, computation, or any other programmatic work, produce a multi-command CLI script using 
argparse
with subcommands. Follow the template in 
references/cli_script_template.py
.
Key requirements:
  • Each major workflow step becomes a subcommand.
  • All subcommands accept 
    --output
    for writing results to a file.
  • Use 
    json.dump
    with 
    indent=2
    for JSON output.
  • Print a success message with the output file path.
  • Exit with code 1 on errors.
  • Make arguments like 
    --limit
    required (no silent defaults). This forces the agent to specify the value explicitly, preventing it from assuming it retrieved "all" results when it was silently capped.
这是默认选择。 如果工作流中的任何步骤涉及API调用、数据处理、文件I/O、计算或其他编程工作，请使用
argparse
生成带有子命令的多命令CLI脚本。遵循
references/cli_script_template.py
中的模板。
关键要求：
  • 每个主要工作流步骤对应一个子命令。
  • 所有子命令接受
    --output
    参数，用于将结果写入文件。
  • 使用
    json.dump
    并设置
    indent=2
    生成JSON输出。
  • 打印包含输出文件路径的成功消息。
  • 发生错误时以代码1退出。
  • 将
    --limit
    等参数设为必填（无静默默认值）。这会强制Agent明确指定值，防止它在结果被静默限制时误以为已获取“全部”结果。

Rule 4: Default to File Output

规则4：默认输出到文件

All scripts and workflows MUST write output to files, not stdout. Stdout should only contain short status messages (e.g., "Success! Data written to: results.json"). This is critical because:
  • API responses can be very large and will truncate in terminal output.
  • File output is token-efficient — the agent reads only the fields it needs using 
    jp
    or Python one-liners.
  • Large stdout output wastes context window space.
所有脚本和工作流必须将输出写入文件，而非标准输出(stdout)。标准输出应仅包含简短状态消息（例如“成功！数据已写入：results.json”）。这一点至关重要，因为：
  • API响应可能非常大，在终端输出中会被截断。
  • 文件输出的 token 效率更高——Agent可以使用
    jp
    或Python单行代码仅读取所需字段。
  • 大量标准输出会浪费上下文窗口空间。

Rule 5: Instruction-Only Pattern (Only When No Code Is Needed)

规则5：纯指令模式（仅当无需代码时使用）

Use this pattern only when the workflow requires zero programmatic work — i.e., every step is purely about orchestration, reasoning, multi-skill coordination, or following a written protocol. If any step needs code (API calls, data processing, file I/O, etc.), use the CLI pattern from Rule 3 instead. Produce a SKILL.md with a structured workflow section:
markdown
undefined
仅当工作流完全不需要编程工作时才使用此模式——即每个步骤纯粹涉及编排、推理、多Skill协调或遵循书面协议。如果任何步骤需要代码（API调用、数据处理、文件I/O等），请改用规则3中的CLI模式。生成包含结构化工作流部分的SKILL.md：
markdown
undefined

Workflow

工作流

1. Step Name

1. 步骤名称

  • Description of what to do
  • Which skill to use and how
  • 操作说明
  • 使用的Skill及使用方式

2. Next Step

2. 下一步

...
undefined
...
undefined

Rule 6: SKILL.md Structure

规则6：SKILL.md结构

Every generated SKILL.md must follow this structure:
markdown
---
name: {skill-name}
description: >-
  {description}
---
每个生成的SKILL.md必须遵循以下结构：
markdown
---
name: {skill-name}
description: >-
  {description}
---

{Skill Title}

{Skill标题}

Overview

概述

{Brief description of what the skill does.}
{Skill功能的简要描述。}

Dependencies

依赖项

{List of required skills, if any.}
{所需Skill列表（如有）。}

Quick Start

快速开始

{Minimal example to get started.}
{入门的最简示例。}

Utility Scripts (if CLI-based)

实用脚本（如果是基于CLI的）

{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.}
undefined
{列出2-3个常见陷阱。}
undefined

Phase 4: Validation

阶段4：验证

After implementation is complete:
  1. Test the skill manually by invoking the agent with a natural-language prompt that should trigger the new skill.
  2. If a sample query/answer was provided during brainstorming, run it through the skill and verify the output matches expectations.
实施完成后：
  1. 手动测试Skill：使用应触发新Skill的自然语言提示调用Agent。
  2. 如果头脑风暴期间提供了示例查询/答案，将其通过Skill运行，验证输出是否符合预期。