技能介绍

为什么你的 Agent Skill 经常“翻车”？

在构建 Agent Skill 时，开发者常遇到一个隐性问题：不可预测性。同一个 SKILL.md，这次 agent 完美执行，下次却提前结束或偏离预期。这通常源于六类典型失败模式：步骤缺乏明确的完成判据导致过早完成；description 里堆砌同义触发词造成分支重复；主文件过长引发上下文污染；充满 "be thorough" 这类模型默认遵守的废话（no-op）；用禁令反而强化了禁项（negation）；以及随时间堆积、只加不减的沉积层（sediment）。

六维体检与改造工作流

本技能基于 Matt Pocock 的 writing-great-skills 元方法论，将抽象的“写好 skill”拆解为可执行的审计与重构流程。核心工作流如下：

逐条对照清单：扫描目标 SKILL.md 及 references/ 子文件，检查上述 6 类失败模式。
自动化基线扫描：推荐运行 python3 scripts/check.py path/to/SKILL.md，获取 0–100 的体检分与命中清单，作为人工审查的对照基线。
针对性重构：为每个工作流步骤补充 ✅ 完成判据（如“文件存在”、“全部项处理完”）；合并冗余触发词，遵循 one trigger per branch；将非每次必读的速查表或边界说明渐进式披露到 references/ 中；删除 no-op 与无效 negation，替换为紧凑的 leading words（如 reusing）。
版本与交付：修改后进行语义化版本升级（version bump），使用 conventional commit 规范提交，并生成一份包含对象表与推送结果的体检报告。

适用边界与注意事项

该技能并非万能的自动修复工具，而是一个结构化的质量门禁。自动脚本仅提供基线分数，最终的判断仍需依赖开发者对业务逻辑的理解。此外，重构过程要求严格遵守渐进式披露原则，切忌将所有内容塞入主文件。对于包含核心安全护栏（如“绝不泄露 API key”）的否定句，应当予以保留，不可盲目替换为正向表述。