sciagent-skill-creator

SciAgent Skill 创建器

用于在仓库本地搭建 skills/ 条目。自动生成 AGENTS.md 步骤 1、2、4、5、6 中的样板内容，让撰写工作专注于 内容（何时使用、工作流、用法示例、参考资料），而非字段配置。

何时调用此 skill

• 用户要求为特定工具、库、数据库或指南主题创建新的 SciAgent skill 条目
• 用户直接调用 /sciagent-skill-creator
• Agent 准备手动编辑 registry.yaml，并从头创建 skills/<cat>/<name>/SKILL.md——应改用此工具

不要在以下情况下调用：

• 编辑现有条目的内容（直接编辑文件即可）
• 迁移现有条目（先阅读 AGENTS.md 中的“从现有条目迁移”——搭建脚本会生成骨架，但迁移需要对内容作出判断）
• 只更新 registry.yaml（使用常规编辑）

需要向用户收集的信息

调用搭建脚本前，先通过对话收集以下信息，而不是通过用户看不到的标志传入：

1. 主题 — 具体的工具、库或概念名称。对于模糊主题（如“ML 相关内容”），应通过提问澄清。
2. 子类型 — pipeline | toolkit | database | guide。使用 AGENTS.md 步骤 1b 中的判断规则。不确定时，询问用户。
3. 类别 — 主要类别目录。如果用户不确定，列出 AGENTS.md 步骤 2 中的表格。
4. 条目名称 — kebab-case 格式的标识名。惯例：{tool-name}-{purpose}（例如 pydeseq2-differential-expression）。请与用户确认。
5. 许可证 — 底层工具的许可证。纯原创文本内容默认使用 CC-BY-4.0。
6. 描述 — 1-2 句话，最多 1024 个字符。前 120 个字符应以工具或领域关键词开头。反面示例见 AGENTS.md 步骤 5“描述撰写规则”。
7. 标签（可选）— 仅当条目确实涉及多个类别时使用（例如，存放在 scientific-writing 下的文献数据库，可标记为 ["databases", "literature"]）。

搭建前检查重复项

调用搭建脚本前，在注册表和 legacy/ 中搜索相似名称：

grep -i "<topic-keyword>" registry.yaml
ls legacy/ | grep -i "<topic-keyword>"

如果存在近似重复项，应先告知用户，再继续操作。创建平行条目通常意味着应更新现有条目，而不是重复创建。

如何运行搭建脚本

使用明确的参数调用 scripts/scaffold.py。该脚本不提供交互模式——由 Agent 提供所有值：

python .claude/skills/sciagent-skill-creator/scripts/scaffold.py \
  --sub-type pipeline \
  --category genomics-bioinformatics \
  --name my-tool-purpose \
  --description "MyTool short-form description starting with the tool name. Brief on inputs, outputs, when to pick this over alternatives." \
  --license MIT \
  --tags databases,literature   # optional, comma-separated

工作流程：

1. 验证名称（kebab-case、尚未列入 registry.yaml，且不在 legacy/ 中）
2. 验证类别是否为 skills/ 下的目录
3. 使用 validate_description.py 验证描述（长度及前 120 个字符中的关键词）
4. 验证标签（若提供，必须为 kebab-case）
5. 根据匹配的模板创建 skills/{category}/{name}/SKILL.md，并替换 frontmatter 字段
6. 向 registry.yaml 追加新条目，date_added 设置为今天（UTC）
7. 运行 pixi run validate，确认注册表格式仍然正确
8. 打印后续步骤（填写概述、工作流、用法示例、参考资料）

任何验证失败时，脚本都会中止且不会写入任何内容。修正有问题的值后重新运行。

搭建后

生成的 SKILL.md 是包含占位符的骨架。Agent 还需完成以下工作：

1. 填写 Overview、When to Use、Prerequisites、Workflow / Core API / Key Concepts、Common Recipes、Troubleshooting、References
2. 按子类型要求的章节结构编写（参见 AGENTS.md 步骤 4 的格式规则）
3. 运行 pixi run test——运行完整测试套件，而不只是 validate——以捕获子类型特有的结构问题（代码块数量、表格行数、章节是否齐全）

搭建脚本不会假装替你撰写内容。内容仍由 Agent 根据源材料编写。

内容编写规则（SKILL.md 中不应包含的内容）

技能描述的是工具的分析能力范围，而不是使用者的风格规范。许多 Agent 会读取同一个 SKILL.md，用于各种下游任务——适合某个分析需求的视觉选择会渗入之后的每次调用。提交前请删除以下内容：

• 配色方案、色图、主题——不要包含十六进制代码（#08306b）、LinearSegmentedColormap.from_list(...)、ListedColormap([...])，也不要指定 cmap= 参数，除非色图本身就是工具 API 的一部分（例如，工具自带调色板）。让 matplotlib 使用默认设置；使用者可在下游覆盖。
• 按重复样本／条件指定的颜色字典——例如 colors = {"rep1": "#1f77b4", ...}。Matplotlib 会自动循环使用颜色。
• 字体选择、dpi 预设、为单份报告调整的图形尺寸——常规折线图使用 figsize=(8, 4) 没问题；为适配幻灯片而选用 figsize=(12, 4) 则不合适。
• 仅适用于一次性用户需求的细节——如果用户在自己的分析中要求“低值用蓝色，高值用红色”，这应写在他们自己的代码中，而不是技能里。技能说明的是如何计算 phi/psi 密度；如何着色由使用者决定。
• 超出工具默认值的硬编码路径——"figures/"、"results/"、f"{pdb_id}_protein.pdb" 可作为示例输出；"/Users/me/proj42/output" 则不可以。

应保留的内容：分析逻辑、数据形状、单位、参数语义、预期输出结构（列、坐标轴、单位），以及工具本身强制采用的视觉选择。

经验法则：如果下游使用者会覆盖某项选择，就不要把它写进技能。

写作风格：简洁

SKILL.md 是供 Agent 查阅的参考资料，不是教程。Token 成本很重要——每次检索都会为每一行付费。写得像文档，而不是操作指南：

• 每个章节的引言只写一句话，不要写成一段。 删除模棱两可的措辞（“通常”“一般来说”“你可能会想”）、填充语（“请注意”“值得一提的是”）和弱化语气的表达。直接陈述规则。
• 代码块中的注释要有存在价值。 只注释不明显的代码行——例如单位、易错点、参数用途。不要重复代码已有的信息（在 traj = md.load(...) 上方写 # load the trajectory 就是冗余）。
• 尽可能用代码代替文字。 四行代码块胜过描述相同调用的段落。Agent 会运行代码；文字用于说明代码无法体现的内容。
• 代码前不要写引言。 “以下代码片段演示了如何……” → 删除。标题和代码足以说明。
• 结尾不要重复总结。 信息结束后，章节也随之结束。不要写“总之……”或“如上所示……”。
• 删去各章节之间的重复内容。 如果工作流步骤 2 已展示该参数，“关键参数”表格行就无需再次解释，只需列出即可。
• 枚举内容用表格，不用项目符号。 参数、故障排查项、代码等都用表格。用文字罗列会浪费纵向空间。

目标密度：读者浏览文件时，阅读约 5 行文字后就应能看到下一个代码块。如果某一节的文字比代码还长，就精简文字。

此技能中的文件

• SKILL.md — 本文件（何时／如何／做什么）
• scripts/scaffold.py — 非交互式脚手架工具（创建文件、追加注册表、运行验证）
• scripts/validate_description.py — 描述检查器（长度 + 前 120 个字符的关键词规则）。供 scaffold.py 和独立运行时复用。

需要向用户提示的失败情况

• 名称已存在 → 建议使用其他后缀
• 类别不在列表中 → 显示类别表格并询问用户
• 描述以禁止的动词开头（Use、A、An、The、Query）→ 改写描述，让工具名称位于开头
• 描述过长 → 精简用于区分的尾部内容；保留承载关键词的部分
• 脚手架运行后 pixi run validate 失败 → 注册表处于不一致状态，中止并撤销部分写入（脚本会自动执行此操作；原样报告验证器输出）