How to build custom skills：从需求到上线的实战指南
插件市场里找不到刚好贴合你们工单流、审批流、老系统接口的时候，基本就要自己写 Skill 了。写出来不难，难的是上线以后别变成无人敢动的黑盒。
一句话：先把「什么叫做完」说清楚，再写代码；契约和测试跟功能同等重要，否则后面全是扯皮。
什么时候值得自定义
常见几种：要接 CRM、ERP、内部工单，字段和权限规则跟公开市场插件对不上；同一动作在你们公司要多级审批或留痕；AI 侧和现有业务系统必须对齐到「这一步写库、那一步通知人」——这种时候，自定义不是为了炫技，是为了后面查账、回滚、甩锅时有据可查。
一个能上线的 Skill，脑子里要有四层
不用背概念，按顺序想就行：进来什么参数、中间调谁、出去什么结果、挂了怎么记日志和限流。很多人只写中间那层，结果联调时才发现 Agent 根本不知道失败是该重试还是该改口回复用户。
- 输入：类型、必填、默认值、边界（空字符串算不算？时区按哪？）
- 执行：超时几秒、重试几次、哪些错误绝对不重试（比如 4xx 里明确是权限问题）
- 输出：成功 JSON 长什么样；失败时最好用统一结构（例如带
code、message、是否可重试），Agent 才好决策 - 治理：关键步骤打日志、敏感字段别明文落盘、该限流就限流、版本要能回滚
从 0 到 1，可以按这条线走
先对齐，再动手。 和业务方坐半小时，把触发方式搞清楚：用户一句话触发、定时跑、还是上游系统推事件？不同触发，超时和重试策略不一样。「成功」是回用户一句话，还是写数据库某张表？谁拿测试账号签字验收？
先做最小一条链路。 一个 Skill 干一类事；第一条链路跑通之前，别顺手把五个业务动作塞进去。超时、权限不够、下游 5xx，早点用假数据或 mock 打一遍，别等预发第一次见。
绑到真实 Agent 上遛一圈。 至少走通：用户侧怎么问 → Agent 怎么调 Skill → 用户看到什么 → 日志里能不能对上号。
再谈灰度。 小流量开几天，看调用量、错误率、P95。指标难看就回滚，别硬扛——回滚不丢人，全站炸锅才丢人。
需求怎么拆，才不至于做到一半返工
对齐会可以很短，但几个问题必须有答案：失败谁兜底、转人工时要带什么上下文（工单号、用户 ID、上次请求 ID）；Skill 允许读写字段边界在哪；有没有个人信息、要不要脱敏。
把结论压成一页纸，后面接口设计和测试用例都从这页长出来，比写完再改需求省一个迭代。
契约写到「别人不用读你源码」
参数枚举用固定字符串，别出现「传 1 也行 true 也行」这种历史包袱。涉及下单、扣费、建资源，幂等键或业务去重要想好——用户连点两次、网络重试一次，不能变成两笔单。
团队里维护一份表格或简易 OpenAPI，新来的同事接集成时心里不慌。
测试别只测「一切正常」
缺参数、类型错、越权 Token、下游超时和烂 JSON、同一用户短时间狂点——都过一遍。数据边界也试试：空列表、超大 JSON、字段特别长。有条件的话，预发里抽一点脱敏后的真实形状数据，开发环境造不出来的脏数据往往在那儿等你。
文档分三类读者，各取一段
开发同事看：依赖、环境变量、本地怎么 mock 下游。运维同事看：健康检查、日志里搜什么关键字、告警大概设在哪、怎么回滚。业务同事看：能做什么、别承诺什么、用户典型怎么问、失败时界面上会看到啥。
文末顺手写一句：当前测过的平台版本、最近大改日期、已知坑——半年后的你会感谢现在偷懒写上的这一行。
发版怎么跟人说人话
版本号规则团队统一就行，破坏性改动写在变更日志最上面。发版前在群里丢一条短 release note：行为变没变、要不要改配置、会不会影响线上正在进行的对话。多个产品共用一个 Skill 时，大改前先知会一声，别撞上大促窗口。
发布前，自己勾一下
- 输入输出能说清楚，最好有 Schema
- 异常路径测过，不是只测 happy path
- 灰度与回滚想好了
- 任意一次失败能从日志追到请求
- 业务方用测试账号点过头
延伸阅读
参考来源
- 各平台官方的 Skills / 插件开发说明（以你实际在用的版本为准）
- 团队自己的上线 Runbook 和 on-call 习惯
- 本站学习路径、安全指南里和工具调用相关的步骤
更新：BestClaw 编辑部，2026-03-21。
说明：实践向文章，不对任何厂商功能做承诺；落地以你方环境为准。
作者
BestClaw 编辑部