把已完成的用户工作流提炼成可复用 Agent…

当用户要求把刚做完的某段工作流/多步交互打包成可复用技能时，用分阶段流程将其蒸馏为 SKILL.md 与配套脚本。

适用场景

解决思路

1. 必须先完成 Phase 1 头脑风暴，才能写任何代码或 SKILL.md 内容；跳过头脑风暴会产出过死或过虚的技能，这段对话是整个流程最重要的部分。
2. 头脑风暴采用多轮迭代对话，不要一次问完所有问题；每轮从问题库中挑 2-3 个相关问题，逐步细化理解并追问。
3. Round 1 先总结你观察到的工作流，再问：我的理解是否准确、要改什么；预期输入与输出是什么；这个工作流多久跑一次、是周期性还是一次性。
4. Round 2 针对每个步骤判断刚性：主方案失败（如 API 挂了、无结果）时应 (a) 询问用户、(b) 自动尝试替代方案、还是 (c) 直接报错失败；哪些步骤必须用特定方法（如指定数据库）、哪些任意合理方法都行；边缘情况应静默处理还是上报用户。
5. Round 3 先检查已安装技能与工作流的重叠：若已有技能覆盖某步骤，新技能必须引用它，不得提供自包含实现；然后问是否还有其他要纳入的工具或技能、是否有未被现有技能覆盖的 API 速率限制、是否有提供科学背景的关键文件（API 文档、参考论文、示例数据集、领域笔记）需要纳入参考材料。
6. Round 4 确认范围与形态：工作流覆盖的 X/Y/Z 是全部蒸馏还是增删；判断是否需要代码——只要任一步骤涉及调用 API、处理数据、读写文件或计算结果就需要代码并默认采用 CLI 模式，只有全部步骤都是纯推理、协调已有工具或遵循书面协议时才用纯文本指令技能，并用平实语言向用户确认；若需脚本，用平实英文列出拟定的子命令（如 search、fetch、analyze）请用户增改；最后确认技能名称。
7. Round 5（可选）请用户提供一个样例查询与预期答案，用于开发期间验证技能。
8. 头脑风暴完成标准：能自信回答全部问题——工作流目的与范围、输入输出、哪些步骤严格哪些灵活、应引用哪些已有技能、需要哪些新脚本、适用哪些速率限制、如何处理错误、是否需要代码（是→CLI 模式，否→纯指令）、技能安装位置（本地/全局/自定义路径）、是否有样例查询与答案用于验证。
9. Phase 2 产出设计文档（作为 artifact/实施计划）交用户审批，必须包含：技能名与描述（YAML frontmatter 规则：name ≤64 字符、小写加连字符；description ≤1024 字符）、目录结构（含所有计划文件与安装位置）、引用的已有技能及理由、新脚本（如有）的拟定子命令与参数、未被已有技能覆盖的 API 的限流策略、每步的错误处理策略；必须等到用户明确批准后才能进入 Phase 3。
10. Phase 3 通用准则：使用 `uv run`，绝不用 `python` 或 `python3`；优先使用默认 Python 3 自带的标准库（首选 `urllib`），尽量避免需要额外安装的库；速率限制必须写入文档并在代码中遵守，优先使用基于文件锁的限流，使同机并发的子 agent 共同遵守限制（参考 Science Skills bundle 中跨进程安全的实现）；技能输出必须 <500 行或重定向到文件，长输出文件应程序化提取相关字段；技能名与 YAML `name:` 字段推荐使用连字符。
11. Rule 1 复用已有技能：当工作流用到已安装技能覆盖的功能时，新 SKILL.md 必须按名称引用而非重新实现，并在 SKILL.md 中加入 Dependencies 章节列出所需技能及简要理由。
12. Rule 2 新 API 的限流：对未被已有技能覆盖的任何 API 交互，生成的 CLI 脚本必须实现限流；写限流代码前先查该 API 官方限流指南（先看用户提供的文档，再上网搜公开文档），找不到文档化限制时默认 1 请求/秒；限流模式已内置于 `references/cli_script_template.py`（见 `RateLimitError` 类与 API client 的 `_request` 方法）。关键要求：用 `time.monotonic()` 计时（不用 `time.time()`）；按文档化限流计算延迟；对瞬时错误（5xx）实现指数退避重试；收到 HTTP 429 时抛出专用 `RateLimitError`；把重试尝试记录到 stderr 以便 agent 观察进度；错误信息中包含 URL 与限流值；对不可重试的 HTTP 错误（如 400、403、404）要读取并把响应体包含进错误信息，而不只是状态码，因为响应体含可操作细节（如 "Invalid parameter"）让 agent 能自我纠正。
13. Rule 3 CLI 脚本模式（需要代码时的默认选择）：只要任一步骤涉及 API 调用、数据处理、文件 I/O、计算或其他程序化工作，就用 `argparse` 子命令产出多命令 CLI 脚本，遵循 `references/cli_script_template.py` 模板。关键要求：每个主要工作流步骤对应一个子命令；所有子命令都接受 `--output` 把结果写入文件；JSON 输出用 `json.dump` 加 `indent=2`；打印带输出文件路径的成功消息；出错时以退出码 1 退出；把 `--limit` 这类参数设为必填（不要静默默认值），迫使 agent 显式指定，避免它在被静默截断时误以为取到了全部结果。
14. Rule 4 默认文件输出：所有脚本与工作流必须把输出写入文件而非 stdout；stdout 只放简短状态消息（如 "Success! Data written to: results.json"）。原因：API 响应可能很大并在终端输出中被截断；文件输出更省 token，agent 可用 `jp` 或 Python 单行命令只读所需字段；大量 stdout 输出浪费上下文窗口。
15. Rule 5 纯指令模式（仅在不需要代码时）：只有当工作流完全不需要程序化工作——每一步都纯粹是编排、推理、多技能协调或遵循书面协议——才用此模式；任一步骤需要代码（API 调用、数据处理、文件 I/O 等）就改用 Rule 3 的 CLI 模式。产出带结构化 Workflow 章节的 SKILL.md，形如 `## Workflow` 下按 `### 1. Step Name` 列出做什么、用哪个技能及怎么用。
16. Rule 6 SKILL.md 结构：每个生成的 SKILL.md 必须遵循固定结构——YAML frontmatter（name、description）、`# {Skill Title}`、`## Overview`、`## Dependencies`（如有）、`## Quick Start`、`## Utility Scripts`（CLI 型时，逐个记录子命令与示例）、`## Workflow`（纯指令型时，编号步骤与清晰说明）、`## Rate Limiting`（如适用，记录限流及执行方式）、`## Common Mistakes`（列 2-3 个常见坑）。
17. Rule 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 自行查明本地与全局技能路径。
18. Phase 4 验证：实现完成后，用应触发新技能的自然语言提示调用 agent 手动测试；若头脑风暴时提供了样例查询/答案，跑一遍并核对输出是否符合预期。

适用边界 · 注意事项

• 不要用于从零创建技能（没有已存在的工作流）——那种情况应使用通用的 skill-creator。
• 不要在未完成 Phase 1 头脑风暴前就写代码或 SKILL.md 内容。
• 不要在 Phase 2 设计文档获得用户明确批准前进入 Phase 3 实现。