前言这篇文章是写给已经写过 Skill或者正打算写自己的 Skill 的读者的。如果你已经写过 Skill并且真的在实际环境里测试过可能会和我一样遇到下面这些困惑我觉得我已经写得很清楚了为什么运行起来没有按预期工作我觉得 Skill 的触发条件已经描述得很清楚了但为什么完全没有被 Agent 调用为什么 Skill 的运行结果不稳定时好时坏为什么别人的 Skill 看起来写得挺简单的但效果不比我写的差甚至效果更好呢问题往往不在于你有没有认真写而在于你对“什么才算高质量 Skill”的判断一开始就可能错了。下面这 3 个误区几乎是每个 Skill 作者一开始都会遇到的常见问题。误区 1以为自己已经写清楚了其实关键上下文根本没写出来Skill 本质上是把某件事的最佳实践写成文档甚至进一步程序化。当我们写 Skill 的时候自己对要解决的问题上下文往往是很清楚的。在我们脑海中我们知道这个问题的背景是什么用户是谁他们需要什么哪些做法在真实场景里可行哪些做法不可行。我们需要的只是一个可执行的方案于是我们写出来的SKILL.md很多时候关注的主要是“怎么做”。但 AI 模型不是人类不会自动帮你补上下文也无法理解你特定需求场景下的约束。所以很多 Skill 在第一次测试时就会暴露出各种问题。比如触发条件写得很泛导致模型在不该触发的时候也触发或者该触发的时候却没有触发没有明确的步骤执行说明和分支跳转逻辑只告诉 Agent 要做什么但对输出缺乏模板化的约束输出要求看似完整实际上缺少验收标准这些问题在你自己阅读时不一定明显。但一旦进入真实使用场景它们就会直接影响结果稳定性。经验一份好的SKILL.md一定有清晰稳定的结构尽量减少模型产生幻觉的空间。误区 2以为 Skill 写得越长效果就越好另一个很常见的误区是文档越长Skill 就越专业。这其实不一定。过去我写 Skill 时很喜欢把一些专业背景知识写进SKILL.md。例如某个指标的含义、某些专业名词的解释、某些行业的最佳实践。直到我看到了 Claude 官网的一篇文章 Skill authoring best practices。这篇文章的第一条原则就是“简洁至上”。对于很多公开知识我们应该假设大模型已经学过不需要再在SKILL.md里重复解释。把这些大模型已经懂得、甚至可能比人更熟悉的知识写进SKILL.md往往是一种浪费。因为每次 Skill 被加载后过长的内容都会占用上下文窗口也会大大增加 token 消耗的成本。其次如果SKILL.md写得很长往往是因为要解决的任务本身比较复杂存在多种分支于是作者想在一个文档里把所有情况都写进去。但最佳实践通常是拆分。也就是说我们在SKILL.md中只描述解决问题的思路框架具体的多分支执行逻辑可以拆分到其他文档中按需引用。所以SKILL.md的长度并不是越长越好当然也不是一两句含糊不清的指示。先抽取框架再在参考文档中补充实现细节这种写法需要持续训练。误区 3以为 Skill 能跑起来就说明它已经没有问题了很多 Skill 作者都会有一种很自然的判断我已经让它成功运行过几次了说明这份 Skill 应该已经没有太大问题了。但“能跑起来”和“写得够好”其实是两回事。一个例子就是前面的第二个误区。同样完成一个任务别人的SKILL.md比你写得更精简占用的 token 更少那么对方的运行效率就会比更高成本也会更低。另外一个例子就是分析类的 Skill。我写过一个简历分析的 Skill专门用来帮我分析候选简历中各方各面的信息帮我判断候选人与岗位的匹配度。这个 Skill 很快就跑起来了但很快我就发现问题了每次输出的判断框架、判断标准、展示模板都不一致。这就是“能完成任务”和“能稳定交付”之间的区别。前者只是能用后者才更接近可持续复用、可稳定维护的质量水平。SKILL.md虽然是一个文本文件但它本质上是一个指导 Agent 运行的思考框架。如果我们希望 Skill 能够在多种场景下稳定运行就需要像对待程序一样对待它约束 Skill 的输出尽量保证每次的交付质量都维持在相同的水准。让 Skill 在多种不同场景下反复测试和优化再对外发布。我的建议在发布你的 Skill 前做一次专业的体检如果有一个工具能够帮我们在发布 Skill 前做一轮完整检查找出这份SKILL.md哪些地方做得好、哪些地方还可以改进是不是就能帮我们更早发现问题并减少后续返工这就是我做 bestskills.dev 这个网站的原因。最近我刚刚发布了一个新功能对一份SKILL.md进行全面的质量审计通过 63 项检查为你生成一份结构化报告。这 63 项检查指标涵盖了下面 4 个大的领域规范例如 Frontmatter 的内容是否规范这直接关系到你写的 Skill 会不会被加载。很多人容易忽略这部分。效果从各种维度评估这个 Skill 能否满足作者的目的能否交付出一个高质量的效果。安全帮助 Skill 的作者和使用者判断这个 Skill 是否存在风险操作并且对风险进行分级提示。精简SKILL.md文档的简洁性非常重要它会直接影响每次运行时的上下文占用和调用成本。我想说的是写 Skill 虽然带有很多个人经验但评估一份 Skill 的质量仍然可以依据一组相对客观的标准。规范我们做了 24 项检测效果我们做了 21 项检测安全我们做了 10 项检测精简我们做了 8 项检测最终我会给一份SKILL.md打一个分。满分是 100 分。每个分数区间对应一个建议90 - 100 分优秀可直接使用或发布70 - 89 分良好仍有少量但实际存在的优化空间50 - 69 分一般需要重要修订50 分以下不合格需要大幅重写比分数更重要的是分数是一个客观的数字但比分数更重要的是我们从这份评测报告中学到了什么我们能从别人的SKILL.md审计报告中学到哪些解决问题的思路如果换成我们来写这份SKILL.md要怎样才能做得更好优秀的SKILL.md就像结构良好的代码读起来会让人觉得清晰、顺畅而写得糟糕的SKILL.md往往只会让人感到困惑。如果你也写了 Skill不妨先试一次如果你最近刚写完一个 Skill或者准备把它公开出来我很建议你先做一次简单的质量检查。把SKILL.md地址贴到 bestskills.dev点击体检按钮稍等片刻你会拿到一份带评分和问题定位的体检结果。分数本身当然有参考价值但更重要的是你可以更快知道这份 Skill 到底强在哪、弱在哪还有哪些地方值得补。在发布之前先给它做一次体检也许会帮你减少很多不必要的返工。最后一点这个功能是免费的你不需要支付任何费用。如果你对这个功能有任何建议或抱怨欢迎给我发邮件deepnotes.orggmail.com