improve-ic-skill

改进 IC Skill

用于改进 IC Skills 仓库中现有 Skill 的高效工作流。指导原则：先了解问题，再精确修改，只验证改动内容。 评测作为回归安全网——有选择地运行，不要每次都自动运行。

第 0 步——动手前先了解问题

这是必须遵守的停止条件。在用户明确提出具体问题之前，不要读取任何文件、运行任何命令或进行任何更改。

你需要了解：

1. 具体问题是什么？（例如：“canister ID X 已过时”“缺少关于 Y 的注意事项”“描述无法针对 Z 触发”“代码示例使用了已弃用的 API W”）
2. 为什么这很重要？（例如：“Agent 会生成无法运行的代码”“该使用场景下 Skill 始终无法触发”“上游同步加入了我们未涵盖的新命令”）

如果请求含糊不清（例如“改进 motoko skill”“ckbtc skill 感觉不够好”），请询问：

“你希望我重点解决什么具体问题？例如：缺少注意事项、canister ID 已过时、代码示例无法运行，或描述无法正确触发。”

如果用户无法或不愿提供具体问题——停止。不要继续。 不要读取 Skill，不要运行命令，也不要“自行探索并寻找改进之处”。请明确说明：

“开始之前，我需要知道要解决的具体问题。盲目改进可能会改动不需要修改的内容。要找到具体问题，可以尝试运行 npm run validate、检查 evaluations/<skill-name>.json 中失败的用例，或提供 GitHub issue 或上游差异供我参考。”

如果用户提出异议、重复含糊的请求或表达不满——坚持这一立场。答案始终不变：没有具体问题，就不开始工作。

唯一例外：如果根据对话中的上下文（GitHub issue 正文、上游差异或具体错误消息）可以明确判断原因——无需询问，直接继续第 1 步。

第 1 步——了解 Skill

完整阅读 skills/<skill-name>/SKILL.md。检查：

• 它涵盖了什么，缺少了什么
• 是否受上游跟踪：运行 grep <skill-name> .claude/upstream.md——如果有匹配项，记下哪些部分由 icskills 负责（这些部分不能被上游内容覆盖）
• 最近的 git 历史：git log --oneline -5 -- skills/<skill-name>/SKILL.md

第 2 步——验证基线

npm run validate

在修改内容前修复所有错误。警告可以接受——除非与本次改进相关，否则不要为此花费精力。

第 3 步——找出改进之处

以全新的视角阅读。常见的高价值改进领域：

注意事项——价值最高的内容；每记录一条注意事项，都能避免 Agent 产生一次幻觉。查找：你了解的错误用法、Agent 通常会误读的错误消息、错误的默认值、API 易错点。

Canister ID 和版本号——根据主网和当前发布标签进行核实。过时的 ID 会悄无声息地导致 Agent 生成的代码无法运行。

代码示例——验证语法能够编译、API 仍然存在，且没有使用已弃用的模式。

描述——必须说明它的功能、适用场景，以及不适用的场景。包含 Agent 会匹配的具体关键词。描述薄弱会导致 Skill 始终无法触发。

必需的 frontmatter——CI 要求包含 metadata.title 和 metadata.category。缺少这些字段会阻止部署。

对于受上游跟踪的 Skill（writing-motoko、migrating-motoko-actors、troubleshooting-motoko-migrations、reviewing-motoko、mops-cli、static-site）：仔细阅读 .claude/upstream.md。仅可自由修改由 icskills 负责的部分；对共享内容的修改也应提交到上游。

第 4 步——应用改进

编辑 skills/<skill-name>/SKILL.md。聚焦于问题本身——不要重构未要求修改的内容。

第 5 步——再次验证

npm run validate

修复所有错误。无关部分的警告可以保留。

如果改动较大，可以选择运行 LLM 质量评分：

skill-validator score evaluate --provider claude-cli skills/<skill-name>

步骤 6 — 检查并更新 eval

打开仓库根目录中的 evaluations/<skill-name>.json（不要打开技能目录中的文件）。

如果该文件尚不存在，请在本次改进过程中创建它。改进技能正是为它添加首批 eval 的好时机。先从精简的内容开始——添加 1-2 个涵盖最重要陷阱的 output_evals，以及 2-3 个针对描述的 trigger_evals。不要试图面面俱到；小而准确的 eval 文件，胜过大而全却从未运行的文件。

对于上游同步，如果不存在 eval 文件：直接根据上游 diff 添加用例——diff 中新增的命令、变更的默认值、重命名的 API 和新出现的陷阱，正是 Agent 在缺少更新后的指导时最容易产生幻觉的地方。diff 是最好的参考来源。

# Verify no eval file exists
ls evaluations/<skill-name>.json 2>/dev/null || echo "No evals yet — create them"

如果该文件已存在，请结合你的改动检查现有用例。

以下情况务必更新 eval：

• 你新增了陷阱——缺少指导时，Agent 最容易在这些地方产生幻觉；每个新陷阱都应有对应的用例
• 你更改了命令、API 或 canister ID，导致现有用例描述有误——请修正用例
• 你引入了 Agent 在缺少明确指导时很可能会弄错的新行为

保持测试套件精简。 不要为显而易见或已有充分覆盖的内容添加用例。每个用例都会成为未来的回归测试，并需要消耗 token 来运行。

步骤 7 — 运行 eval

这里有两项彼此独立的工作——不要混为一谈：

A. 务必运行你新增或修改的每个用例（并与基线对比）。 新增或编辑的 eval 用例就是你刚编写的代码。运行它可以确认用例确实通过，并展示使用技能与基线之间的实际差异。未运行的用例可能范围设置不当——例如，提示词要求“只给命令”，但预期行为却需要解释，导致使用技能的运行失败——而你却提交了一个悄然失效的回归测试。请在 PR 中附上这些结果。这是必须执行的，即使改动“纯粹是新增内容”也不例外：新增内容意味着新增用例，而新增用例必须运行。

B. 仅在相关时重新运行未改动的现有用例。 重新运行其余现有测试套件属于回归检查——“我是否破坏了已有测试的内容？”在以下情况下进行此检查：

• 你更改或删除了现有 eval 明确测试的内容（canister ID、命令名称、错误消息）
• 你重写了多个现有 eval 覆盖的章节
• 描述有显著变化——只运行 trigger eval
• 你不确定改动是否安全

只有在你改动的内容与某个现有用例覆盖的内容无关时，才可以跳过重新运行该用例。

请先检查现有的 eval，再作决定：

node scripts/evaluate-skills.js <skill-name> --list

只运行相关的子集：

# Single eval by index (cheapest)
node scripts/evaluate-skills.js <skill-name> --eval <N>

# Trigger evals only — for description changes
node scripts/evaluate-skills.js <skill-name> --triggers-only

# Run a case you added/changed WITH baseline (default) — this is what goes in the PR
node scripts/evaluate-skills.js <skill-name> --eval <N>

# Skip baseline (--no-baseline) only for a quick correctness spot-check, not for PR results
node scripts/evaluate-skills.js <skill-name> --eval <N> --no-baseline

# Full suite — only when you made broad changes across the whole skill
node scripts/evaluate-skills.js <skill-name>

Eval 格式参考：

{
  "output_evals": [
    {
      "name": "descriptive name",
      "prompt": "scoped prompt asking for one thing — specify what to exclude to keep it fast",
      "expected_behaviors": [
        "Specific, checkable behavior the model should exhibit",
        "Another specific behavior"
      ]
    }
  ],
  "trigger_evals": [
    {
      "query": "realistic user prompt that should trigger this skill",
      "expected_behavior": "should trigger"
    },
    {
      "query": "realistic prompt that looks similar but should NOT trigger this skill",
      "expected_behavior": "should NOT trigger"
    }
  ]
}

提示词的范围要明确——开放式提示词会生成较长的回复，也容易超时。一次只询问一件事；明确排除不需要的内容（“只给函数，不要部署步骤”）。

步骤 8 — 最终检查

npm run validate

技能已准备好提交 PR。请简要总结改动内容；如果你在步骤 7 中运行了 eval，请将相关结果放入 <details> 块中折叠展示（准确格式请参阅 提交 PR）。

由上游跟踪的技能

编辑 writing-motoko、migrating-motoko-actors、troubleshooting-motoko-migrations、reviewing-motoko、mops-cli 或 static-site 之前，请先阅读 .claude/upstream.md。其中列出了哪些章节由 icskills 所有。你可以自由改进自有章节。对于共享内容，也应向上游提交 issue，以便这些改进能在下次同步时合并回去。