Agent Skill 更适合承担执行契约，而非压缩版教材。它应告诉 Agent 何时使用、按什么顺序行动、看到什么信号才算完成，以及失败后如何恢复。一篇 2026 年预印本整理了 8135 条受控实验记录，为这个判断提供了少见的机制证据。同时，论文也提醒我们收窄结论：Skill 相比原始工作记录的优势较稳健，相比完全不给经验的裸 Agent，整体优势较小且统计区间跨过零。
真正值得迁移到工程实践的，是这组证据背后的 Skill 设计方法。
8135 条记录究竟是什么
研究覆盖 Terminal-Bench 2.0、SkillsBench 和 Terminal-Bench-Pro，并使用 Codex 与 Gemini CLI 的若干模型组合。同一批历史轨迹被组织成三种实验条件：
| 条件 | Agent 得到的历史经验 | 要验证的问题 |
|---|---|---|
| Raw | 没有注入历史经验 | 裸 Agent 基线 |
| Workflow Memory | 清洗后的轨迹式记录 | 直接复用历史过程是否有效 |
| Skill | 从同一批轨迹提炼的 SKILL.md |
程序化表示是否更有效 |
8135 指标准化后的完整记录清单。机制分类使用了其中 240 条开放编码样本，最终保留 238 个有效标签。三组条件的核心对照包含 528 个配对三元组，共 1584 个条件级分类。人工复核确认了 238 个标签的轨迹依据，并在分类映射上与 LLM 达到 95.8% 的一致率。
因此，8135 是证据底座规模，并非逐条人工标注数量。这个口径决定了文章可以声明什么。
最稳健的结论是 Skill 胜过流水账
528 个配对三元组的结果如下：
| 条件 | 528 条代表轨迹的验证结果成功率 | 代表轨迹被归入超时预算耗尽模式的比例 |
|---|---|---|
| Raw | 59.1% | 1.7% |
| Workflow Memory | 55.9% | 10.6% |
| Skill | 61.9% | 4.4% |
Skill 比 Workflow Memory 高 6.06 个百分点，95% bootstrap 置信区间为 +0.76 至 +11.36。Skill 比 Raw 高 2.84 个百分点，但置信区间跨过零。换成工程语言：把同一批经验提炼成程序化指南，效果显著优于把清洗后的历史过程直接塞给 Agent；现有数据尚不足以支持每个 Skill 都能普遍提升每个 Agent。表中的超时比例来自每个任务设置条件选取一条代表轨迹后的描述性分类，不能外推为 8135 条记录的全局超时率。
Workflow Memory 已经经过清洗和结构化，但仍比 Skill 保留更多过程流、探索路径、死胡同、任务特有细节和调试噪音。这些残留可能消耗注意力与超时预算。论文附件中的平均运行时并未显示 Workflow Memory 普遍比 Raw 更慢，因此 10.6% 只能解释为某类代表轨迹更常撞上预算上限。
65.7% 的程序锚定，对比 4.5% 的知识注入
528 个 Skill 条件的机制标签中，347 个被归为程序锚定，占 65.7%；24 个被归为知识注入，占 4.5%。另有 87 个被归为反效果，64 个被归为失败警告。这些是对代表轨迹进行 LLM 辅助分类的机制标签，不能解释成 8135 条记录的因果贡献率。论文中的程序锚定包括：
- 环境准备和依赖顺序；
- 工具、命令与操作序列；
- 中间检查点；
- 输出格式和验收要求；
- 已验证的陷阱与恢复动作。
描述性差异主要集中在执行层。环境与基础设施错误标签从 Raw 的 5.3% 降至 Skill 的 0.2%，输出格式错误标签从 7.4% 降至 3.2%，后台服务生命周期错误标签从 2.7% 降至 0.8%。
Skill 对新推理问题的帮助有限。算法逻辑错误只从 8.3% 变为 7.4%，缺少运行时检查的静态验证错误只从 12.5% 变为 11.7%。操作指南能稳定已知动作；任务拆解、算法设计、适用性判断和正确标准仍处在契约与判断层。
这与此前的动态任务评测框架正好衔接：Skill 的质量要用外部状态与最终验收衡量，文档看起来完整本身没有证明力。
一份有效 Skill 应包含六类内容
一、用任务形状定义触发条件
描述输入、目标和约束，同时写清相邻场景该走哪条流程。模糊的适用范围会制造误用。论文中 Skill 组有 10.0% 的轨迹出现指南被误用或忽略。
较弱的写法是用于部署。更有效的写法是：用于从固定构建命令发布静态站点，并以公开 URL 的 HTTP 状态验收；涉及容器镜像或数据库迁移时改用容器发布流程。
二、把前置条件写成可观察状态
列出文件、权限、凭据、工具版本与外部状态，并尽量给出检查命令。command -v jq 是可执行前置条件，解释 jq 的历史通常只是背景材料。
三、保存动作顺序，删除探索流水账
保留命令、决策点和依赖关系。只有当一次失败暴露了可复用边界时，才把它沉淀为陷阱。Fabien Sanglard 的 agent.md 提供了一个现场样本：他把反复出现的代码审查意见直接写成约束，减少跨会话重复沟通。这是一份工程经验，能够支持机制的合理性，无法替代论文的受控因果证据。
四、每个高风险动作都配一个验收信号
启动服务后检查 readiness，修改文件后看 diff 或运行解析器，发布后访问公开 URL。验证需要贴近动作，成为 Agent 可以读取的接口。
五、从轨迹提炼时保留成败标签
成败标签能向 Skill 编写者说明哪些路径值得保留。在 Gemini 的 Terminal-Bench-2 一个 3 次成功、2 次失败的条件里，带结果标签生成的 Skill 得分为 0.7462，隐藏结果标签后为 0.4000。不同基准和模型的结果存在差异，Gemini Terminal-Bench-Pro 的部分混合条件反而由隐藏标签组得分更高。因此，标签应作为可追溯证据保留，并用下游任务验证，不能被当作自动提升 Skill 的保证。
task_shape: publish-static-site
outcome: failed
verifier: public_url_http_200
failure_phase: dns_propagation
reusable_lesson: verify_origin_before_cdn
六、写出恢复路径与最终复验
Agent 需要知道何时停止、当前安全状态是什么、从哪份输出继续检查，以及修复后必须重跑哪个验收。做到这一步，一组命令才演化为闭环。
Skill 库扩大后，重点是语义卫生
候选池从 5 个增加到 100 个时，执行过程中访问到 SkillsBench 标注标准答案的平均精确率从 29.6% 降至 3.3%，最终任务成功率则从 36.4% 变为 39.3%。论文没有报告这段成功率变化的显著性。召回率保持更高，因为 Agent 往往同时查看多个 Skill。在该基准的标注口径下，准确命中标准 Skill 既不是成功的充分条件，也不是必要条件：相关 Skill 也可能提供有用步骤，正确 Skill 也可能被机械套用。
Skill 库治理应聚焦五件事：
- 每个 Skill 只承担一个操作责任。
- 描述字段写任务形状与排除项。
- 合并功能重叠的流程。
- 清理过时的环境假设。
- 分开评测检索质量与任务完成质量。
若同一份 Skill 需要运行在多种 Coding Agent 上，还要处理内容、发现、调用与运行时四层差异。具体方法可参考Agent Skills 跨工具兼容模型。
先判断这条规则应该放在哪里
程序锚定并不意味着所有检查单都应该写进 Skill。规则的适用范围与执行方式决定了承载位置。
| 内容类型 | 更合适的控制面 | 原因 |
|---|---|---|
| 在一个仓库的几乎所有任务中都适用 | AGENTS.md 或同类项目指令 |
常驻上下文与普遍适用范围一致 |
| 可确定性检查的格式、类型或策略约束 | Linter、测试、Schema 或 CI | 可执行约束比文字提醒更可靠 |
| 带工具、分支、检查和恢复的特定任务流程 | 按需加载的 Skill | 只在任务形状匹配时加载操作契约 |
| 大量领域事实、API 清单与示例 | 引用文档或检索系统 | 保持默认流程聚焦，同时保留知识入口 |
| 暂时无法自动检查的人类偏好 | 项目指令与审查标准 | 先显式表达，成熟后再转为可执行控制 |
Fabien Sanglard 的常驻 agent.md 主要保存仓库级编码偏好，其中一部分适合项目指令，格式与可见性规则还可以逐步转成 Linter 或 CI。部署、故障恢复等边界明确的流程更适合按需 Skill。这个判断可以避免把所有上下文都重新命名为 Skill。
十分钟审查现有 SKILL.md
把每一段标成动作、决策、验证、恢复、事实或轶事，然后逐项处理：
- 只保留会改变动作、阈值、工具选择或验收的事实。
- 把模糊建议改成可观察动作。
- 把验证移动到它所验证的动作旁边。
- 删除只用于记录探索过程的时间线。
- 为最容易混淆的相邻 Skill 添加排除条件。
- 让每个已知陷阱指向真实失败或外部来源。
- 在冻结任务集上记录成功率、超时、人工介入和误用率。
目标是得到能够反复完成闭环的最小操作契约，而非追求最短文件。
证据边界
这项研究是 2026 年 8 月 14 日提交的 arXiv 预印本。实验集中在终端与工具调用、调试和验证任务，覆盖的 Agent 与模型组合有限。它没有测试长周期网页交互或开放式多 Agent 协作。受控轨迹池还筛选了 Raw 条件中同时出现成功与失败的任务，因此结果面向测试 Agent 本身表现不稳定的任务。机制分类样本约占标准化记录的 3%，完整三元组分类仍由 LLM 辅助完成，虽然分类体系接受了独立人工复核。
更稳妥的落地方式是：先用自己的固定任务集验证这份检查单，再把它推广成组织标准。
常见问题
AGENTS.md 与 SKILL.md 分别放什么？
普遍适用的仓库规则放入 AGENTS.md。具有明确触发条件、工具、决策、验证与恢复的流程放入 Skill。能够确定性检查的规则优先转成 Linter 或测试。
Agent Skill 可以包含领域知识吗？
可以。领域知识需要改变动作、阈值、工具选择或验收。纯背景材料适合放入按需检索的参考文档。
原始 Agent 轨迹还有价值吗？
有。它适合调试、审计和提炼 Skill。执行时直接注入长轨迹会增加过程噪音与超时风险。保留原始证据，标注结果，再把可复用步骤提炼进 Skill。
检查单会削弱 Agent 推理吗？
检查单稳定已知执行。新问题拆解、算法设计、适用性判断和正确标准仍需要推理。
团队怎样衡量 Skill 质量？
冻结一组真实任务，比较最终验证器通过率、超时率、人工介入、Token 成本和误用率。检索命中率单独统计。
SKILL.md 多长合适？
长度属于次要指标。文件需要完整表达触发条件、前置状态、动作顺序、检查、失败边界与恢复。可选背景可拆到引用文档。
参考资料
- Jiang 等，Demystifying Agent Skills: Why They Work Until They Don't，2026 年 8 月 14 日提交的 arXiv 预印本。
- 论文完整 HTML 版本。
- Fabien Sanglard，My agent.md to improve LLM-assisted code quality，2026 年 8 月 21 日。
- 鸭哥，Skill 不是教材，是检查单，作为发现线索和二级解读进行对照。