最近有两个同事在 Copilot Studio 里折腾自定义 Skills，问的问题几乎一模一样：官方文档写得挺清楚，但一到自己搭建就是连不上服务、识别不了意图、JSON 校验报错。我自己的经验是，Skills 这层东西光看概念容易，真正落地要踩的坑全藏在细节里。这篇就把我跑通一个完整 Skill 的整个过程拆开聊，从设计到调试，再到最后发布，附上我踩过的具体问题和解决方案。
先说清楚这东西能做什么。Skills 本质上是在 Copilot Studio 里给 AI 助手加装一副"专用工具"，让它具备调用外部 API、查数据库、提交工单这类实际操作能力，而不只是停留在闲聊问答。适合谁看？适合手里已经有一个 Copilot Studio 环境，正准备做自定义技能，但还没理清该怎么设计输入输出、该怎么调试验证的团队或个人开发者。
1. 为什么偏偏要先做自定义 Skills，而不是直接堆 Prompt
我刚上手的时候也犹豫过，既然 Copilot 已经能理解自然语言，为什么不干脆把 API 调用逻辑写进 Instruction 里，非要搞什么 Skills？这个问题值得先说清楚，它决定了你后面整个架构怎么走。
1.1 Copilot 的技能体系里，Skills 处在哪一层
微软的 Copilot 生态里有几个容易混淆的概念：Prompt、Plugins、Skills，还有所谓的 "Connectors"。Prompt 是纯文字指令，适合简单问答和格式转换；Plugins 在 Copilot Studio 里偏向连接外部数据源；Skills 则是更完整的"可复用动作单元"——它有自己的描述文件、输入输出定义，还能在多个助手之间分享。
用一句话概括：Prompt 教 AI 怎么说，Skill 教 AI 怎么做。Skill 的定义文件（通常是 JSON 格式）把"功能描述"和"参数结构"写清楚，AI 靠这个文件判断什么时候该调用你写的这段能力，而不是靠你反复在指令里叮嘱它。这一点在项目变大后差异特别明显，指令多了容易互相覆盖，Skills 却能像搭积木一样独立扩展。
1.2 什么时候该用 Skill，什么时候不该用
我自己总结了一个粗略的判断标准，不一定权威，但很实用：
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 需要调用内部 API 并处理返回数据 | Skill | 输入输出有结构，AI 不会自由发挥 |
| 操作步骤固定，不依赖用户上下文 | Skill | 复用性强，改一处全局生效 |
| 只是让 AI 换个语气、改个格式 | Prompt | 轻量，不需要建文件 |
| 涉及多步骤对话状态流转 | Topic / Dialog | Skill 不适合管复杂对话分支 |
如果你想把 Skill 做得通用一点，比如"查天气"这种我也试过纯粹用 Prompt 加 HTTP 请求实现，但很快就发现维护成本上来了，因为天气接口的返回字段经常变，Prompt 里写死字段名，接口一变就得更新指令。换成 Skill 后，参数和返回结构都收敛在定义文件里，接口变化只影响 Skill 内部实现，助手逻辑不用跟着动。
1.3 从"能聊"到"能干活"的那道坎
Copilot 默认的对话能力再强，也只是"能聊"。让助手真正处理事务——查库存、建工单、算报价——都需要一个动作层。Skills 就是这层动作的载体。你不需要理解复杂的 Agent 框架，只需要按照约定把动作描述清楚，剩下"何时调用、怎么填参数"这类推理交给模型就行。
这也是我建议你先做一个最简单 Skill 的原因：它能帮你把整条链路理顺，包括描述文件怎么写、AI 怎么识别触发、API 返回后怎么转成自然语言回复。这条路走通了，后面加再多功能都是套同样的模板。
2. 动手前的功课：Skills 的目录结构、命名规范与触发逻辑
真正写代码之前，我花了不少时间研究项目结构。这部分看起来不起眼，但决定了你后面调试时能不能一眼定位问题。
2.1 一个 Skill 项目里到底该有哪些文件
拿我在 Copilot Studio 里的实际项目结构举例，这不是唯一的标准，但很典型：
MyAssistant/ ├─ skills/ │ ├─ asset-tracking/ │ │ ├─ manifest.json │ │ ├─ asset-tracking.json │ │ └─ scripts/ │ │ ├─ check-asset.py │ │ └─ update-asset.py │ ├─ ticket-handling/ │ │ ├─ manifest.json │ │ ├─ ticket-handling.json │ │ └─ scripts/ │ │ └─ create-ticket.pymanifest.json负责向平台声明这个 Skill 的存在，包括名称、版本、入口。asset-tracking.json才是模型要读的"说明书"，里面定义了技能描述、参数类型、必填项这些关键信息。脚本目录放的是实际执行逻辑，可以是一段 Python、一个 PowerShell，也可以是一个指向外部 API 的 HTTP 调用。
2.2 描述和触发词是灵魂，别把它当摆设
一开始我一心扑在代码上，描述写得仓促，结果就是 AI 经常在错误的时候把 Skill 拉出来，或者完全无视它。后来我才摸清：模型判断要不要调用某个 Skill，主要靠两点，一是描述文本的语义匹配度，二是参数能否从对话里顺利抽取。
描述写得好不好，直接影响召唤准确率。这里的讲究是"具体但不冗长"。比如 "查资产" 这种描述就太笼统，模型不知道哪些问题该走这里。我后来改成 "根据资产编号或名称查询企业固定资产的归属人、存放地点、当前状态" 就好多了。但描述也别写小作文，太长反而稀释关键词，让模型抓不到重点。
触发词这块不同版本的实现细节有差异，但大方向上你要把常见的问法变体都列出来。比如查资产的触发词可以写 "资产在哪" "谁在用这台电脑" "这台设备什么状态"，AI 会参考这些表达来判断调用时机。
2.3 为什么这个 Skill 用 JSON 定义而不是代码
这是被问得比较多的问题。JSON 在这里不是可有可无的配置文件，它是给模型看的"结构化提示"。模型推理时通过 JSON 的字段名、描述、示例去理解参数语义，配合 LLM 的能力，生成准确的调用参数。相比之下，如果用自然语言段落描述参数，同一个意思可能被理解出好几个版本，校验和纠错都麻烦。
而且 JSON Schema 本身支持类型约束、必填项、默认值、枚举值，这些约束能有效防止 AI 把字符串传给数字参数、漏传必填项这类低级错误。宁可定义时多写几行 schema，也别在调用时去猜。
3. 把一个真实场景装进 Skills：从设计到代码的一个完整样例
前面讲了一堆原则，下面拿我实际做过的一个 IT Helpdesk 场景来演示。这个 Skill 的功能是：用户报电脑故障时，助手能根据设备序列号查询保修信息，并自动开一个工单。
3.1 先定义好输入：序列号、问题描述、紧急程度
这个 Skill 的输入参数我设计了三个：
serialNumber（字符串，必填）：设备序列号issueDescription（字符串，必填）：用户描述的问题urgencyLevel（字符串，可选）：紧急程度，默认 "Medium"，可选 "Low"、"Medium"、"High"
定义在 JSON 里是这样：
{ "name": "create_service_request", "description": "根据用户提供的设备序列号和故障描述，查询保修信息并创建服务工单", "parameters": { "type": "object", "properties": { "serialNumber": { "type": "string", "description": "设备序列号，通常在机身标签上可以找到" }, "issueDescription": { "type": "string", "description": "用户描述的故障现象" }, "urgencyLevel": { "type": "string", "enum": ["Low", "Medium", "High"], "default": "Medium", "description": "紧急程度" } }, "required": ["serialNumber", "issueDescription"] } }这里有一点值得注意：description字段不只是给人看的，也是给 AI 看的，所以每个参数都写清楚它的业务含义，AI 才能准确从用户话里抽取值。我见过很多人这部分写得随意，比如就写"序列号"三个字，模型遇到"帮我查一下序列号是 SN123456 的电脑"这种话就不知道到底该抽哪段，结果要么报错，要么传了"SN123456"以外的多余字符。
3.2 处理逻辑：调接口、判状态、给反馈
技能内部脚本我用了 Python，通过 HTTP 请求调用内部资产系统的 API。
import requests import json def create_service_request(serial_number, issue_description, urgency_level="Medium"): # 第一步：根据序列号查资产状态 asset_api = "https://asset-internal.example.com/api/v1/assets/" + serial_number asset_resp = requests.get(asset_api, headers={"Authorization": "Bearer " + get_token()}, timeout=5) if asset_resp.status_code != 200: return { "status": "error", "message": "未能查询到资产信息，请核对序列号是否正确" } asset = asset_resp.json() if asset.get("warranty_status") != "active": return { "status": "warning", "message": "该设备保修已过期，可协助提交付费维修申请" } # 第二步：创建工单 ticket_payload = { "serial_number": serial_number, "description": issue_description, "urgency": urgency_level, "asset_owner": asset.get("owner_email", "") } ticket_api = "https://ticket-system.example.com/api/v1/tickets" ticket_resp = requests.post(ticket_api, json=ticket_payload, headers={"Authorization": "Bearer " + get_token()}, timeout=5) if ticket_resp.status_code == 201: ticket_id = ticket_resp.json().get("ticket_id") return { "status": "success", "message": f"工单已创建，编号是 {ticket_id}", "ticket_id": ticket_id } else: return { "status": "error", "message": "工单创建失败，请稍后重试或联系 IT 支持" }这段代码不是重点，重点是返回值结构要设计得"对模型友好"。我踩过一个大坑：第一次实现直接返回了后端原始 JSON，字段名全是own_email、warranty_exp_date这种简写，AI 拿到后虽然技术上讲也能读懂，但生成回复时经常磕磕绊绊，还偶尔把字段名直接抛给用户。后来我改成返回标准化的三段式：status、message、data，让 AI 优先把message里的内容转述给用户，问题一下就少了。
3.3 为什么返回值要标准化，而不是原样透传
从模型的角度想，它在生成最终回复时是"看着函数的返回结果来组织语言"的。如果返回结果是杂乱的键值对，AI 需要先做一层理解再转述，这中间就存在猜错的概率。如果把结果整理成一句接近自然语言的话放进message，AI 的工作从"理解+转述"简化为"润色+转达"，可靠性明显提升。
用生活类比来说：你让助理帮你问快递到哪了，助理拿回来的是一张写着各种代码的底单，还是直接告诉你"你的件到杭州了，预计明天送到"？Skills 的返回值就相当于助理回来报告的口径，口径越接近人话，模型越不容易答歪。
4. 最容易翻车的三个细节：JSON Schema 校验、描述冗余、响应超时
讲完能跑的流程，重点来了。这三个坑几乎每个做 Skills 的人都会踩，我一样不落全踩过，现在把它们写下来，能帮一个是一个。
4.1 JSON Schema 校验失败：引号和类型远比你以为的更容易错
有一次我信心满满把写好的 Skill 导入测试，结果平台直接拒绝加载，报错信息指向 manifest 文件。查了半天，导因是编辑器"自动修复"了引号，把半角引号变成了全角。这类问题最隐蔽，因为肉眼几乎看不出来。
排查链路是这样的：先用平台自带的校验工具定位到具体文件，发现是manifest.json；然后用 VS Code 打开，开启 JSON 语法高亮，一眼就看出有一行的引号颜色不对；最后重新手打一遍引号，导入立刻通过。
除了引号，类型不匹配也是高频报错点。比如urgencyLevel如果定义成integer，但调用时传了"High"，校验就会失败。AI 按你的 schema 参数约束来，enum和type要写严一点，宁缺毋滥。
提示：写完后养成习惯，先用校验工具跑一遍，别直接上测试。这类低级错误一旦上线，用户侧的报错反馈会比调试期难定位十倍。
4.2 描述写太长，AI 反而不认识这个 Skill
这个坑特别反直觉。我开始觉得描述写得越细，AI 理解越准，结果发现恰恰相反。有一次我把某个 Skill 的描述写到两百多字，测试时它几乎从不被触发。后来把描述精简到一句话加几个触发词，准确率立刻上来了。
原因在于，描述越长，关键词被稀释，模型在做语义匹配时反而不容易抓到核心意图。你可以把描述想象成给 AI 的"搜索引擎摘要"，摘要必须精炼、突出业务动作和关键实体，而不是把所有背景都塞进去。
我现在的写法套路是："根据【关键实体1】和【关键实体2】，执行【具体动作】，并返回【关键结果】"。比如 "根据设备序列号查询保修状态并返回剩余天数"，一句话搞定，需要详细说明的内容放进参数描述和示例里。
4.3 外部 API 响应超时，AI 直接把锅甩给用户
最后一个坑在联调阶段冒出来。测试环境里内部 API 偶尔响应超过 5 秒，而平台对 Skill 调用有响应时长限制。超时后 AI 会自己编一个失败原因，常见的是话术 "I'm sorry, but I couldn't find that information" 之类。用户看到的是助手的"无辜抱歉"，实际上底层是接口超时。
我排查了很久才发现根因，后来做了两层处理：
- 脚本内设置
timeout=5，超过时间立即返回结构化错误信息，而不是无限等待。 - 在错误信息里明确写"系统暂时无法连接资产服务，请稍后重试"，让 AI 照着这个口径回复，不再自行发挥。
效果立竿见影。用户至少知道是系统问题，而不是一脸懵。这个经验后来也用在其他几个 Skill 上，特别是依赖外部系统的，统一都加上了超时保护和兜底文案。
5. Skill 发布与后续维护：版本、权限、可观测性
一个 Skill 跑通测试不代表完事，发布和长期维护才是真正考验工程习惯的部分。
5.1 发布到不同的渠道，行为竟然有差异
我在 Teams 里测试没问题，但发布到企业门户后，同一句话有时触发有时不触发。比对后发现，原因是不同渠道对上下文窗口的处理不太一样，Teams 会话里前面聊过设备型号，模型能结合上下文推断序列号；门户里新会话没有历史，AI 就会追问用户。
这里的对策是：在 Skill 描述里写清楚"如果用户没有提供序列号，请直接询问，不要尝试猜测"。也就是说，你要提前预判"信息缺失"这个场景，把 AI 的行为引导好，而不是指望它在所有渠道都表现一致。
5.2 权限模型：别把 Admin Key 写进 Skill 代码
有次我在技能脚本里直接写死了内部 API 的访问密钥，想着"反正是内部系统"。后来安全审计被打回，连夜改成调用凭据托管服务，从环境变量读取。这里的经验是：Skill 脚本本质上跑在你的服务器或云环境里，任何硬编码的机密都可能泄露，正确的做法是利用平台的配置项或独立密钥管理服务。
顺带一提，内部 API 的权限范围也要做最小化。比如这个工单 Skill 只需要创建工单和查询资产，那就不要给它分配删除或修改权限。宁可权限不够再补，也别一开始就给个万能钥匙。
5.3 日志与监控：每次调用都留下痕迹
最初版本我没加调用日志，出了问题全靠用户转述"刚才助手说错误了，到底哪错了"，根本没线索。后来我在 Skill 脚本里加了结构化日志，记录每次调用的参数、耗时、返回码，输出到日志平台。
这里我建议记三个关键指标：调用次数、失败率、平均响应时长。特别是失败率，如果某个 Skill 突然失败率升高，大概率是依赖的 API 变了或凭据过期了，日志一出定位很快。这个习惯帮我在一次接口字段变更时，十分钟内就找到了受影响的 Skill 并完成修复。
5.4 版本管理：一个 Skill 也要走小步迭代
很多做 AI 项目的人容易忽略技能本身的版本管理。我的做法是：manifest.json里的版本号每次改动都递增，然后再发布；同时在描述文件里留个changelog字段，记录这次改了什么。这样做的好处不只是回溯方便，更重要的是，如果新版本上线后出现沟通质量问题，你可以快速回退到上一个稳定版本。
6. 做完这个项目后，我对 Skills 的重新理解
这里聊点个人体会。以前我总觉得 AI 助手的能力取决于模型多聪明，实际做下来发现，边界和结构同样重要。Skills 本质上是在给模型划定"能力边界"，让它知道哪些事可以做、怎么做、做到什么程度。模型负责聪明，Skills 负责靠谱。
有一次我试着让助手处理"模糊请求"——用户说"帮我搞定这台电脑的问题"，但没有序列号也没有问题描述。我发现，把这种边界情况想清楚并写进 Skill 描述后，助手会主动追问信息，而不是瞎猜或乱答。这说明 Skills 不仅是工具注册表，也是行为约束机制，设计得好能大幅提升用户体验的一致性。
再分享一个我自己觉得特别值得的习惯：每次新做一个 Skill，都用一套固定的测试用例去评估，包括正常查询、参数缺失、无权限、超时、接口返回异常。这套用例跑一遍，基本能覆盖大部分线上问题，省下的沟通排查时间远超写用例的投入。另外，调试时多留意 AI 在中间步骤生成的内容，它如何解读你的参数描述、如何决定调用时机，这些观察比看报错更能帮你优化触发效果。
