很多人写完 Skill 之后会遇到Agent 完全不触发这个 Skill继续用通用能力回答Agent 忘记读取 references生成的内容不符合业务规范模板占位符没有替换成功输出里面残留{{xxx}}scripts 脚本调用失败路径错误、参数传错读取参考文档过多token 暴涨响应变慢甚至截断修改了文件但是 Agent 没有读到最新版本。一、Skill 常见故障排查清单Skill 没有触发检查 SKILL.md YAML 头的 description触发关键词描述是否清晰是否存在其他 Skill 优先级更高、抢占了当前场景检查 Skill 名称是否符合命名规范小写横杠分隔不要中文。忘记读取 references 文件SKILL.md 的步骤里必须显式写读取文件动作确认文件相对路径正确区分大小写不要一次性强制读取大量参考文档。assets 模板渲染失败占位符残留检查占位符写法前后保持一致确认所有占位变量都收集到用户输入模板内不要混入复杂判断逻辑。scripts 脚本调用报错检查文件路径、脚本执行权限入参格式是否符合脚本要求优先本地测试脚本确认脚本单独运行正常再交给 Agent 调用。上下文超限、响应慢按需读取不要一次性加载全部 references拆分大文档为多个小文件精简 SKILL.md 正文。二、Skill 工程最佳实践命名规范Skill 名称小写字母 横杠分隔例如meeting-minutes禁止中文内部文件命名尽量英文减少跨平台路径问题。版本管理--- name: weekly-report version: 1.0.0 author: demo description: 根据用户提供的工作内容生成统一周报。当用户说“写周报”时使用。 ---在 SKILL.md YAML 头增加version、author方便迭代追踪。能力复用原则通用能力抽成独立 Skill多个 Agent 可以共用业务专属规则放在 references方便业务人员修改不用改动执行逻辑。最小可用优先先实现最简可用版本只保留 SKILL.md需要再追加 references /scripts/assets避免一开始过度设计。三、测试流程推荐单独测试直接测试触发词确认 Agent 可以命中 Skill单模块验证单独测试读取 reference、渲染模板、调用脚本端到端测试完整跑一遍业务流程异常用例测试缺少输入、边界数据看 Skill 能否给出合理提示。小结Skill 的难点不在于写模板和脚本而在于边界控制、模块化权衡和可调试性。优先保证职责单一、流程清晰遇到问题按照上面清单逐项排查大部分 Skill 问题都可以快速定位。