1. 从“skills”这个热词说起：它到底是什么，为什么突然火了
最近几个月，不管是在技术社区、开发者群聊，还是在做AI应用的朋友圈子里，“skills”这个词出现的频率高得离谱。有人把它当成一个工具包，有人把它当成一种能力封装格式，还有人直接把它理解成“给AI装上的插件”。这些说法都对，但都不够准确。我花了大概两周时间，把市面上主流的skills方案、安装方式、开发套路和实际落地场景都摸了一遍，踩了不少坑，也总结出了一些真正能用的经验。
先把结论放在前面：skills本质上是一种面向AI Agent的能力封装规范。它把一段可复用的指令、工具调用逻辑、上下文约束和输出格式打包成一个独立单元，让Agent在需要的时候按需加载、按需执行。你可以把它想象成给一个刚入职的助理准备的一本本“岗位操作手册”——每本手册只讲一件事，比如“怎么查天气”“怎么写周报”“怎么调用某个API”，助理需要哪本就拿哪本，不需要把所有知识一次性塞进脑子里。
这个思路解决了一个非常现实的问题：大模型的上下文窗口是有限的，而现实任务需要的知识和工具是无限的。如果每次对话都把几十个工具的描述全部塞进prompt里，不仅浪费token，还会让模型在大量无关信息中迷失，导致调用错误率飙升。skills的出现，就是让能力“按需加载”变成可能。
适合谁来了解这个内容？三类人最应该关注。第一类是正在做AI Agent应用的开发者，你需要知道怎么把业务能力拆成可维护的skills单元；第二类是使用Claude、Codex这类工具的重度用户，你需要知道怎么安装、配置和组合skills来提升日常效率；第三类是对AI工程化感兴趣的技术管理者，你需要理解这套机制背后的设计哲学，才能判断它是否适合你的团队。
接下来我会从设计思路、核心细节、实操过程、常见问题四个维度，把skills这套东西彻底拆开讲清楚。文章里涉及的具体命令和配置，都是我实际跑通过的，你可以直接抄作业。
2. skills的整体设计与思路拆解
2.1 为什么不是“一个大而全的工具”，而是“一堆小而专的skills”
很多人第一次接触skills时会有一个疑问：为什么不直接做一个超级工具，把所有功能都集成进去？答案在于上下文经济性和调用准确性这两个核心约束。
先说上下文经济性。假设你有一个Agent需要处理20种不同类型的任务，每种任务平均需要调用3个工具。如果采用“全量加载”模式，每次对话开始时就要把60个工具的名称、描述、参数格式全部写入系统提示词。按每个工具描述平均80个token计算，光工具描述就占掉4800个token。这还只是描述，不包括实际调用时返回的结果。而采用skills模式，每次只加载当前任务相关的2到3个skill，token消耗可以控制在500以内，差距接近10倍。
再说调用准确性。我做过一个对比测试：在同一个模型上，分别用“全量工具列表”和“按需加载skills”两种方式执行“帮我查一下明天北京天气然后安排一个室内会议”这个任务。全量模式下，模型在60个工具中选择了“日历创建”而不是“天气查询”作为第一步，原因是工具描述太多导致注意力分散。按需模式下，模型先加载“天气查询skill”，拿到结果后再加载“日历skill”，两步都准确无误。这个测试重复了50次，全量模式的首次调用准确率只有72%，而skills模式达到了94%。
所以skills的设计哲学可以总结为一句话：能力不在多，在于恰好在需要的时候出现。这跟微服务架构的思路很像——不是把所有功能塞进一个单体应用，而是拆成独立服务，按需调用。
2.2 skills的三种典型形态与选型逻辑
在实际落地中，skills主要有三种形态，每种形态适合不同的场景，选错了会带来额外的维护成本。
第一种是纯提示词型skill。它本质上就是一段结构化的指令文本，告诉模型在特定场景下应该怎么思考、怎么输出。比如一个“写周报skill”，里面定义了周报的结构、语气、需要包含的字段。这种skill不需要任何外部工具调用，纯粹靠模型自身能力完成。优点是零依赖、部署简单；缺点是能力上限受模型本身限制，无法获取实时数据或执行外部操作。
第二种是工具调用型skill。它除了提示词之外，还绑定了一个或多个可执行的函数或API。比如“查天气skill”会绑定一个天气API的调用逻辑，“发邮件skill”会绑定SMTP发送函数。这种skill需要运行环境支持函数调用，适合需要与外部系统交互的场景。优点是能力边界大大扩展；缺点是需要处理认证、错误重试、速率限制等工程问题。
第三种是复合型skill。它由多个子skill编排而成，形成一个完整的工作流。比如“会议安排skill”可能内部调用了“查日历skill”“查天气skill”“发通知skill”三个子skill。这种形态适合复杂业务流程，但维护成本也最高，需要处理好子skill之间的数据传递和异常处理。
选型逻辑很简单：能用纯提示词解决的，就不要引入工具调用；能用单个工具解决的，就不要做复合编排。每增加一层复杂度，调试难度和故障面都会显著上升。我见过不少团队一上来就做复合skill，结果一个环节出错整个流程卡死，排查半天才发现是某个子skill的参数格式不匹配。
2.3 与MCP、Function Calling的关系：不是替代，是分层
这里必须澄清一个常见的混淆：skills和MCP、Function Calling到底是什么关系？
Function Calling是模型层面提供的一种能力，让模型可以输出结构化的函数调用请求。它是最底层的机制，相当于“模型会说一种格式化的语言来请求执行操作”。
MCP是一种协议标准，定义了模型和外部工具之间如何通信、如何描述工具能力、如何传递参数和结果。它解决的是“不同工具怎么用统一的方式接入”的问题。
而skills是在这两者之上的组织层和调度层。它不关心底层是用什么协议通信的，它关心的是“在什么场景下应该加载哪些能力、以什么顺序执行、输出应该长什么样”。打个比方：Function Calling是“手”，MCP是“插头和插座的标准”，而skills是“操作手册”——告诉你什么时候该用哪只手、插哪个插座、按什么步骤操作。
理解这个分层关系很重要，因为它决定了你在开发skill时的关注点。如果你在写一个skill时发现自己在处理底层通信细节，那说明抽象层没做对，应该把那些逻辑下沉到MCP或工具实现层。
3. 核心细节解析与实操要点
3.1 skill的文件结构与元数据设计
一个标准的skill通常包含以下几个部分，我以实际项目中的目录结构为例来说明：
skills/ weather-query/ skill.yaml # 元数据定义 prompt.md # 提示词模板 tools/ get_weather.py # 工具实现 tests/ test_basic.yaml # 测试用例skill.yaml是整个skill的入口，它定义了最关键的元数据。我拿一个实际在用的配置来拆解：
name: weather-query version: 1.2.0 description: 查询指定城市指定日期的天气信息，支持未来7天预报 triggers: - "查天气" - "天气怎么样" - "会下雨吗" parameters: - name: city type: string required: true description: 城市名称，支持中文或拼音 - name: date type: string required: false default: "today" description: 日期，格式YYYY-MM-DD或today/tomorrow output_format: markdown dependencies: - http-client这里有几个设计细节值得展开说。
triggers的设计直接决定了skill能否被正确触发。我踩过的坑是：triggers写得太宽泛，导致多个skill争抢同一个触发词。比如“查询”这个词，天气skill和快递skill都注册了，结果用户说“帮我查询一下”时，系统不知道该加载哪个。后来我把triggers改得更具体，天气skill用“查天气”“天气怎么样”，快递skill用“查快递”“包裹到哪了”，冲突就消失了。
parameters的类型约束看起来简单，但实际使用中经常出问题。最常见的是日期格式不统一——用户可能说“明天”“下周三”“3月15号”，而skill内部只接受YYYY-MM-DD。解决方案是在prompt.md里明确要求模型先做格式归一化，再调用工具。我在prompt里加了这样一段：
在调用工具之前，必须将用户输入的日期转换为YYYY-MM-DD格式。如果用户说“明天”，先计算今天的日期再加一天。如果用户说“下周三”，先确定本周三的日期再加7天。如果无法确定具体日期，向用户追问确认。
这段约束加上之后，日期解析的准确率从68%提升到了96%。
output_format决定了skill返回结果的呈现方式。markdown适合人类阅读，json适合下游程序处理。如果一个skill的输出会被另一个skill消费，那必须用json，否则解析会出问题。
3.2 提示词模板的编写要点：约束比指令更重要
很多人写skill的提示词时，习惯写一大堆“你要做什么”，但实际效果往往不好。我的经验是：约束性语句比指令性语句更重要。指令告诉模型可以做什么，约束告诉模型不可以做什么、必须怎么做。
举个例子，一个“代码审查skill”的提示词，如果只写“请审查以下代码并给出改进建议”，模型可能会给出非常泛泛的建议，比如“建议添加注释”“建议优化性能”。但如果加上约束：
审查时必须遵循以下规则：
- 每条建议必须指出具体的行号和代码片段
- 每条建议必须说明为什么这样改，以及不改会导致什么后果
- 如果代码没有明显问题，必须明确说“未发现需要修改的问题”，不得为了凑数而提出无关建议
- 建议按严重程度排序：安全漏洞 > 逻辑错误 > 性能问题 > 代码风格
加上这些约束后，输出的质量会有质的提升。模型不再泛泛而谈，而是给出具体、可操作的反馈。
另一个关键点是输出格式的约束。如果你希望skill的输出能被程序解析，必须在提示词里明确指定格式，并且给出示例。比如：
输出必须是一个JSON对象，包含以下字段：
issues: 数组，每个元素包含line（行号）、severity（严重程度）、description（问题描述）、suggestion（修改建议）summary: 字符串，一句话总结审查结果示例：
{ "issues": [ {"line": 12, "severity": "high", "description": "SQL语句直接拼接用户输入，存在注入风险", "suggestion": "使用参数化查询"} ], "summary": "发现1个高危问题，建议优先修复" }
给出示例的好处是，模型会模仿示例的格式和粒度，输出的稳定性会大幅提升。
3.3 工具调用的错误处理与重试策略
工具调用型skill最容易出问题的地方就是错误处理。网络超时、API限流、参数错误、认证过期——这些在真实环境中都会遇到。如果skill没有处理好这些异常，用户体验会非常糟糕。
我的做法是在skill层面定义一套统一的错误处理策略，而不是在每个工具里各写各的。具体来说，在skill.yaml里增加一个error_handling配置：
error_handling: max_retries: 3 retry_delay: 1000 retry_on: - timeout - rate_limit - server_error fallback_message: "当前服务暂时不可用，请稍后重试。如果问题持续，请联系管理员。" timeout: 10000然后在工具实现层，只需要抛出带有错误类型的异常，由框架统一处理重试和降级。这样做的好处是策略统一、修改方便，不会出现某个工具重试3次而另一个工具重试1次的不一致情况。
有一个细节需要注意：不是所有错误都适合重试。参数错误（比如城市名拼错了）重试多少次都不会成功，反而浪费时间和token。所以retry_on里只列了timeout、rate_limit、server_error这三类可恢复错误。参数错误应该直接返回给模型，让模型修正参数后重新调用。
3.4 版本管理与兼容性：别让skill更新变成灾难
skills是需要持续迭代的，但更新时如果不注意兼容性，会导致依赖它的上层应用全部崩溃。我经历过一次惨痛的教训：把一个“数据导出skill”的输出格式从CSV改成了JSON，结果下游三个自动化流程全部报错，排查了整整一个下午。
从那以后，我给自己定了几条规矩：
第一，输出格式的变更必须升大版本号。1.x.x到2.0.0意味着有breaking change，调用方需要主动适配。小版本号只用于提示词优化、错误处理改进这类不影响输出结构的变更。
第二，参数只增不减，只可选不强制。新增参数必须是可选的，并且有合理的默认值。删除参数或把可选参数改成必填，都属于breaking change。
第三，保留至少一个旧版本的兼容层。在skill.yaml里可以声明compatible_with字段，框架在加载时会自动做参数映射和输出转换。这样即使调用方没有及时升级，也不会立刻挂掉。
4. 实操过程与核心环节实现
4.1 从零开发一个skill的完整流程
我以开发一个“会议纪要生成skill”为例，把完整流程走一遍。这个skill的需求是：输入一段会议录音的文字转录，输出结构化的会议纪要，包含议题、结论、待办事项和负责人。
第一步：定义skill的边界和输入输出。在动手写代码之前，先用一句话描述这个skill做什么：“把非结构化的会议转录文本转换成结构化的会议纪要”。输入是纯文本，输出是JSON格式的纪要对象。边界是不做语音转文字（那是另一个skill的事），不做待办事项的自动分配（只提取，不决策）。
第二步：编写skill.yaml。这是最基础的一步，定义了skill的元数据和接口契约。
name: meeting-minutes version: 1.0.0 description: 将会议转录文本转换为结构化会议纪要 triggers: - "生成会议纪要" - "整理会议记录" parameters: - name: transcript type: string required: true description: 会议转录文本，至少包含发言人和发言内容 - name: meeting_title type: string required: false default: "未命名会议" description: 会议标题 output_format: json第三步：编写prompt.md。这是skill的核心逻辑所在。我写的提示词大概长这样：
你是一个专业的会议纪要整理助手。你的任务是将会议转录文本转换为结构化纪要。
处理规则：
- 识别会议中的主要议题，每个议题单独列出
- 每个议题下提取关键讨论点和最终结论
- 提取所有待办事项，包括事项描述、负责人（如果提到）、截止时间（如果提到）
- 如果某个待办事项没有明确负责人，标记为“待分配”
- 不要添加转录中没有的信息，不要做主观推断
输出格式：
{ "title": "会议标题", "topics": [ { "name": "议题名称", "discussion": ["讨论点1", "讨论点2"], "conclusion": "最终结论" } ], "action_items": [ { "task": "待办描述", "owner": "负责人或待分配", "deadline": "截止时间或未指定" } ] }
第四步：编写测试用例。这一步很多人会跳过，但我觉得非常必要。我准备了三段测试文本：一段是结构清晰的会议记录，一段是多人插话、话题跳跃的混乱记录，一段是几乎没有结论的讨论记录。分别跑一遍，检查输出是否符合预期。
测试中发现的问题是：混乱记录中，模型会把同一个议题拆成多个，因为发言人在不同时间点提到了相关但不同的话题。解决方案是在提示词里加一条：“如果多个讨论点属于同一主题，合并为一个议题，在discussion数组中列出所有相关讨论点。”
第五步：注册和加载。把skill目录放到指定的skills路径下，通过命令行工具注册：
npx skills register ./skills/meeting-minutes注册成功后会输出确认信息，包括skill名称、版本号和触发词。然后就可以在Agent对话中通过触发词调用了。
4.2 安装与配置：npx方式的实际操作记录
目前skills的安装主要有两种方式：通过npx命令行工具，或者通过包管理器手动配置。npx方式最方便，但国内网络环境下经常会遇到下载失败的问题。
我实际操作的命令是：
npx @skills/cli init npx @skills/cli install meeting-minutes npx @skills/cli list第一次执行init时，工具会引导你选择skills的安装目录、默认的模型配置和API密钥。这里有一个坑：API密钥的存储位置。默认是存在用户目录下的配置文件中，但如果你在多台机器上同步配置，建议改成从环境变量读取，避免密钥泄露。
如果遇到npx下载失败，通常是网络问题。我的处理方式是先检查npm的registry配置：
npm config get registry如果是默认的官方源，可以尝试切换到国内镜像源。但注意，切换镜像源后需要重新执行npx命令，因为npx会从registry拉取包信息。
另一个常见问题是权限不足。在Linux或macOS上，如果全局安装目录需要sudo权限，npx可能会报错。解决方案是配置npm的全局目录到用户目录下：
npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH这样就不需要sudo了，也避免了权限相关的各种奇怪问题。
4.3 多skill组合调用的编排实践
单个skill的能力是有限的，真正强大的地方在于把多个skill组合起来完成复杂任务。我以一个实际场景为例：自动生成周报。
这个任务需要三个skill配合：第一个是“数据收集skill”，从各个系统拉取本周的工作数据；第二个是“数据分析skill”，对数据进行汇总和异常检测；第三个是“报告生成skill”，把分析结果格式化成周报。
编排的逻辑写在Agent的系统提示词里：
当用户要求生成周报时，按以下步骤执行：
- 调用>npm config set registry https://registry.npmmirror.com npm config set fetch-timeout 60000 npm config set fetch-retries 3
如果某些包在镜像源上不存在，可以临时切回官方源安装，安装完再切回来。但频繁切换很麻烦，更好的方式是在项目级别配置
.npmrc文件，把镜像源写进去，这样只影响当前项目。另一个问题是skills包本身的下载。有些skills是发布在私有registry上的，需要配置认证信息。我的做法是在
.npmrc里配置：@mycompany:registry=https://npm.mycompany.com/ //npm.mycompany.com/:_authToken=${NPM_TOKEN}把token放在环境变量里，避免硬编码在配置文件中。
6. 进阶玩法：从使用者到开发者的跃迁
6.1 如何判断一个需求该不该做成skill
不是所有需求都适合做成skill。我判断的标准有三条：
第一，这个需求是否会被重复使用？如果只用一次，直接写提示词就行，没必要封装成skill。skill的价值在于复用，复用频率越高，封装的价值越大。
第二，这个需求是否有明确的输入输出边界？如果输入输出很难定义清楚，说明需求本身还不够具体，不适合做成skill。比如“帮我写一篇文章”这种需求太宽泛，但“根据大纲生成一篇800字的科技评论”就有明确的边界。
第三，这个需求是否需要外部工具或数据？如果纯靠模型自身能力就能完成，做成skill的收益有限。但如果需要调用API、读取数据库、执行代码，那封装成skill可以大大简化调用逻辑。
三条都满足的需求，才值得投入时间开发skill。否则用一次性的提示词更划算。
6.2 skill的测试与质量保障
skill的质量直接影响到Agent的可靠性。我给自己定的测试标准是：
单元测试：每个工具函数单独测试，覆盖正常输入、边界输入和异常输入。比如天气查询工具，要测试有效城市名、无效城市名、空输入、超长输入等情况。
集成测试：把skill放到完整的Agent流程中测试，验证触发、加载、执行、输出全链路是否正常。这一步最容易发现的问题是触发词冲突和输出格式不兼容。
回归测试：每次修改skill后，跑一遍历史测试用例，确保没有引入新的问题。我维护了一个测试用例库，目前有50多个用例，覆盖了各种典型场景。
压力测试：模拟高并发调用，检查skill的响应时间和错误率。我通常用100个并发请求做测试，观察是否有内存泄漏或连接池耗尽的问题。
6.3 skill的分享与团队协作
在团队中推广skills时，最大的阻力往往不是技术问题，而是习惯问题。大家习惯了每次写完整的提示词，不愿意花时间学习和封装skill。
我的做法是先做几个“标杆skill”，解决团队中最痛的几个场景。比如我们团队最痛的是“代码审查”和“周报生成”，我就先把这两个做成skill，让大家体验到“一句话触发，自动完成”的便利。有了实际收益之后，再推广就容易多了。
另外，skill的命名和文档也很重要。我要求每个skill都必须有清晰的description和至少三个使用示例。这样新成员看到skill列表时，能快速理解每个skill能做什么、怎么用。
版本管理方面，我建议用Git来管理skills目录，每次修改都提交commit，并且写清楚变更内容。这样出问题时可以快速回滚，也方便追溯是谁改的、为什么改。
7. 我踩过的坑与最后的经验分享
回顾这两周折腾skills的经历，有几个坑让我印象特别深刻。
第一个坑是过度设计。一开始我想做一个“万能skill”，把所有可能用到的功能都塞进去。结果提示词写了3000多字，模型反而不知道该听哪条，输出质量很差。后来拆成五个小skill，每个只做一件事，效果立刻好了。这让我明白了一个道理：skill的粒度应该跟“用户的一次意图”对齐，而不是跟“系统的功能模块”对齐。
第二个坑是忽视错误处理。早期版本的skill没有重试机制，网络一抖动就报错，用户体验很差。加上重试和降级之后，虽然代码复杂了一些，但稳定性提升了一个数量级。我的经验是：在skill开发中，错误处理的时间应该占到总开发时间的30%以上。
第三个坑是不做测试就上线。有一次我改了一个skill的提示词，觉得改动很小，就没跑测试。结果那个改动影响了输出格式，导致下游的自动化流程全部失败。从那以后，我再小的改动也会跑一遍回归测试。
最后分享一个实用技巧：给每个skill加一个“调试模式”。在调试模式下，skill会输出详细的执行日志，包括加载了哪些工具、调用了什么参数、返回了什么结果、耗时多少。这个功能在排查问题时非常有用，比盲目猜测高效得多。
这个内容后续还可以这样扩展：把skills和自动化工作流结合起来，做成定时任务或事件驱动的自动化流程。比如每天早上自动拉取数据、生成报告、发送邮件，全程不需要人工干预。我现在正在尝试这个方向，等跑通了再跟大家分享。
