1. 为什么你的智能体需要一个"技能"：先说清楚 Coze Skills 到底解决了什么问题
接触扣子平台一段时间之后，你会发现一个非常尴尬的阶段：对话、知识库、工作流都能搭得像模像样，但智能体一到"需要外部实时数据"的时候就哑火了。比如用户问"今天北京能出门跑步吗"，它只能基于训练数据里的旧信息给你一段模棱两可的回答，而不可能真的去查当下的空气质量、风速和降水概率。问题不在于模型不够聪明，而是它没有"手"——没有一条能触达外部世界的通道。
Coze Skills（中文界面里通常叫"技能"）解决的就是这件事：把某个外部能力封装成一个可以被对话式 AI 动态调用的函数式接口。你可以把技能理解为给智能体装了一台"外接设备"。平时它安安静静地挂在工具箱里，只有当用户请求确实需要用到某项能力时，模型才会按你的描述决定是否调用、填什么参数、怎么处理返回结果。
很多人会把 Skills 和"插件""工作流""工具"这几个概念混在一起，刚开始我也花了挺长时间才理清楚它们的分工。简单来说，在扣子生态里，工作流是把多个步骤串起来做编排，内部可以调用各种节点；而技能更接近一个"能力单元"，强调的是对外部系统的单一封装。单个技能内部也可以有多个接口，但它的边界通常是一次明确的外部交互，比如"查天气""发短信""查数据库里的订单状态"。类比一下：工作流像是一条流水线，技能则是这条流水线上的机械臂；机械臂负责具体干活，流水线负责安排什么时候让哪只机械臂动。
这篇文章面向的是已经能在扣子平台上创建智能体、但还没系统搞过技能的开发者。我会从底层原理一路讲到实操步骤，再讲排错思路和几个容易被忽略的坑。整篇的内容都基于一个假设：你想让智能体具备某个真实可用的外部能力，而不是做个只会背资料的聊天机器人。
2. 技能的工作机制：OpenAPI 描述文件是如何把"对话意图"变成"真实请求"的
动手写技能之前，必须先理解扣子技能底层的设计逻辑，否则你写出来的文件就像没有地基的房子，看起来结构完整，一测试就塌。
2.1 技能文件的核心组成：一块提示词加一份接口描述
一个自定义技能，本质上由两个不可分割的部分组成：描述文件（负责告诉模型"这个技能什么时候该用、参数怎么填"）和接口定义（负责告诉模型"外部服务的请求格式是什么、返回结构是什么"）。在扣子的技能编辑器里，前者通常是一段 Markdown 格式的说明，后者则是遵循 OpenAPI 规范的结构化定义，一般可以用 JSON 或 YAML 编写。
这里就引出一个关键的认知：技能不是一个程序插件，它是模型与外部 API 之间的翻译契约。模型本身不会执行代码，它只会阅读这些描述，然后按照规则生成一次 HTTP 请求。外部服务返回结果之后，模型再把这些结构化数据转化成自然语言回复给用户。整个链路里，真正发起网络请求的是扣子平台的运行时，模型负责的是"决策"和"表达"这两端。
2.2 一次完整调用的流转过程：从用户提问到智能体给出答案
我以最经典的"查天气"技能为例，拆解一次典型调用的完整过程。这一部分非常重要，因为很多人在调试技能时失败，就是因为不知道问题出在链路的哪一环。
第一步，用户在对话框里输入："明天上海适合出门吗？"
第二步，扣子平台的调度器把这句话连同历史对话上下文一起交给大语言模型，同时附上你定义好的技能描述。模型理解到这是一个需要实时天气数据的问题，判断"get_weather"这个操作适合当前场景，于是生成一个结构化的函数调用意图，目标接口是 get_weather，参数 city = "上海"。
第三步，平台运行时读取 OpenAPI 定义，把意图转换成一个真实的 HTTP 请求，比如 GET，请求地址是 https://api.example.com/v1/weather?city=%E4%B8%8A%E6%B5%B7，再带上你配置好的鉴权头。
第四步，外部服务返回 JSON 响应：{"city":"上海","temp_max":22,"temp_min":16,"condition":"多云","wind_level":3}。
第五步，模型拿到这个 JSON，结合用户原问题，翻译成自然语言："上海明天多云，最高气温 22 度，最低 16 度，风力 3 级，整体体感挺舒服的，可以出门。"
这个链路看似不复杂，但每一个环节都有独立的失败模式。我在后面专门写一节排错，现在先记住一个核心结论：技能调试的本质，不是"代码能不能跑"，而是"模型是否准确理解契约"。
2.3 为什么选 OpenAPI 而不是别的协议
很多从传统开发转过来的朋友会问：为什么不直接让我写个函数注册进去？这里有一个关键权衡。对话场景里，调用方是语言模型，它最擅长的输入输出是结构化的文本。OpenAPI 规范本身就是人类可读、机器可解析的 JSON 结构，而且对 HTTP 动词、路径参数、请求体、响应体都有完整描述，这些信息恰好就是模型做决策时需要的。
相比之下，如果你暴露一个普通的 SDK 函数，模型没有任何依据判断该传什么参数、返回结果长什么样。而 OpenAPI 描述把所有这些"上下文"前置到了编辑期，模型在运行时只是做一次"阅读理解 + 执行"，可靠性高得多。
3. 从零开始创建你的第一个技能：以"获取实时天气"为例的完整实操
理论铺垫完了，现在进入正题。我建议第一个技能不要贪多，选一个单接口、单参数的服务来练手，比如"根据城市名获取实时天气"。做通这一个，后面复杂技能只是内容和结构的扩展，原理完全一样。
3.1 前期准备：想清楚三个问题再动手
很多教程常犯的错误是一上来就让用户填接口地址，结果填到一半卡住了。我在动手前会先花十分钟回答三个问题，这三分钟能省掉后面两小时的返工。
第一问：数据源靠不靠谱？你自己有没有可用的 API？如果没有，是否准备用一个公开测试接口？注意要选支持跨域或至少支持服务端调用的接口，且要确认限流策略，不然调试时很快就被封。
第二问：这个技能提供几个操作？每操作需要哪些参数？比如天气接口需要 city 参数，如果你希望支持"根据 IP 自动定位"，可能还要加一个可选参数。第一版建议只留必填参数，把可选参数的坑留到第二版再踩。
第三问：返回结果打算怎么被模型使用？你要不要对原始 JSON 做一层裁剪？很多免费接口返回的数据字段非常庞大，动辄几十个键。如果全量返回，既浪费 token，又容易让模型被无关字段干扰。这个点后面我会专门讲，但设计技能时最好提前想好输出结构。
3.2 编写技能描述文件（SKILL.md）：给模型一份"使用说明书"
技能描述文件是整个技能的"思路入口"。它存在的意义是让模型在读完后能够做到三点：知道这个技能是干什么的、知道什么场景下必须调用它、知道怎么从对话里提取参数值。
我的模板一般包含四个部分：技能名称和一句话说明、适用场景和反例场景、参数提取规则、返回值说明。下面是一个参考写法：
# 实时天气查询 通过第三方天气服务获取指定城市的实时天气数据，包括温度、湿度、风力、风向、天气现象。 适用于：用户询问当前或近期天气、询问是否适合户外活动、询问穿衣建议。 不适用于：用户询问历史天气、用户没有提供城市直接问"今天冷不冷"（此时应先用反问澄清地点）。 ## 参数提取规则 - city：必填。从对话中提取城市名。如果是“上海”“北京市”这类表述，规范为“上海”。 - 如果用户说“我这边”，且上下文没有明确城市，不要猜测，主动询问。 ## 返回值处理 - 返回字段以 openapi.json 中的定义为准。 - 优先输出温度、天气现象、风力三项；湿度信息在用户主动询问时才提及。 - 如果接口返回错误，如实告知“暂时无法获取天气”，不要编造数据。这段描述看起来简单，但里面的每一句都直接影响模型行为。特别值得一提的是"不适用场景"和"参数提取规则"：前者防止模型滥用技能，后者保证参数抽取的准确性。很多刚上手的人只写第一段，结果就是模型该调用时不调用，不该调用时乱调用。
3.3 编写 OpenAPI 定义：JSON 还是 YAML，用什么字段
扣子的技能编辑器里，接口定义可以手写也可以从 URL 导入，我建议初学阶段先手写一份 JSON，因为手写的过程本身就是理解的过程。
下面是一份极简的天气接口 OpenAPI 定义（OpenAPI 3.0 版本）：
{ "openapi": "3.0.0", "info": { "title": "实时天气查询", "version": "1.0.0" }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/weather": { "get": { "operationId": "getWeather", "summary": "查询城市实时天气", "parameters": [ { "name": "city", "in": "query", "required": true, "description": "城市名称，如北京、上海", "schema": { "type": "string" } } ], "responses": { "200": { "description": "查询成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string" }, "temp": { "type": "number" }, "temp_min": { "type": "number" }, "temp_max": { "type": "number" }, "condition": { "type": "string" }, "wind": { "type": "string" } } } } } } } } } } }这里要特别强调两个容易忽略的细节。
第一，operationId字段一定要写，而且最好是语义明确的动词加名词组合，比如getWeather。模型在决策时会把 operationId 当作函数名来引用，一个叫fetch_data_12345的 operationId 会让模型感到困惑，而sendEmail、queryOrder这样的名字天生就能被模型理解。
第二，description字段的重要性不亚于主路径。很多接口的请求参数名称是缩写，比如c、q、latlon。如果你不在 description 里解释清楚"c 代表城市拼音，q 代表关键词模糊搜索，latlon 代表纬度经度"，模型即使识别出了用户的意图，也无法正确填参。
3.4 上传配置到平台并完成首次联调
文件编写完成后，进入扣子的技能编辑器，通常有"创建技能"的入口，选择"自定义技能"或"导入 OpenAPI"。我习惯把 SKILL.md 放在描述区、JSON 粘贴到接口定义区，保存后新建一个测试智能体，把技能挂载上去。
第一轮联调建议这样操作：
- 在调试面板里输入一个意图明显的句子，比如"上海现在多少度"，观察是否会触发技能调用。
- 在调试日志里查看模型生成的请求参数，确认 city 是否为"上海"而不是"Shanghai"或"上海天气"。
- 观察模型对返回结果的回复措辞，确认它没有编造字段。
如果整条链路都通了，恭喜，你的第一个技能已经跑起来。但绝大多数情况下你会卡在某个环节，接下来我讲最常踩的坑。
4. 参数传递与鉴权配置：最容易踩坑的三个隐蔽细节
当技能能正常响应简单查询后，你就该面对真实世界的复杂度了。这里我要重点讲三个隐蔽细节：参数的隐式传递、鉴权头的配置方式、以及返回数据的压缩处理。
4.1 模型"自作主张"填参数：如何在描述里约束取值边界
你有没有遇到过这种情况：天气接口明明只需要城市名，但模型给 city 传了个 "shanghai" 或 "上海市，浦东新区"？问题往往不在模型，而在你描述文件里没写清楚"city 的合法取值形式"。
建议在参数描述里把约束写死，比如：
- city 必须是中国大陆城市的官方中文名称，例如“北京”“上海”“广州”。 - 禁止使用拼音（如 Beijing、shanghai），禁止携带“市”“省”等行政后缀。 - 如果用户提供的信息不足，回复“请告诉我你要查询的城市名”。这不仅仅是个格式问题。有些天气服务会按拼音搜索，有些则需要精确匹配城市编号，你如果给模型设定了严格的边界，参数错误率会急剧下降。
4.2 鉴权配置：Header、Query 还是 Body？
真实的外部服务几乎都要鉴权。扣子平台通常支持你为技能统一配置鉴权参数，运行时自动附加在请求上，这样模型不需要关心鉴权细节——这对模型是好事，因为让模型在对话中动态决定往 Header 里塞什么 Token，是非常不安全的做法。
鉴权常见的三种方式：
- Header 传递：适用于大多数标准 API，比如
Authorization: Bearer <token>或者X-API-Key: <key>。 - Query 参数：有些老接口把 key 写在 URL 上，比如
?api_key=xxx。这种最简单但最不安全，调试可用，生产环境尽量别选。 - Body 字段：适用于 GraphQL 或者少数自研服务，Token 放在请求体里。
我的建议是：能用 Header 就用 Header。因为 URL 会出现在访问日志里，如果平台自带日志系统，Query 方式会直接把密钥暴露在屏幕上；而 Header 方式在日志里通常会被脱敏，安全性高得多。
另外还有一个很多人不知道的配置细节：扣子技能编辑器的鉴权配置里，如果你填的变量名和你服务端校验的名称不一致（比如服务端读的是x-api-key，你填的是x-apikey），运行时不会报格式错误，只会返回 401。排查这类问题时，永远先看服务端日志或抓包，别急着改代码。
4.3 返回数据的"瘦身"策略：别把原始 JSON 整个丢给模型
接口返回 50 个字段，模型需要的有 5 个，怎么办？直接把整个 JSON 丢给模型当然是能跑的，但有两个坏处：一是 Token 浪费，天文数字的 token 累积起来成本不小；二是无关字段会稀释模型的注意力，导致它回答时引入噪音信息。
比较务实的做法是：如果你能控制外部服务（比如你自己开发的后端接口），就做一个适配层，只返回必要字段。如果你控制不了，可以利用 OpenAPI 定义里的responses部分做裁剪吗？截止到目前，扣子的自定义技能还不会对响应内容做结构转换，它会把原始响应体原样给模型。所以最可靠的方案是：在接口后端做精简，或者找能返回精简格式的数据源。
如果你实在没有后端能力，有一个小技巧：在 SKILL.md 的返回值处理部分写明："只向用户呈现 temperature、condition、wind 字段相关内容，其余字段仅在追问时说明。" 这虽然不能省 token，但至少能约束模型"说什么"。
5. 实战中的三大高频故障：完整排查链路分享
技能上线之后，问题才会真正密集地暴露出来。我把自己多次调试技能踩过的坑归成三大类，每一类都附上完整的排查思路，供你照着走一遍。
5.1 故障现象一：模型"看不见"这个技能，或者从不主动调用
这是最让人崩溃的故障——技能挂载了，测试时模型却像个没事人一样继续用常识回答。排查思路如下：
第一步，检查技能是否处于"已启用"状态。扣子平台有时会出现技能挂载但并未生效的情况，特别是从草稿修改后忘记重新发布。
第二步，检查 SKILL.md 的场景描述够不够清楚。如果你只在里面写了一句"这是一个天气查询工具"，模型很难判断"用户问明天带伞吗"是否该调用它。把适用的问法直接写进去，比如"当用户询问具体城市的天气、温度、降水概率、风力、空气质量时，调用该技能"。
第三步，用更强的指示测试：在调试里输入"请使用天气技能查询北京天气"。如果能触发，说明技能本身没问题，是模型对触发条件的判断不够果断；此时加强描述文件里的场景映射关系即可。如果连强制指令都触发不了，说明技能的挂载或描述文件存在底层问题，仔细检查技能是否发布成功。
这里有个常见误解：以为模型不调用是"模型笨"。其实大多数情况是技能描述写的太含糊。语言模型没有"常识"说天气该用天气API，它完全依赖你给的那段文字。
5.2 故障现象二：接口通了，但返回参数永远是"空"或"未知"
假设你在平台日志里看到请求实际发出去了，返回也有 200，但模型回答"获取失败"或关键字段显示为空。这个坑出现频率极高，根因多半在响应体结构。
很多天气 API 的返回是嵌套结构，比如：
{ "status": 200, "result": { "data": { "weather": { "temp": 22 } } } }你的 OpenAPI 定义里如果只声明了顶层字段，没有把嵌套路径写清楚，模型就无法从嵌套 JSON 的深层取值，只能看到 status 和 result 这两个键。要解决这个问题，你需要在 response schema 里把嵌套结构完整描述出来，而不是只写一层 properties。一种更简单的粗暴方案是：改造后的后端接口直接拍平成一层，例如{"temp": 22, "condition": "多云"}，模型处理扁平 JSON 的可靠性明显高于深层嵌套。
5.3 故障现象三：每次触发技能时重复报错，错误信息飘忽不定
这种故障最让人头大。但把错误信息收集起来你会发现一个规律：报错内容高度相似，只是措辞不同。比如有时说"接口响应超时"，有时说"上游连接失败"。这类问题的根子多半不在技能配置，而在服务提供方的稳定性或网络链路。
排查顺序我建议：
- 先用 curl 或在线工具直接请求该 API，排除平台因素。
- 再观察是不是偶发超时——很多免费天气接口的免费额度有 QPS 限制，测试脚本一跑就爆。
- 如果你同时挂载了多个技能，检查技能之间是否互相抢占。
如果确定是外部服务不稳定，方案很简单：换服务商或加缓存。技能内部也可以做一些容错提示，在 SKILL.md 里写"如果返回 error 或 status 非 200，回复：天气服务暂时不可用，请稍后再试"。这至少保证用户体验不是崩溃的。
6. 从能用走向好用：技能编排的三个进阶思路
第一个技能跑通后，你会开始思考：怎么能让智能体同时用好几个技能？怎么让技能更省 token？怎么让技能适配更复杂的业务？这一节我把进阶方向梳理清楚。
6.1 把多个技能组合成"工作流技能"
扣子平台允许你在工作流里调用技能节点。这意味着你可以做一个"出行助理"技能，内部串起：天气查询、空气质量查询、交通限行查询三个子操作。用户问"明天能开车去市中心吗"，工作流先查天气，再查限行尾号，最后汇总输出。这是一个典型的技能编排组合方式。
设计这种组合技能时要注意一个原则：子操作之间的数据依赖要清楚。如果操作 B 需要操作 A 的返回结果作为入参，则要在工作流节点里配置好变量映射，不要指望模型自动把 A 的结果填进 B。模型擅长的是理解语义，而不是做状态管理。
6.2 技能描述里的"话术工程"：让模型少问废话、多给有用信息
这大概是最容易见效的优化。很多人的技能描述只写"技能干 什么"，忽略了"给用户看什么"。我强烈建议在 SKILL.md 里增加一个"输出风格"片段，示例如下：
## 输出风格 - 先回答核心结论，例如“上海现在 22 度，多云”。 - 只有当用户问“适合穿什么”时，再补充穿衣建议。 - 不要重复输出整个城市的天气数据表。 - 如果用户对两个城市做对比，输出时采用两行对比格式。这样做了之后，同一套 API 接口的回复质量会明显提升。在 GPT 类应用里这个叫 Prompt Engineering，在扣子技能里其实就是描述文件的工程化，两者背后的逻辑完全一致。
6.3 Token 成本优化：用字段裁剪替代全量返回
最后再提一次 Token 的问题。对大模型应用来说，Token 就是成本。如果一个技能每次调用都要把接口返回的长长 JSON 交给模型，一次对话里如果调用三次，光输入 Token 就会翻倍。
推荐两个方向：一是找到能自定义返回字段的 API 服务，在 URL 参数里加fields=temp,condition,wind之类；二是自己做一层数据中转服务，把外部接口的结果缓存并裁剪。前者门槛低，但不是所有服务都支持；后者需要一行后端代码，但对稳定性和成本标杆明显更好。
我在一个模拟项目里做过统计：原始接口返回约 1.2KB 的 JSON，裁剪后只有 300B，模型输入 token 直接下降了约 70%，回复生成时间也缩短了。对一个日调用量几千次的智能体来说，这个优化的收益相当可观。
7. 收尾之前：分享一个我反复调试后才总结出的"技能调试三板斧"
写到这里，该讲的原理和步骤基本都讲到了。最后分享一个我自己的调试习惯，算不上什么高深理论，但真能救命。
第一板斧：每次修改只动一处。无论是改描述还是改 OpenAPI 定义，一次只改一个变量，然后立刻测试。不要同时改五个地方然后对着结果猜是哪个生效的，那样只会浪费时间。
第二板斧：善用平台调试日志。扣子的调试面板会显示模型生成的函数调用参数和请求响应。这相当于给你装了个放大镜，能准确看到模型眼中的世界是什么样。你不需要猜"模型为什么没填对参数"，直接看它是怎么填的。
第三板斧：给技能准备一个"最小可复现问题集"。我通常会在 SKILL.md 旁边维护一个测试用例列表，包括十个典型提问和一个边界提问，每次发布前跑一遍。比如天气技能的最小集是："北京天气""北京明天怎么样""上海和杭州哪个热""帮我查查今天能跑步吗""不知道我在哪个城市"这五条。跑完就知道技能在真实对话环境下的表现。
……
技能的复杂度是逐步长出来的。第一版只求跑通，第二版再优化参数提取，第三版才考虑多接口编排和 token 成本。这个过程急不来，但只要你理解了一个核心原则——模型是在"读说明书"而不是"执行程序"，大部分问题就都有了答案。拿着这份实操指南，去搭一个哪怕很小的技能，跑通之后你会有一种"原来如此"的踏实感。
