刚入职的时候，团队丢给我一个任务：把现有的自动化测试能力全部迁移到 Agent 调用的 Skills 体系里。我打开代码库，200 多个脚本文件散落在不同项目里，注释不全，一半依赖硬编码的页面元素，另一半依赖早已过期的接口文档。
头三天我基本在“考古”。后面四天我把这些烂摊子拆干净，重新梳理出一套企业级 Skills 库的设计模式。这篇文章不是“Skills 入门”，是我在工程落地过程中挖出来的东西——哪些设计被反复踩坑，哪些模式在大规模使用下会崩，哪些做法在字节、腾讯的扣子、SkillHub 里能找到影子。
不列空洞原则，直接走一遍完整的设计推演。
如果你正在做 Agent 测试体系，或者被要求“把测试能力 Skill 化”，下面这些能让你少走大半年的弯路。
- 为什么传统脚本一“Skill化”就崩
多数人把 Skill 理解成“给脚本包一层皮”。写个 YAML 声明参数，把原来跑在 pytest 里的代码丢进去，加个 description 说“这个 Skill 能做接口测试”。然后交给 Agent 调用。
上量之后马上翻车。三个典型症状：
Agent 选不中：描述写了，但 Agent 在任务规划阶段就是不用你这个 Skill，反而自己瞎猜。
上下文爆炸：每次调用把整个接口文档塞进 prompt，Token 费飞涨，响应越来越慢。
副作用不可控：一个 Skill 执行失败，Agent 不知道现在系统处于什么脏状态，后续调用连环出错。
问题不在“脚本写得好不好”。问题在设计范式没切过来。
脚本是为“人按步骤执行”设计的，Skill 是为“Agent 按意图调度”设计的。这是两个物种。你用给人看的食谱去训练机器人做菜，它连“少许盐”都理解不了。
本质上，Skill 需要提供三样脚本给不了的东西：可被 Agent 理解的能力描述、可预测的执行边界、可组合的原子接口。缺一样，调度就崩。
- 企业级 Skills 库的核心骨架
拆完自己团队的脚本资产，又翻了扣子 2.0 的 Agent Skills 设计、腾讯 SkillHub 的 Skill 标准，我提炼出一个三层骨架。几乎所有能在生产环境跑稳的 Skill 体系，都长这个结构：
2.1 注册与发现层
这层解决的是“Agent 怎么找到你”。
不是写一段 description 就完了。Agent 做任务规划的时候，是靠语义匹配 + 能力标签来筛选 Skill 的。实践中有效的做法是三层筛选：
领域标签：接口测试、UI 验证、数据校验、性能压测……每个 Skill 至少挂一个主标签、两个辅助标签。
意图描述：用“是什么 + 解决什么问题 + 适用场景 + 不适用场景”四段式写。尤其“不适用场景”这一项，直接决定 Agent 会不会滥用你的 Skill。
前置指纹：声明执行这个 Skill 需要哪些前置条件，比如“需要目标接口的 OpenAPI 文档已加载”“需要登录态 Token 已缓存”。Agent 在规划阶段会检查前置是否满足，不满足就不调用。
踩过的坑：不要拿测试用例标题当 Skill 名。“验证支付接口幂等性”不够，改成 payment.api.idempotency_check，带命名空间，方便 Agent 做层次化搜索。
2.2 能力抽象层
这层决定 Skill 的复用半径。设计差的 Skill，换个项目就得重写；设计好的，跨业务线直接调用。
核心设计要素：
输入 Schema：用 JSON Schema 做强类型约束，而不是靠自然语言描述参数。Agent 对结构化约束的遵循程度远高于自然语言。字段里至少包含：参数名、类型、是否必填、默认值、示例值、合法范围。能写枚举就写枚举，别让 Agent “自由发挥”。
输出 Schema：必须包含三部分——执行状态码（成功/失败/部分成功）、结构化结果数据、可观测信息（执行耗时、调用日志、关键中间状态）。尤其是“部分成功”这个状态，很多 Skill 根本不设计，导致 Agent 不知道下一步是重试还是降级。
依赖声明：直白地写出你这个 Skill 需要调哪些 MCP 工具、依赖哪些其他 Skill。这是编排的基础。没有这个声明，Agent 只能盲目尝试，效率和准确性直接腰斩。
一个可落地的 Skill 元描述模板（JSON）：
{
"skill_name": "api.contract.verify",
"labels": ["api_test", "contract", "regression"],
"intent": "验证接口实际响应与 OpenAPI 契约定义的一致性",
"applicable": "已有 OpenAPI 规范文档的 RESTful 接口",
"not_applicable": "GraphQL、gRPC、无规范文档的存量接口",
"precondition": ["openapi_doc_loaded", "target_env_accessible"],
"input_schema": { ... },
"output_schema": { ... },
"dependencies": ["mcp.browser_invoke", "mcp.db_query"]
}
2.3 执行与副作用管理层
这一层是区分“玩具”和“生产级”的分水岭。
Agent 调用 Skill 不是单次调用就结束的。实际测试场景中，一个 Skill 失败后，Agent 需要知道三件事：环境是否被污染、是否可重试、是否可降级。
这就要求每个 Skill 在输出时明确携带副作用声明：
本 Skill 对系统状态做了什么改变（新增了订单、修改了配置、消耗了优惠券）
失败后回滚策略（自动回滚 / 需人工介入 / 不可回滚）
幂等性标识（重复调用是否安全）
我见过最严重的事故：一个清理测试数据的 Skill 在执行超时后，Agent 判断失败自动重试，结果把下一轮测试的有效数据全清了。如果当时声明了“本 Skill 不可自动重试，失败须人工确认”，就不会发生。
工程实践上，我们给每个 Skill 加了一个 side_effects 字段：
"side_effects": {
"changes": ["create_order"],
"rollback": "call skill: order.cleanup.by_trace_id",
"idempotent": false,
"auto_retry": false
}
Agent 调度器读到这个声明后，会自动忽略重试逻辑，并在失败后触发回滚链路。
- 决定复用半径的三个设计决策
很多人觉得 Skill 复用就是“写得通用点”。实际上有三个决策，直接决定一个 Skill 能用一年还是只能用一周。
决策一：抽象到业务语义层，而不是 UI 元素层
错误做法：skill: click_login_button
正确做法：skill: user.auth.login
前者绑定按钮选择器，UI 一改就废。后者描述的是“完成用户登录这个业务动作”，内部实现可以随时从按钮点击换成 API 直调。Agent 只关心“登录”这件事能不能完成，不关心你怎么完成。
决策二：Skill 间通信靠上下文传递，不靠全局状态
多个 Skill 协作时，数据怎么传递？新手会开一个全局变量，执行链里大家往里读写。上量后并发一跑，数据全串了。
正确的模式：每个 Skill 接收上下文对象，返回上下文对象。Agent 负责把上一个 Skill 的输出映射为下一个 Skill 的输入。Skill 本身不持有任何跨调用的状态。
决策三：版本控制做到 Skill 级别
一个 Skill 库里有 50 个 Skill，只改了其中一个，不能让整个库升版。我们采用 Skill 粒度的 SemVer：每个 Skill 独立版本号，Agent 在注册中心按版本约束拉取兼容的最新版。这跟微服务的版本治理逻辑一模一样。
- 让人头皮发麻的副作用问题，以及解决模式
前面提到了副作用声明。这还不够。实际运行中，最常见的三类副作用问题，需要对应模式去解决。
数据污染模式
问题：测试执行中产生的脏数据残留。
解法：伴随式清理 Skill。每个会产生数据的 Skill 必须注册一个伴随的清理 Skill，Agent 在任务结束时统一调度。不是“有空再清”，而是“调度器强制触发”。
资源泄漏模式
问题：Skill 创建了临时资源（文件、连接、Token）但没有释放。
解法：生命周期钩子。每个 Skill 初始化时需要在执行器中注册 on_complete 和 on_error 两个钩子，无论执行结果如何，钩子必须跑完。不是依赖开发者自觉，是框架强制。
状态毒化模式
问题：一个 Skill 修改了全局配置，后续 Skill 全部在错误配置下运行。
解法：不可变的上下文快照。Skill 接收的上下文是快照，返回的上下文是新快照，原始上下文不会被修改。Agent 随时可以丢弃当前分支，回到上一个快照重试。这个设计借鉴了函数式编程里不可变数据的思路，在 Agent 执行链里非常有效。
- 可被截图传播的设计原则
拆完这一周，能总结成几条可以直接贴在工程文档前面的原则：
Agent 是调度者，Skill 是执行单元，不要让 Skill 替 Agent 做决策。
一个 Skill 只做一件事，但要把这件事的副作用、边界、失败模式全部暴露干净。
输入输出强类型化。别让 Agent 猜，也别让下游猜。
复用不靠“写得通用”，靠“抽象到业务语义层”和“声明式依赖”。
没有副作用声明的 Skill，在生产环境是定时炸弹。
- 从“会用 Skill”到“会设计 Skill 体系”
回到实际工作里，如果你现在被要求开始构建团队的 Skill 库，建议按这个顺序推进：
第一阶段：清理存量。把现有脚本按业务语义重新归类，识别哪些是强绑定 UI/接口的，哪些可以抽象到业务层。
第二阶段：定义元描述标准。先不写代码，把上面提到的 Skill 元描述模板定下来，团队里所有人共用一套标准。
第三阶段：优先封装高频、稳定、低依赖的能力。比如接口契约验证、登录态注入、基础数据校验。这些是 Agent 调用频率最高的原子能力。
第四阶段：建立 Skill 注册中心和质量仪表盘。跟踪每个 Skill 的调用次数、成功率、平均耗时、被降级次数。数据会告诉你哪些 Skill 设计得好，哪些需要重写。
第五阶段：引入编排模板。对于复杂测试场景，把多个 Skill 的编排模式固化下来，Agent 直接调用模板，而不是每次都从零规划。
最后一个要反复想的问题：
你团队现在跑的几百个测试脚本里，哪些适合抽象成 Skill，哪些天生就不适合 Agent 调用？
如果你还没开始问这个问题，一年后这些脚本大概率会变成没人维护的技术债。而能够回答这个问题的人，已经在构建下一个周期的测试基础设施了。
一个值得反复想的问题：
你现在的测试体系里，哪些环节可以抽象成Skill让Agent直接调用，哪些环节必须人工做最终判断？
如果这个问题你还没有明确的答案，那么你的体系也许还停留在“脚本时代”。而当AI开始接管测试执行层，能够清晰回答这个问题的人，才是在定义规则，而不是被规则定义。
