在 dotnet/skills 仓库从零创建符合…

适用于在 dotnet/skills 仓库中从零创建新 Agent Skill，并确保 description 路由、正文模板、目录结构、CODEOWNERS 和 eval 都符合仓库约定的场景。

适用场景

解决思路

1. 验证技能名称：只包含小写字母、数字和连字符；不以连字符开头或结尾；不包含连续连字符；长度 1-64 字符。
2. 编写 description，因为它是运行时决定是否加载技能时唯一看到的文本。使用 frontmatter 格式：name: <skill-name>，description: <what it does>. USE FOR: <symptoms, error codes, artifact names, quoted user requests>. DO NOT USE FOR: <nearby-but-wrong intents, with the skill that owns them>。
3. description 以动作动词开头，使用用户自己的词：症状、错误码（CS1501、MSTEST0014）、artifact 名（.testsettings、binlog），以及开发者会输入的请求。
4. 与兄弟技能按真实区分条件划分，而不是按主题；例如「抽象是否已存在？」可区分两个技能，「testing」不能；将匹配的排除加到两个兄弟技能。
5. 声明会路由到兄弟技能的模糊词；如果提示说「review my tests」而兄弟技能拥有「review」，明确说明。
6. 对照技能要服务的场景检查每个 DO NOT USE FOR 子句；像「already on v3」这样的排除可能锁住升级后修复，而这是技能的目的。
7. 遵守 description 预算：每个 description 1,024 字符；整个插件的渲染技能菜单也受预算限制；用户不应直接调用的 helper skill 可设置 disable-model-invocation: true 以释放菜单空间，同时仍可按名称调用。
8. 为超过基线模型的 delta 写作：每个技能与同一模型未加载技能时头对头评分；模型无需协助已能产生的内容价值为零；使其更慢或更含糊的内容价值低于零。
9. 编码模型本来会做错的决策，而不是复述它已能重现的 API 签名。
10. 使用「When A, do B, never C, verify D」表格，而不是列出看似合理的替代方案。
11. 使用具体输出契约（精确命令、判定行、发现表），而不是「Consider…」、「you may want to…」。
12. 按输入大小调整输出结构，而不是为 8 个测试套件做 12 节仪表盘。
13. 设置停止条件防止过度应用，而不是在测量前行动、重写可工作代码。
14. 指示 agent 发现仓库路径，而不是把可发现路径标记为必需输入。
15. 如实报告 restore/build/test 失败，而不是在命令失败后声称成功。
16. 通过编译或探测验证承载性 API 声明，而不是信任读到的源码。
17. 将罕见或昂贵路径放在 references/ 后面，而不是一个大的 SKILL.md 承载每条路径。
18. 不要过度纠正：一个比基线更短且更不可操作的熟练回答仍然会输。
19. 创建技能目录：plugins/<plugin>/skills/<skill-name>/，其中包含 SKILL.md。
20. 使用 Step 2 起草的 frontmatter 生成 SKILL.md。
21. 添加 Purpose 部分：一段描述结果。
22. 添加 When to Use 部分：合适场景的 bullet list。
23. 添加 When Not to Use 部分：边界和排除。
24. 添加 Inputs 部分：必需和可选输入的表。
25. 添加 Workflow 部分：带检查点的编号步骤。
26. 添加 Validation 部分：如何确认技能正确工作。
27. 添加 Common Pitfalls 部分：已知陷阱及如何避免。
28. 如需要，添加 scripts/ 目录：agents 可运行的可执行代码。
29. 如需要，添加 references/ 目录：按需加载的额外文档。
30. 如需要，添加 assets/ 目录：模板、图片、数据文件。
31. 使用相对于包含 SKILL.md 的目录的路径引用捆绑文件，例如 references/details.md 或 scripts/validate.ps1；不要告诉 agent 搜索技能的安装目录；如果缺失捆绑文件会降低结果质量，允许列出一次已知的捆绑文件目录并要求 agent 报告降低的覆盖范围。
32. 更新 .github/CODEOWNERS：为新的技能及其测试目录添加条目：/plugins/<plugin>/skills/<skill-name>/ @owner-team 和 /tests/<plugin>/<skill-name>/ @owner-team；匹配同一插件中兄弟技能使用的 owner 模式。
33. 确认 frontmatter 字段有效。
34. 确保 SKILL.md 少于 500 行。
35. 检查文件引用使用相对路径。
36. 验证指令可操作且具体。
37. 运行 dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin>。
38. 用 create-skill-test 在同一个 pull request 中添加 eval.yaml。
39. 没有 eval.yaml 的技能没有证据表明它比基线有改进。
40. 使 eval 规模具有统计功效——少于五个不同刺激的 eval 永远无法返回通过判定。
41. 例外：带有 disable-model-invocation: true 的 helper skill，模型不能自行激活它，所以激活评分的 eval 比较两个相同臂；改为通过加载它的技能的 eval 来覆盖。
42. 使用提供的 SKILL.md 模板创建新技能（frontmatter、标题、目的、When to Use、When Not to Use、Inputs、Workflow、Validation、Common Pitfalls）。
43. 创建后验证：技能名称与目录名完全匹配。
44. 创建后验证：技能名称仅小写和连字符。
45. 创建后验证：description 非空且少于 1024 字符。
46. 创建后验证：SKILL.md 正文少于 500 行。
47. 创建后验证：指令具体且可操作。
48. 创建后验证：捆绑文件路径相对于包含 SKILL.md 的目录。
49. 创建后验证：缺失捆绑文件不能导致静默降级。
50. 创建后验证：Workflow 有编号步骤和清晰检查点。
51. 创建后验证：Validation 部分存在，具有可观察的成功标准。
52. 创建后验证：不包含 secrets、tokens 或 internal URLs。
53. 创建后验证：.github/CODEOWNERS 有新技能及其测试目录的条目。
54. 创建后验证：description 命名具体触发条件并排除最近的兄弟技能。
55. 创建后验证：每个部分都改变未加载技能的模型本来会做错的决策。
56. 创建后验证：技能说明何时 **不** 行动，以及真实失败报告是什么样。
57. 创建后验证：存在 eval.yaml 并清除 distinct-stimulus 下限（或技能是 disable-model-invocation: true 并通过其消费者覆盖）。
58. 避免陷阱：名称包含大写字母 -> 仅使用小写：code-review 而不是 Code-Review。
59. 避免陷阱：description 模糊 -> 包含它做什么以及何时使用。
60. 避免陷阱：指令模糊 -> 使用编号步骤和具体动作。
61. 避免陷阱：缺少验证步骤 -> 添加验证成功的检查点。
62. 避免陷阱：SKILL.md 太长 -> 将详细内容移到 references/ 文件。
63. 避免陷阱：硬编码环境假设 -> 在 compatibility 字段中记录要求。
64. 避免陷阱：缺少 CODEOWNERS 条目 -> 为 /plugins/<plugin>/skills/<skill-name>/ 和 /tests/<plugin>/<skill-name>/ 添加条目，匹配兄弟技能的 owner 模式。
65. 避免陷阱：技能复述模型已知内容 -> 删除；技能按相对于未加载模型的 delta 评分。
66. 避免陷阱：可发现路径列为必需输入 -> 告诉 agent 发现它们，否则它会停止并询问用户。
67. 避免陷阱：description 按主题与兄弟技能分区 -> 按真实区分条件分区并在两侧排除。
68. 避免陷阱：排除子句阻止技能自己的用例 -> 对照真实工作流阶段重读每个「do not use for」子句。
69. 避免陷阱：添加技能但没有 eval -> 在同一个 PR 中添加 eval.yaml；未评估的技能没有证据。

适用边界 · 注意事项

• 修改现有技能时不要用；直接编辑现有文件。
• 诊断或修复未通过评估的技能时不要用；改用 improve-skill-quality。
• 编写技能的 eval.yaml 或创建自定义 agents 时不要用；分别改用 create-skill-test 或 agents/ 目录模式。