企业官网建设流程全解析

很多人写完 Skill 之后会遇到：

1. Agent 完全不触发这个 Skill，继续用通用能力回答；
2. Agent 忘记读取 references，生成的内容不符合业务规范；
3. 模板占位符没有替换成功，输出里面残留{{xxx}}；
4. scripts 脚本调用失败，路径错误、参数传错；
5. 读取参考文档过多，token 暴涨，响应变慢甚至截断；
6. 修改了文件，但是 Agent 没有读到最新版本。

一、Skill 常见故障排查清单

1. Skill 没有触发
   • 检查 SKILL.md YAML 头的 description，触发关键词描述是否清晰；
   • 是否存在其他 Skill 优先级更高、抢占了当前场景；
   • 检查 Skill 名称是否符合命名规范（小写，横杠分隔，不要中文）。
2. 忘记读取 references 文件
   • SKILL.md 的步骤里必须显式写读取文件动作；
   • 确认文件相对路径正确，区分大小写；
   • 不要一次性强制读取大量参考文档。
3. assets 模板渲染失败，占位符残留
   • 检查占位符写法前后保持一致；
   • 确认所有占位变量都收集到用户输入；
   • 模板内不要混入复杂判断逻辑。
4. scripts 脚本调用报错
   • 检查文件路径、脚本执行权限；
   • 入参格式是否符合脚本要求；
   • 优先本地测试脚本，确认脚本单独运行正常，再交给 Agent 调用。
5. 上下文超限、响应慢
   • 按需读取，不要一次性加载全部 references；
   • 拆分大文档为多个小文件；
   • 精简 SKILL.md 正文。

二、Skill 工程最佳实践

1. 命名规范
   • Skill 名称：小写字母 + 横杠分隔，例如meeting-minutes，禁止中文；
   • 内部文件命名尽量英文，减少跨平台路径问题。
2. 版本管理

--- name: weekly-report version: 1.0.0 author: demo description: 根据用户提供的工作内容生成统一周报。当用户说“写周报”时使用。 ---

• 在 SKILL.md YAML 头增加version、author，方便迭代追踪。

3. 能力复用原则
   • 通用能力抽成独立 Skill，多个 Agent 可以共用；
   • 业务专属规则放在 references，方便业务人员修改，不用改动执行逻辑。
4. 最小可用优先
   • 先实现最简可用版本，只保留 SKILL.md；
   • 需要再追加 references /scripts/assets，避免一开始过度设计。

三、测试流程（推荐）

1. 单独测试：直接测试触发词，确认 Agent 可以命中 Skill；
2. 单模块验证：单独测试读取 reference、渲染模板、调用脚本；
3. 端到端测试：完整跑一遍业务流程；
4. 异常用例测试：缺少输入、边界数据，看 Skill 能否给出合理提示。

小结

Skill 的难点不在于写模板和脚本，而在于边界控制、模块化权衡和可调试性。
优先保证职责单一、流程清晰；遇到问题按照上面清单逐项排查，大部分 Skill 问题都可以快速定位。