别把 Skill 和 Agent 写成屎山

Skill 和 Agent 很容易越写越强，也很容易越写越乱。真正让它们变成“屎山”的，通常不是文件太多，而是触发条件、职责边界和维护方式同时失控。

这篇文章记录我的一套整理方法：先找到可靠的学习渠道，再分清 Skill、Agent、AGENTS.md 和工具各自负责什么，最后建立能维护、能验证、能扩展的协作方式。

一、整理学习渠道：别把二手经验当规范

AI 工具更新很快。只看零散教程，最容易把某个版本的技巧误当成长期规则。我的学习顺序会固定成四层：

1. 官方文档：先确认术语、目录结构、加载方式和限制。优先阅读 Skills 概念、Skill 编写指南、AGENTS.md 与 多智能体。
2. 官方示例和成熟项目：观察别人如何拆分 SKILL.md、references、scripts 和 assets，但不要只复制目录外形。
3. 团队现有约定：仓库里的 AGENTS.md、已有 Skill 和真实开发流程，比“最佳实践”更接近当前项目。
4. 失败记录：误触发、漏触发、编造参数、改坏旧流程，这些失败才是下一轮维护最有价值的输入。

二、理解概念：先分工，再写文件

很多混乱来自把四种不同层级的东西揉在一起。我的简单判断是：流程写进 Skill，角色交给 Agent，约定放进 AGENTS.md，能力接到工具或 MCP。

Skill 不是“万能提示词”，Agent 也不是“把所有工具都装进去的超级机器人”。前者应该像一本边界清楚的操作手册，后者应该像一个职责明确的同事。

三、怎么维护自己的 Skill

我会先写契约，再写步骤。最小的 SKILL.md 至少要回答：谁会触发它、输入是什么、成功结果是什么、哪些事实不能猜、何时询问用户、何时停止。

---
name: review-skill
description: 当用户要求评审一个 Skill 时使用，检查触发、边界与可维护性。
---

1. 读取目标 Skill 和直接引用的资料
2. 检查输入、输出、停止条件
3. 用正例、反例和缺失输入测试
4. 输出问题、风险和最小修改建议

维护时我重点守住五件事：

• 单一目标：一个 Skill 对应一个可识别的用户目标。触发条件、输入或成功标准明显不同，就拆开。
• 描述负责触发：描述写“何时使用”和“解决什么”，不要只写一段空泛介绍。
• 渐进加载：SKILL.md 保持短而清晰；长资料放 references，模板放 assets，确定性的重复处理才放 scripts。
• 明确停止条件：缺少关键输入、涉及新权限、结果无法验证时，必须知道要询问还是停止，不能靠猜。
• 用案例回归：至少测试直接触发、间接触发、输入不全、不该触发和边界情况。

四、怎么维护别人的 Skill

维护别人的 Skill，要把它当成一套已经有人依赖的接口，而不是一篇等待我重写的作文。

1. 先读 description 和输出契约，确认它对外承诺了什么。
2. 用真实案例复现问题，区分是触发错误、流程错误，还是底层工具失败。
3. 做最小修改，避免顺手改写无关目录、命名和输出格式。
4. 把这次失败补成回归案例，确认旧的正确场景仍然可用。
5. 如果必须破坏兼容性，清楚记录变化、迁移方式和影响范围。

五、高阶用法：让 Skill 和 Agent 分层协作

当任务变复杂时，我更愿意让主 Agent 保留目标、决策和最终验收，再把独立、边界清楚、能够并行的工作交给子 Agent。

• 资料研究 Agent：只核对官方文档和来源。
• 仓库探索 Agent：只定位文件、依赖和影响范围。
• 实现 Agent：只完成一个明确改动，并返回验证结果。
• 审查 Agent：只找风险、回归和遗漏，不顺手重写实现。

这里的关键不是 Agent 越多越高级。读多写少、互不依赖的任务适合并行；多人同时修改同一片代码，往往只会制造冲突和额外协调成本。Skill 可以负责规定协作顺序，Agent 负责执行其中一个有边界的角色。

最后：五个问题判断它是不是屎山

• 我能不能用一句话说清它何时触发？
• 输入、输出和成功标准是否明确？
• 修改一个流程时，会不会意外破坏其他流程？
• 它是否知道什么时候询问、停止或拒绝猜测？
• 每次失败，能不能沉淀成下一次的测试案例？

文件越多不代表越专业，能力越强也不代表越可维护。真正可靠的 Skill 和 Agent，靠的是清楚的边界、稳定的契约，以及持续从失败中更新的方法。