最权威的Skills编写指南来了！33页，Anthropic亲自发布

如今龙虾爆火，Skills的推出功不可没。

怎样写好Skills，让龙虾真正为你做事，而不只是玩玩？

Skills的创造者，Anthropic发布了33页的《Skills编写完整指南》。

Skills为智能体注入专属行业经验与标准工作流，能大幅降低沟通成本并实现复杂任务的自动化运转。

通过编写结构化的Skills文件，可以把人类的专业知识与系统的工具调用能力无缝结合。

这份指南，系统梳理了Skills文件的技术规范与编写逻辑，带你完整走过从需求构思到测试发布的全生命周期。

定制专属Skills的核心逻辑

Skills本质上就是一个包含了特定指令的简单文件夹。

它负责教导智能体如何处理特定的任务或工作流。定制Skills是满足特定业务需求最有效的方法。

你可以通过一次性的Skills教导让智能体长久受益。不需要在每次对话中反复解释你的偏好、流程和领域专业知识。Skills在处理可重复的工作流时尤为强大。

这些重复性工作可以是根据规格说明生成前端设计图，或采用一致的方法论进行市场调研，或按照团队的样式指南创建文档，或编排多步骤的业务流程。它们能够与智能体内置的代码执行和文档创建能力完美配合。

Skills采用了三层渐进式的信息披露系统来优化运行效率。

顶层是包含基本信息的配置文件。这部分内容会始终加载到智能体的系统提示词中。

它只提供最基础的信息，让智能体知道何时应该触发对应的Skills。这种设计避免了把所有细节一股脑塞进上下文里。

中间层是Skills的主体说明文件。只有当智能体判定当前任务与该Skills高度相关时才会加载这一层。主体文件包含了完整的执行指令和工作指导。

底层则是打包在Skills文件夹中的其他关联文件。

智能体可以根据实际任务的需要自行选择导航和发现这些底层参考资料。这种渐进式的设计在保持专业深度的同时最大限度地减少了系统资源的消耗。

智能体具备极强的可组合性能够同时加载并运行多个Skills。

你开发的Skills应该具备与其他能力和谐共处的设计考量。

Skills还具备高度的可移植性。无论是通过网页端界面还是各类开发工具或是API环境创建一次即可在所有平台通用。

对于构建了MCP集成的开发者来说Skills加上连接器能够发挥出巨大的威力。可以把MCP想象成一个设备齐全的专业厨房。它为你提供了各种先进的厨具、新鲜的食材和基础设备。

Skills则是一份详尽的菜谱指南。它提供了一步步的指导教你如何利用厨房里的工具做出一道真正有价值的美味佳肴。两者结合就能让普通用户在无需摸索每一个执行细节的情况下完成极其复杂的任务。

下面这张表格清晰地展示了MCP与Skills之间的协同运作关系。

没有Skills引导的情况下用户连接了服务却往往不知道下一步该干什么。这会产生大量关于如何使用集成的客服咨询。每次对话都得从零开始设定背景导致输出结果参差不齐。

有了Skills的加持预设的工作流会在需要时自动激活。每一次交互都内嵌了最佳实践指南。这极大降低了用户学习和使用复杂集成的门槛。

构思设计与编写规范化Skills

动手写代码之前需要先明确两到三个Skills需要实现的具体用例。优秀的用例定义包含清晰的触发条件和步骤。还要有明确的预期结果。

日常应用中存在三种最常见的Skills用例类别。

第一类是文档与资产创建。用于输出高质量的演示文稿、应用程序设计图或代码等一致性内容。

这类Skills通过内嵌样式指南和品牌标准来实现高质量输出。它们不需要外部工具仅依赖系统内置能力即可完成任务。

第二类是工作流自动化。这类用例适用于需要多步骤协调的复杂流程。通常包含带有验证网关的步骤指引以及内置的审核和改进建议机制。

第三类是MCP功能增强。它通过编排多个连接器调用顺序，并嵌入领域专业知识来提升原始工具箱的实用价值。

在明确用例后还要定义清晰的成功衡量标准。量化指标可以设定为在相关查询中达到90%的自动触发率。也可以设定为整个工作流中API调用零失败。

定性指标则体现在用户不需要人为引导提示，且工作流无需人工纠错即可顺畅跑通。

Skills的具体实现需要遵循严格的目录与文件规范。

下面是一个标准的Skills文件夹结构示例。

Skills文件夹的命名必须使用小写字母加连字符的格式。严禁包含空格、下划线或大写字母。文件夹内必需包含一个严格命名为SKILL.md的文件。

主文件内绝不能再放入常规的自述文件。所有的指导说明都应当写在主文件或参考目录中。SKILL.md的头部需要使用YAML(一种直观的数据序列化格式)编写核心元数据。

下面是满足最低要求的头部信息格式标准。

文件开头的这部分内容决定了智能体是否会调用你的Skills。

名称字段必须与外部文件夹名称完全保持一致。描述字段的字数要求控制在1024个字符以内并且绝对不能包含XML(可扩展标记语言)尖括号符号。

由于这部分数据会直接注入系统的底层提示词中，严格的安全限制能有效防止恶意指令注入。

描述不仅要讲清楚Skills是干什么的，更要包含用户可能会使用的确切触发短语。

下面展示了几组优秀与糟糕的描述对比。

紧接着头部元数据的是使用Markdown编写的正文说明。正文需要为智能体提供清晰的操作指南。

下面是推荐的正文结构模板。

编写指令时务必做到具体且具有强行动导向。需要明确指出操作失败时的常见排查方向。

下面是一组指令编写的正确与错误示范。

当指令涉及繁杂的连接失败处理，或限流准则时应当把细节转移到独立的参考文件中。

正文只需保持对核心逻辑的关注即可。这就是渐进式披露原则在文档结构上的具体体现。

迭代与问题排查的系统方法

Skills的测试严谨度取决于你的实际应用场景。

供极少数内部成员使用的Skills，和面向成千上万企业用户的Skills有着截然不同的质量验收标准。

轻量级测试可以直接在对话界面手动输入查询来观察表现。

自动化测试则通过代码编辑器的集成环境运行标准测试用例。

最严谨的做法是基于API构建完整的评估套件进行系统性回归测试。

开发初期建议集中精力攻克单一的复杂任务。观察智能体在哪种表述下能够成功执行。提取出这套制胜逻辑后再扩展到更广泛的测试面上。

科学的测试通常覆盖触发准确性、功能完备性和性能对比三个维度。

触发测试的目标是确保Skills该来的时候来，不该来的时候绝不打扰。

下面是一个标准的触发测试用例库配置。

功能测试用于验证Skills执行后能否产出绝对正确的结果。

这包括确认所有的网络请求都已成功返回且异常捕捉机制正常运转。

下面是功能验证的常规写法。

性能对比测试则用来证明开启Skills确实比人工干预提升了效率。

基准对比清晰地展现了优化前后的资源消耗差异。

下面是一组典型的优化前后对比数据。

官方提供了一个名为skill-creator的辅助工具来加速开发过程。

它可以根据自然语言描述自动生成结构正确的配置文件，并提供触发短语建议。

它也能帮你审视已有Skills的过度触发风险或结构性缺陷。

Skills是需要不断吸收反馈的活文档。

如果发现Skills该启动时没有启动这就是触发不足的信号。

解决方法是在描述中加入更多带有专业术语的细节和细微差别。

如果遇到用户总是想把它关掉，或者抱怨它莫名其妙跳出来这就是过度触发。

需要补充明确的负面排查词汇使边界更清晰。

下面是添加了负面触发条件的代码示例。

当遇到配置无法上传的系统报错时，多半是因为主文件没有严格命名为SKILL.md。

也可能是文件头部格式出了问题。

下面列举了常见的格式错误与正确写法对照。

如果Skills加载了但没有遵循你的步骤走，多半是因为指令过于啰嗦或重点被埋没在了大段文字中。

使用清晰的要点符号并把最关键的指令置顶。

对于涉及严苛格式校验的环节，最好编写一段确定性的验证代码，而不是依赖自然语言的模糊理解。

由于系统偶尔会表现出偷懒的倾向，你可以在文件末尾加上明确的鼓励性话语。

这种心理暗示往往能带来意想不到的执行效果。

下面是防止偷懒的提示语写法。

随着Skills体量增大可能会遇到响应速度下降的问题。

这就需要把超长的主文件拆分，并通过链接转移到参考目录中去。

时刻保持启用的Skills组处于精简状态。

早期开发者和内部团队在实践中探索出了五种极其好用的编排模式。

第一种是串行工作流编排模式。适用于要求步骤前后存在严格依赖关系的业务。

第二种是多端协同编排模式。它主要应对跨越多个独立服务的复杂协作。核心在于划分清晰的阶段并集中处理各服务间的数据交接。

第三种是迭代式优化模式。适用于文档生成等需要反复打磨才能达标的任务。关键在于设置明确的质量验证脚本和退出循环的阈值。

第四种是情境感知分发模式。目的是实现同样的目标但会根据具体情况智能选择最合适的工具。这种模式能极大地提高工作流的灵活性。

第五种是领域智慧注入模式。这超越了单纯的工具调用层面，把特定的行业常识和合规审查前置到了业务操作之前。下面是以金融支付为例的审查模式代码。

封装发布与多场景分发的标准流程

完善的Skills，可以让你的集成方案在众多同类产品中脱颖而出，给用户带来最快获得价值的捷径。

目前个人用户主要通过下载打包好的文件并手动上传至系统设置中来使用。

企业管理员则能够将测试稳定的Skills直接推送到整个组织的工作空间，实现集中化的版本管理与无感更新。

智能体Skills已经被官方确立为一项开放的标准规范。

同一套优秀的Skills代码，应该可以在各种不同的智能体平台上顺畅运行无缝迁移。

针对开发者构建自动化流水线的需求官方开放了专门的接口服务。

开发者可以通过代码请求列出、管理并直接执行这些Skills从而编排出更为庞杂的业务网。

下面这张表格，梳理了在不同场景下应该使用界面操作，还是代码调用的决策建议。

现阶段最推荐的分发做法是把Skills开源托管在平台上。

维护一份清晰干练的面向人类读者的安装指南。

配合实际运行成功的界面截图能大大降低新手的尝试门槛。

如果你已经有了一个业务集成的代码库，要在里面单独开辟一个章节解释将两者搭配使用的奇效。

下面是一份极其直观的标准安装指南编写示范。

除了技术层面的连通，如何向公众宣发和定位你的成果，同样决定了它的生死存亡。

在对外介绍时千万不要堆砌枯燥的技术名词，而是要直击用户能获得的具体成果。

一份糟糕的介绍往往像是一本毫无感情的字典，只强调文件里写了什么代码。

优秀的介绍，会直接告诉团队这套方案能在几秒钟内搭建好原本需要半小时才能弄完的基础设施。

宣发故事应当死死绑定工具连接加Skills赋能的双剑合璧理念。

告诉市场冰冷的工具加上温暖的专业流程沉淀，最终孕育出的是一个全自动的强力业务管家。

Anthropic这份全景式的技术指南，能帮你轻松驾驭智能体的工作流改造。

参考资料：

https://claude.com/blog/complete-guide-to-building-skills-for-claude