在AI Agent开发中，如何编写稳定可靠的工具描述（Skill）一直是高不确定性环节。开发者往往依赖直觉或反复试错，导致Agent行为飘忽不定。近日，TypeScript领域知名开发者Matt Pocock在其项目mattpocockuk中沉淀的/writing-great-skills指南，已经成为其最常调用的Skill脚本——这套方法将编写AI Skill从“玄学”转向了可拆解、可测试的工程化实践。

其核心理念是过程可预测性：Skill的实现路径应尽量消除随机性，让每次调用都产生一致的行为模式。为了实现这一目标，Pocock首先明确了两种触发机制：model-invoked（模型自动触发）与user-invoked（用户主动调用）。前者通过自然语言描述中的语义匹配来触发，后者则由用户显式指定。description字段在这里不仅是说明文档，更是精确的“触发器”条件——写错一个词就可能导致模型错误唤醒或漏唤醒。

Pocock提出了一套三层信息结构来组织Skill内容：主步骤（核心执行流程）、参考（常见边界场景或备选方案）、外部文件（函数定义、配置模板等）。这种渐进式披露让模型在不同推理阶段按需获取信息，避免一次性输入全部上下文导致注意力分散。每一层都需明确规定完成标准——比如“列出三个候选项”而不是“尝试找到一些选项”，量化可判断的退出条件能有效抑制模型的自动补全冲动。

值得注意的是，拆分Skill的核心原因并非功能解耦，而是控制模型的注意力范围。一个巨型的Skill容易让模型迷失在冗长步骤中，而多个粒度适中的Skill配合精确的description，能让模型像执行有限状态机一样逐步推进。Pocock还引入了leading word技巧：在步骤开头使用特定动词（如“Compute:”“Validate:”“Output:”）压缩行为要求，类似于指令的元标记，帮助模型快速定位当前动作类型。

除了正向构建方法，指南还系统归纳了五种典型失败模式：
– Premature completion：模型在未完成全部步骤时提前结束，通常是因为完成标准模糊或上下文过长导致注意力漂移；
– Duplication：多个Skill功能重叠，模型随机选择或各执行一部分，造成行为冲突；
– Sediment：历史调用的残余信息污染当前执行，如缓存了错误的中间结果；
– Sprawl：Skill规模膨胀，嵌套过多分支，模型难以在推理中保持完整路径；
– No-op：指令无法产生实际效果，模型执行后无任何行为变化。

尤其值得关注的是No-op测试：通过检查每一条指令是否能引发可观察的状态变化来判断其有效性。如果删除某条指令后Agent行为不变，则该指令属于无效冗余。这种测试方法为Skill维护提供了可量化的质量门槛。

对AI Agent开发者而言，这套方法论的价值在于将调试从“猜模型在想什么”转变为“检查工程结构是否符合原则”。未来，随着模型能力接近天花板，围绕AI系统的工程化手段将成为竞争主战场。无论是个人开发者还是团队项目，借鉴Pocock的思路——从触发设计、信息分层到失败模式排查——都能让自定义工具行为更稳定、更可预测。