Skill 治理、测试与版本发布
目录
为什么要治理 Skill
Skill 一旦被 Agent 自动引用，错误步骤的影响面可能大于一次普通对话：它会重复执行、可能被写进记忆、甚至触发工具链。治理目标是把 Skill 当成配置即代码：可评审、可测试、可回滚。
版本号：语义化建议
推荐采用 SemVer 风格（主版本.次版本.修订）：
- 主版本：流程结构变化、输入输出不兼容。
- 次版本：新增步骤、收紧质量标准（向后兼容）。
- 修订：措辞修正、错别字、无行为变化。
在 SKILL.md 顶部 Metadata 中写明 Version，并在 Git 提交信息里引用。
变更评审检查项
| 检查项 | 说明 |
|---|---|
| 适用场景是否收窄/扩大 | 扩大可能引入误用 |
| 输入字段是否变更 | 下游自动化是否同步 |
| 工具调用是否新增 | 安全评审是否覆盖 |
| 质量阈值是否变化 | 发布门槛是否仍成立 |
测试策略：从人工到半自动
最低限度（个人/小团队）
- 选 3～5 条代表性用例，按 Skill 逐步执行，记录是否满足 checklist。
进阶（团队）
- 把输入输出做成 JSON fixture，用脚本校验输出 schema。
- 对依赖检索的 Skill，固定 评测集（问题 + 期望证据来源）。
注意：Skill 测试的是「流程是否可执行」，不是「模型每次回答都完美」；后者属于模型评测范畴。
描述是否「该触发」：单独测一层
Optimizing skill descriptions 强调：description 是多数宿主在发现阶段唯一依赖的触发信号；应用祈使语气（如「在以下情况使用本 Skill…」）、写清用户意图而非实现细节，并准备一批 should_trigger / should_not_trigger 的模拟用户句（含口语、错别字、近义任务）。注意：极简单的单步请求有时模型不用 Skill 也能完成——评测时要区分「描述写得差」和「任务本身不需要 Skill」。
优化描述时建议做 训练集 / 验证集划分，避免把测试句措辞背进 description 造成过拟合；并留意 1024 字符上限。
输出是否「做得好」：用例 + 断言 + 基线
Evaluating skill output quality 推荐在 Skill 目录下维护 evals/evals.json：每条用例包含真实风格的 prompt、期望结果的文字说明，可选固定输入文件；在见过首轮输出后再补充可检查断言（文件存在、JSON 合法、图表轴有标签等）。对比维度建议包括：带 Skill / 不带 Skill（或升级前 / 升级后），并记录耗时与 token，便于权衡质量与成本。
迭代时除断言外，可保留人工扫一眼与执行轨迹（为何走错步骤、是否忽略某条指令），把失败模式反馈回 SKILL.md 修订，而不是只堆更多口号式规则。社区亦有 skill-creator 等自动化辅助工作流可参考。
若要与官网术语一一对应，上两小节即 Optimizing descriptions 与 Evaluating skill output quality 的落地笔记；脚本化工具链（uvx/npx、自包含 scripts/）见 Using scripts；规范索引见 Agent Skills 规范对照与宿主接入。
发布与回滚
建议流程：
- 在分支上修改 Skill，提交 PR。
- Review 通过后合并到主分支。
- 同步到各运行环境（工作区目录、或 Plugin 包版本号）。
- 若线上异常：回滚 Git 提交或恢复上一版
SKILL.md备份。
对于随 Plugin 分发的 Skill，版本与 Plugin 版本绑定（见 插件概念与 manifest）。
权限与审计
- 谁可以改生产 Skill：建议与「能改生产配置」同一权限级别。
- 审计：重大 Skill 变更保留评审记录（PR 描述即可）。