CAIE注册人工智能工程师

公众号作者

CAIE，全称 Certifed Artifcial Intelligence Engineer（人工智能工程师），简称 CAIE（赛一） ，是人工智能领域的技能等级认证。旨在评估和培养具备人工智能理论基础与实战能力的职业人士。

为了帮助大家更好的了解、开发Skills，最近Anthropic发布了一份Claude官方开发指南。

这份指南一共分了七大核心模块，还有三份配套的参考清单，从基础原理到最后怎么分发共享，甚至遇到问题怎么排障都覆盖到了。

不管是想做单独的Skills，还是想结合 MCP 做更复杂的工作流，都能在里面找到对应的方法。

指南地址：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

下面【CAIE】就用大白话为大家解读一下这个指南，彻底搞懂Skills。

到底什么是Skills？

你可能见过很多Skills开源，也有人说它多么多么神奇好用，那Skills到底是个啥东西呢？

其实说白了，Skills不是什么复杂的程序，就是一个标准化的文件夹，里面装着让Claude执行特定任务的所有东西。

其中有一个必须有的核心文件叫SKILL.md，用Markdown写就行，里面还要加一点YAML的基础信息，剩下的就是几个可选的文件夹。

比如放Python、Bash这些可执行代码的scripts，放参考文档的references，还有放模板、图标这些素材的assets。

这种结构设计得特别巧，轻量还能随便拓展，也是它能跨平台用的关键。

不管是在Claude.ai网页端，还是Claude Code，甚至是用API调用，同一个Skills不用改任何东西，只要运行环境能满足依赖，就能直接用，这一点能省

设计Skills的三大核心原则

而设计Skills的核心有三个原则，这是所有操作的基础，摸透了这三点，做Skills就不会跑偏。

1. 渐进式披露

说白了就是Claude不会一次性把Skills的所有内容都加载出来，而是分三级来。

最外层的YAML基础信息会一直放在系统里，只告诉Claude这个Skills是干嘛的、什么时候该用，不占太多内存；等Claude判断当前任务需要这个Skills了，再加载SKILL.md里的完整指令；

如果还需要更详细的资料，再去翻文件夹里的其他附属文件。这样既保证了Claude能精准用Skills，又能减少令牌消耗，解决了大模型上下文不够用的老问题。

2. 可组合性

意思就是一个Claude能同时加载好几个Skills，而且这些Skills之间能配合工作。

不用想着自己做的Skills要独一份用，而是要考虑和其他Skills的兼容性，这样企业团队就能把不同的Skills拼起来，做出适合自己业务的复合型工作流，比如把文档创建和项目管理的Skills结合起来，一站式完成工作。

3. 可移植性

这个刚才也提了一嘴，就是跨平台通用，一次创建到处能用，不用为了不同的使用端反复修改，大大提升了Skills的复用价值，毕竟谁也不想做一次Skills，再为了网页端、API端各改一遍。

Skills与MCP的关系

这里还要说一下Skills和MCP的关系，很多朋友会把这两个搞混，指南里用了一个特别形象的比喻，一下子就懂了。

MCP就像是一个专业的厨房，给Claude提供各种工具、原料，让Claude能连接Notion、Asana这些第三方工具，还能获取实时数据、调用工具功能。

而Skills就是菜谱，告诉Claude怎么用这些工具和原料，一步一步做出想要的结果，把工作流和最佳实践都沉淀下来。

简单说，MCP决定了Claude能做什么，Skills则明确了Claude该怎么做。

如果只连MCP不加Skills，就会出现很多问题，比如用户连好之后不知道下一步该干嘛，客服总收到各种使用问题，每次和Claude对话都要从零开始说要求。

因为每个人的提示词不一样，结果也乱七八糟，甚至有人会觉得是MCP连接器不好用。

但配上Skills之后就不一样了，对应的工作流会自动激活，Claude用工具的方式会更稳定，最佳实践也会直接嵌在操作里，用户几乎不用学就能上手，学习曲线直接拉低。

开发Skills，设计环节是关键

做Skills的核心环节在规划和设计，这一步做不好，后面再怎么改都费劲。

指南里反复强调，别一上来就写代码、写指令，先想清楚这个Skills要解决什么实际问题，先定2-3个具体的用例，再开始后续的工作。

这一点真的太重要了，能避免做出来的Skills没用，白忙活一场。

如何定义用例？

定用例也有讲究，不是随便想一个就行，要明确触发条件、执行步骤和预期结果。

比如做一个项目冲刺规划的Skills，触发条件就是用户说帮我规划冲刺、创建冲刺任务这些话，执行步骤要明确先从Linear拿项目状态，再分析团队的工作速度和产能，接着建议任务优先级。

最后在Linear里创建带标签和预估时间的任务，最终的结果就是生成一个完整的冲刺规划，所有任务都安排好。想清楚这些，做出来的Skills才会精准落地，不会偏离需求。

Skills的三大类型

根据Anthropic的实践经验，Skills大概能分成三类，每一类的开发重点都不一样，大家可以对着自己的需求找方向。

第一类：文档和资产创建类

就是让Claude生成规范的文档、PPT、代码、设计图这些东西，不用借助任何外部工具，全靠Claude的原生能力就行。

开发这类Skills的关键，就是把样式指南、品牌标准嵌进去，做好标准化的模板，还有最终输出前的质量检查清单，保证每次生成的内容质量都在线，比如前端设计的frontend-design Skills就属于这一类。

第二类：工作流自动化类

适合那些需要多步骤操作，还得有标准化方法的流程，甚至能让多个MCP服务器配合工作。

比如做Skills的skill-creator工具本身就是这类Skills，它能一步步引导用户做新Skills，从定用例到写基础信息，再到写指令、验证，全流程都覆盖。

开发这类Skills，要做好分步的工作流，每一步都加验证环节，还要给通用的结构模板，内置审核和改进建议，让工作流能不断优化。

第三类：MCP增强类

核心是给MCP的工具访问能力加工作流指导，让Claude能更高效地用MCP连接的工具。

比如Sentry的代码审核Skills，能借助Sentry的MCP服务器，自动分析并修复GitHub里的代码漏洞。

这类Skills要做好的是多个MCP调用的顺序安排，把领域知识嵌进去，自动补充用户没说的上下文，还要处理好MCP使用中常见的错误，保证运行顺畅。

如何定义成功标准？

定好用例和类型后，还要定一个成功标准，不然不知道自己做的Skills好不好用。这个标准分量化和定性两方面：

量化标准：

• Skills
  要在90%的相关查询里自动触发，拿10-20个测试问题试一下就行

• 在指定的工具调用次数里完成工作流，对比开Skills和不开Skills的情况

• 工作流里不能有API调用失败的情况，看MCP的服务器日志就能知道

定性标准：

• 用户不用反复提醒Claude下一步该干嘛

• Skills
  执行的结果不用用户修正

• 不管什么时候用，结果都能保持一致

这些可以通过自己测试、找朋友试用反馈来判断。

设计环节的硬性规则

当然，设计环节还有一些硬性的规则要遵守，不然后面上传都传不上去：

• Skills
  文件夹的名字要用短横线分隔，不能有空格、下划线，也不能用大写字母

• SKILL.md
  这个文件名必须一字不差，大小写也不能错，不然系统找不到

• 文件夹里不能放README.md，所有文档要么放SKILL.md里，要么放references文件夹里，只有在GitHub分发的时候，才能在仓库层面加一个给人看的README

最关键的就是YAML里的基础信息，尤其是描述部分，直接决定了Claude能不能正确识别并触发Skills。

描述里必须同时说清Skills是干嘛的、什么时候该用，还要加一些用户平时会说的触发话，涉及到特定文件类型的也要提，字符数控制在1024以内，别用XML的标签。

比如做一个Figma设计文件分析的Skills，描述就要说清能分析Figma文件、生成开发交接文档，用户上传fig文件、要设计规范、做设计转代码交接的时候就触发，这样Claude才能精准识别。

写SKILL.md的技巧

写SKILL.md里的具体指令也有技巧，要具体、能落地，别写那些模棱两可的话：

• 比如别说让Claude验证数据，而是要说清运行哪个脚本、带什么参数，验证失败了常见的问题是什么、怎么解决

• 还要把错误处理做好，把常见的问题和解决方法都写进去

• 清晰引用文件夹里的其他资源，核心指令留在SKILL.md里，太详细的资料就放references里，用链接引过来就行，符合渐进式披露的原则

测试迭代也很重要

做出来的Skills不能直接用，一定要测试和迭代，不然实际用的时候会出各种问题，体验特别差。

测试方法

指南里给的测试方法特别灵活，能根据自己的需求选，不用追求一刀切的严谨度：

• 自己用：
   就在Claude.ai里手动测，直接输指令看Claude的反应，不用额外配置，改起来也快

• 团队用：
   想保证版本稳定，就在Claude Code里做脚本化测试，把测试用例固定下来，每次改完Skills都能重复测

• 企业级：
   要大规模部署，就用Skills API做程序化测试，建一个评估套件，系统性地跑测试用例，保证Skills的稳定性

还有一个特别实用的测试技巧，亲测有效，就是先盯着一个复杂的任务反复调，直到Claude能完美执行，再把这个成功的方法提炼成Skills，最后再扩展到其他测试用例。

这样能充分利用Claude的上下文学习能力，比一上来就全面测试效率高多了，也能更快找到Skills的问题所在。

测试的三个方面

测试主要看三个方面：触发、功能、性能，把这三点测透，Skills的基础就稳了。

1. 触发测试

看Skills能不能在该用的时候出来，不该用的时候不捣乱。比如做了一个ProjectHub的Skills，用户说搭建工作区、创建项目这些话要能触发，说查天气、写代码这些无关的话，就不能触发，还要试一下不同的说法，比如换个句式说创建项目，看能不能正常触发。

2. 功能测试

看Skills能不能做出正确的结果，比如测试创建5个任务的项目，给定项目名和任务描述后，Skills要能在平台上建好项目，5个任务的属性都正确，还能和项目关联起来，全程不能有API错误。

还要测一些边缘情况，比如输入的信息不完整、格式不对，看Skills的错误处理能不能生效，保证各种情况都能应对。

3. 性能对比测试

主要看开了Skills之后，工作流的效率有没有提升。对比开Skills和不开Skills的情况，看是不是能自动执行工作流，需要用户澄清的问题少不少，API调用有没有失败，消耗的令牌多不多。

一般来说，开了Skills之后，这些指标都会有明显的提升，不然这个Skills的价值就不大了。

skill-creator工具

这里还要提一下skill-creator这个工具，简直是做Skills的神器，能省大把时间。

在Claude.ai的插件目录就能找到，Claude Code也能下载用，只要告诉它你想做一个什么Skills，它就能根据你的描述生成规范的SKILL.md文件，还会建议触发的话和Skills结构。

做完之后，它还能帮你审核，指出哪里描述模糊、少了触发词、结构有问题，还会根据Skills的用途给测试用例。

如果用的时候发现了问题，比如某个边缘情况处理不好，把问题反馈给它，它还能帮你优化Skills，唯一的缺点就是不能自动跑测试套件，也给不了量化的测试结果，这部分还得自己来。

持续迭代优化

Skills做完上线后，也不是就完事了，还要根据实际使用的情况持续迭代：

• 该触发的时候不触发：
   用户还要手动开，甚至有人问这个Skills什么时候用，就是描述不够详细，把相关的关键词、技术术语加上就行

• 触发太频繁：
   无关的查询也触发，就是描述太宽泛了，要么加一些排除的场景，要么把描述写得更具体，比如把处理文档改成处理合同审核的PDF法律文档

• 执行结果乱七八糟： API
  总失败，用户总要修正，就回去优化指令，把错误处理做得更完善

5大好用开发模式

指南里还有一个特别实用的部分，就是从大量的实际开发案例里，提炼出了五个好用的Skills开发模式，不是硬性的模板，而是经过验证的方法，大家可以对着自己的需求选，不用再自己摸索。

不过选之前要先想清楚自己的Skills是问题导向还是工具导向：

• 问题导向：
   用户说想做什么，Skills来安排对应的工具调用，比如用户说要建项目工作区，Skills来协调各种工具完成

• 工具导向：
   用户已经连好了某个MCP工具，Skills来教Claude怎么高效用这个工具，比如用户连了Notion的MCP，Skills来教Claude用Notion做项目管理

多数Skills都会偏向一个方向，找对方向再选模式，就不会错。

模式一：顺序工作流编排

适合那些要按固定顺序做的多步骤流程，比如新客户的入职流程，先建账户，再设支付，然后创订阅，最后发欢迎邮件，每一步都调用对应的MCP工具，还要明确参数和等待条件。

开发关键： 把步骤顺序、步骤间的依赖关系说清楚，每一步都加验证，还要写好失败后的回滚方法，避免一步错步步错。

模式二：多MCP协同

适合那些需要多个第三方工具配合的工作流，比如设计到开发的交接流程，先在Figma里导出设计资产，再把资产存到Drive里，然后在Linear里创建开发任务，最后在Slack里发通知。

核心： 把每个阶段划分清楚，做好不同MCP之间的数据传递，进入下一个阶段前一定要验证，还要有集中的错误处理，不管哪个环节出问题，都能快速解决。

模式三：迭代优化

适合那些需要反复修改才能出好结果的场景，比如生成报告，先拿数据写初稿，再用脚本检查质量，找出问题后修改，改完再检查，直到达到质量要求，最后再做最终的格式调整。

开发关键： 定好明确的质量标准，做好迭代的循环，配好验证脚本，还要知道什么时候该停止迭代，不然会无限修改，浪费时间。

模式四：上下文感知的工具选择

适合同一个结果能用不同工具实现的场景，比如存文件，大文件用云存储，协作文档用Notion，代码文件用GitHub，临时文件用本地存储。

核心： 定好清晰的决策标准，比如多大的文件算大文件，什么类型的文件算协作文档，还要有备选方案，万一某个工具用不了，能快速换，还要跟用户说清楚为什么选这个工具，让用户明白背后的逻辑。

模式五：领域特定智能

适合那些需要专业领域知识的Skills，不只是简单调用工具，比如带合规要求的支付处理，处理前要先查制裁名单、验证司法管辖区、评估风险等级，合规了才能处理，还要做好完整的审计记录。

开发关键： 把领域的专业知识嵌到Skills的逻辑里，先做合规检查再操作，做好全面的文档记录，建立清晰的治理规则，保证操作符合行业规范。

常见Skills问题解决方法

咱们开发Skills的过程中，肯定会遇到各种问题，指南里把最常见的问题都整理好了，从上传失败到Skills不触发，再到MCP连接出错，都有对应的解决方法，相当于一个全场景的排障手册。

问题1：上传失败

• 系统找不到SKILL.md文件：
   大概率是文件名写错了，大小写不对或者多了少了字，改回一字不差的SKILL.md就行，还能通过ls -la命令验证一下

• 提示前置元数据无效：
   就是YAML格式错了，比如少了分隔符、引号没闭合，按标准格式改好就可以

• 提示Skills名称无效：
   就是名字里有空格、大写字母，改成短横线分隔的格式就行

问题2：Skills不触发

这是最常见的问题，核心就是描述部分没写好，要么太笼统，要么没加触发词，要么没提相关的文件类型。可以先问Claude什么时候会用这个Skills，Claude会把描述念回来，对着看哪里缺了信息，补上就行。

如果Skills触发太频繁，无关的查询也会出来，就把描述改得更具体，或者加一些排除的场景，明确Skills的使用范围。

问题3：MCP调用失败

如果Skills能加载，但MCP调用总失败，就一步步查：

1. 先看MCP服务器是不是连好了

2. 再看API密钥、OAuth令牌这些认证信息是不是有效

3. 再直接调用MCP工具试试，如果直接调用也失败，就是MCP的问题，不是Skills的问题

4. 最后再检查Skills里的工具名称是不是写对了，大小写也要注意

问题4：Claude不按指令执行

Skills加载了，但Claude不按指令来，大概率是指令写得不好，要么太啰嗦，要么关键信息藏在后面，要么话讲得模棱两可。

解决方法：

• 把指令精简一下，用编号、项目符号分点

• 关键信息放最前面，用醒目的标题标出来

• 话要说得具体，别写模棱两可的内容

• 还可以加一些明确的执行要求，比如让Claude仔细做、质量优先、别跳过验证步骤（不过这些要求加在用户的提示里比加在Skills里效果更好）

• 对于一些关键的验证环节，还可以把语言指令做成可执行的脚本，用代码的确定性代替语言解释的不确定性，避免Claude理解偏差

问题5：Claude反应慢、回答质量下降

如果用Skills的时候发现Claude反应慢、回答质量下降，就是大上下文的问题，要么是Skills的内容太杂，要么是同时开的Skills太多，要么是没按渐进式披露的原则，一次性加载了所有内容。

解决方法：

• 把SKILL.md里的详细内容移到references里，保持SKILL.md在5000字以内

• 关掉一些不用的Skills，把同时开启的数量控制在20-50个

• 严格按三级加载的原则来，就能解决这个问题

写在最后

Anthropic这次发布的这份Claude Skills构建指南真的是太详细了，不只是把Skills开发的全流程拆解开了。更重要的是确立了AI定制化工作流的标准化体系，让AI能真正贴合每个人、每个团队的实际需求，落地到日常工作中。

无论你是Skills领域刚入门的小白还是有开发经验的老手，都能从这个指南中获得宝贵的学习经验。

想系统掌握AI核心技能、获取行业认可资质？

CAIE注册人工智能工程师认证

助你拓宽职业赛道，成为AI领域持证实力派

微信小程序

CAIE 认证

CAIE认证

以上内容来自微信小程序