make-skill

创建或修复技能

编写简洁、稳定的任务指南，补充 Agent 无法仅凭源代码可靠推断的知识，并配套创建评估，以证明指南确实改变了行为。

选择合适的构件

• 对于按需加载的特定任务工作流或知识体系，请使用技能。
• 对于适用于特定路径的背景指南，请使用文件指令。
• 当需要隔离上下文或施加不同的工具限制时，请使用自定义 Agent。
• 优先使用现有技能，避免创建内容重叠的技能。

工作流

1. 阅读相关实现、测试、仓库指令以及相邻的自定义内容。
2. 找出反复出现的错误或不明显的不变量。不要将源代码清单、行数或可轻易从代码中重新发现的事实写入技能。
3. 创建 .agents/skills/<name>/SKILL.md。Frontmatter 中的 name 必须与目录名完全一致；描述必须说明技能的用途，以及用户提出哪些自然语言请求时应触发该技能。
4. 将背景领域指南标记为 user-invocable: false。面向用户的工作流应聚焦于用户会明确提出的目标。
5. 编写可执行且有明确验证方式的指南。解释边缘情况的重要性；避免重复仓库指令中已有的通用工程建议。
6. 创建 eng/harness-evaluation/skills/<name>/eval.yaml，并遵循 eng/harness-evaluation/README.md。
7. 对自定义内容运行 lint，并检查对照组和处理组的产物，再决定是否接受。

配对评估

• 评估根目录下的 agent_environment.skills 只包含目标技能。刺激输入应放在各刺激项的 agent_environment.files 下。
• 运行器会在对照组中移除根目录技能，并单独验证处理组是否激活该技能。不要添加 skill-invocation grader，也不要在共享提示词中要求 Agent 调用技能。
• 提示词可以指出固定数据、拟议代码、固定 ID 和输出路径，但不得透露预期诊断、所属机制或回归测试设计。
• 暂存自包含的源代码快照，不要使用差异文件或提交引用；测试夹具不得依赖获取某个仓库版本。
• 对可观察产物使用确定性 grader，对行为使用范围明确的语义评估，并添加 token-budget grader。设置有上限的轮次、令牌数和耗时，以及已提交的评分阈值。
• 任务必须考查该技能独有的指南。若对照组的表现始终与处理组一致，说明技能或评估的实用性不足。

验证

• Frontmatter 可解析，且名称与目录名一致。
• 技能简洁、稳定，且未重复根级或作用域内的指令。
• 文件引用使用相对路径，且目标文件存在。
• 验证步骤明确可观察，并针对具体任务。
• 配对评估只针对该技能，评分完整且有界，提示词不偏向特定解法。
• npm run lint 和 harness 清单测试均通过。

常见问题

问题	修正方法
将实现清单照搬到技能中	只保留不明显的不变量和路由决策
使用精确行数或易变指标	删除这些内容；改为引用稳定符号或行为
提供通用测试目录指南	描述有独特性的测试形式，或省略
评估提示词告诉 Agent 要找什么	将预期事实移至隐藏评分标准
评估根目录包含仓库测试夹具	根目录仅保留目标技能；按刺激项暂存测试夹具
提示词要求调用技能	由仅针对处理组的运行器门控来确保技能激活
初始脚手架启动多模型审查	先生成并 lint 所需产物；另行运行耗时的行为验证