微信官方把「小程序 AI Skill」做成了工具链：拆透腾讯 ai-mode-skills 的 generate / validate / eval

学习日期：2026-06-17 ｜ 对象：wechat-miniprogram/ai-mode-skills（腾讯官方，monorepo） 一句话：这是迄今我见过的、把「Skill」从概念做成工业流水线最完整的一份官方实现——它不是教你怎么写 Skill，而是给了你一套「从存量小程序源码自动生成 Skill → 真机校验修复 → 模拟用户评测」的三件套。

博客里这阵子拆过三条关于 Skill 的内容：Aaron 说「拉开差距的是 Skill 不是模型」（认知层）、把一个专家 Vibecode 成 Skill（方法层）、老板 Skill 人格蒸馏（玩法层）。它们都在讲「Skill 是什么、怎么做」，但用的都是 Claude / Anthropic 那一脉的 Agent Skill。

这次不一样。腾讯把「Skill」这个词，长在了微信小程序里——而且做法和 Claude 那套，同名、却是两种动物。

这篇笔记干三件事：① 把这套官方「小程序 AI Skill」规范讲清楚（目录、契约、红线长啥样）；② 把它和我们熟悉的 Claude Agent Skill 逐维度对比，讲透同与异；③ 抽出对「想自己做 Skill 的人」真正有用的启发，外加一份能直接照抄的上手步骤。

一句话定性

这是一份**「不信模型、什么都要验」的工程化 Skill 规范**。它的锋利之处不在于又造了一个 Skill 格式，而在于它把「Skill 能不能用」从「模型自觉」变成了可静态校验、可真机执行、可端到端评测的硬指标。如果说 Claude 的 Skill 是「写给模型看的说明书」，微信这套就是「编译给小程序跑的可执行件 + 一份机器可读的契约」。

先看全景：三个工具，一条流水线

整个仓库是一个 monorepo，3 个互相交棒的独立 skill：

Skill版本它干什么
wxa-skills-generate0.1.20生成：分析小程序源码（含压缩 / 混淆），识别业务步骤，提取网络接口与 JSAPI，生成符合 wx.modelContext 规范的技能分包 skills/，并改 app.json / project.config.json 完成集成
wxa-skills-validate0.1.18校验：对 skills/ 产物跑「静态校验 → 真机执行 → 渲染验证 → 交付文档」闭环，按错误类型就地修复源文件
wxa-skills-eval0.1.18评测：从 AI 视角端到端评测一个 Skill 的意图理解、调用轨迹与答案质量，模拟真实用户多轮对话，产出多维报告

它们串成一条单向流水线：

小程序源码 ─▶ generate ─▶ skills/ 产物 ─▶ validate ─▶ 真机/渲染验证 ─▶ eval ─▶ 评测报告

注意一个很克制的职责切分：generate 只生成、绝不自己校验（生成完强制交棒 validate）；validate 只校验和修复、不重设计接口（要重设计就退回 generate 的某个阶段）。每个 skill 都把自己的边界写死在 SKILL.md 第一屏——这本身就是「Skill 该怎么写」的一个示范。

这套「小程序 AI Skill」规范，到底长啥样

要看懂它和 Claude Skill 的区别，先得搞清楚它定义的「Skill」由什么构成。核心是两个原子 + 一份契约。

原子接口（apis/）：暴露给 AI 的「可调用能力」

一个原子接口就是一个被 wx.modelContext.registerAPI(name, fn) 注册的 JS 函数，放在 skills/{skill}/apis/{name}.js。它对外暴露给「小程序 AI」（微信内置的那个对话 Agent），是 AI 真正能 call 的东西。

它的返回值是固定结构——content（给 LLM 看的文本）+ structuredContent（对应 schema 的结构化数据）+ _meta（对 LLM 不可见、传给 UI 组件）：

// apis/searchItems.js
async function searchItems(params = {}) {
  console.info('[ai-mode] searchItems 入口, params=', JSON.stringify(params))
  try {
    const data = await request({ url: '/api/items/search', /* ... */ })
    return successResult('找到 N 个商品', { items: data.list })
  } catch (err) {
    console.error('[ai-mode] searchItems 出错:', err.message)
    return errorResult(`操作失败: ${err.message}`)
  }
}
module.exports = searchItems

原子组件（components/）：把返回值渲染成一张「卡片」

这是微信这套和 Claude Skill 最不一样的地方之一：每个接口的返回数据，要渲染成对话里的一张可视卡片。原子组件是个标准小程序组件（index.{js,json,wxml,wxss} 四件套），路径强约束为 components/{name}/，且必须与契约里的 componentPath 字符串完全相等。

而且它带一套相当严的设计规范：5 档宽高比（最小高 4:1 ~ 最大高 1:1）、圆角 4px、边距 16/12/8 三档、字号 17/15/12 三档配 0.9/0.45/0.3 透明度分层、容器超出即裁剪、不支持纵向滚动（横向超长才允许 <scroll-view scroll-x>）。甚至有高度预估公式 availableHeight = maxHeight - 97，超了自动决策——优先换大档位，再不行纵向内容转半屏、横向内容转横滚，全程不打断问用户。

为什么这么轴？因为它跑在消费级的、亿级用户的对话框里——卡片不能溢出、不能错位、不能在深色模式翻车。这是 Claude Skill（文本进文本出为主）完全不需要操心的维度。

mcp.json：单一真源的「契约」

这是整套规范的中枢。每个接口在 mcp.json 里有一条记录，含 name / description / inputSchema / outputSchema / _meta.ui.componentPath：

{
  "apis": [{
    "name": "searchItems",
    "description": "根据关键词检索商品，返回商品列表",
    "_meta": { "ui": { "componentPath": "components/item-list/index" } },
    "inputSchema":  { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] },
    "outputSchema": { "type": "object", "properties": { "items": { "type": "array" } } }
  }]
}

看出来了吗——这就是 MCP（Model Context Protocol）的工具 schema。name + description + inputSchema + outputSchema，一个原子接口本质上就是一个 MCP tool。微信这套「小程序 AI Skill」，骨子里是「一捆 MCP 工具 + 每个工具结果的渲染卡片 + 一份路由说明」。规范甚至硬性要求：契约只在 mcp.json 一处维护，SKILL.md 里禁止再出现参数表 / 返回值表——单一真源，防漂移。

SKILL.md：被「提纯」成纯路由说明

每个技能也有一份 SKILL.md，但它的定位被收得极窄——只写路由，不写手册。规范规定它只能有 5 节、且按序排列：

  1. 能力域定位（一句话）
  2. 触发场景（3~6 条「用户原话」few-shot，口语化）
  3. 不适用范围（反例，避免和兄弟 skill 抢活）
  4. 前置条件（登录 / 授权 / 区域等硬约束）
  5. 使用顺序（能力间的业务依赖）

并且通篇禁止出现驼峰 apiName、inputSchema、参数表、componentPath、storage key、安装 / CLI 运维。一句话：SKILL.md 的唯一 KPI 是「让调度方用最少 token 判断这事该不该路由给我」。

这个「SKILL.md = 纯触发判断、契约另放」的切分，是这份规范里最值得我们偷师的设计——后面会展开。

红线：用「白名单 + 独立分包」把约束写进结构

两条硬约束撑起了整套规范的安全性：

  • JSAPI 白名单：接口侧、组件侧各有一份可用 wx API 清单，清单外的一律按「不可迁移」处理（如 wx.navigateTo / showToast / getUserInfo 全禁，老接口 chooseImage 自动换 chooseMedia）。组件侧更严，只能收数据、做预览、读系统信息，连业务网络请求都要显式声明 scope.dynamic。
  • 独立分包隔离：Skill 跑在 independent: true 的独立分包里，与主包 JS 环境物理隔离——禁止 getApp()、禁止跨包 require、不依赖主包登录态。所有依赖（鉴权、云初始化、storage 初始化）必须自包含：每次执行接口前自己 ensureLogin() 走一遍登录，token 存模块级变量不写 storage。

还有 6 条「直接终止生成」的阻断规则——依赖小程序插件、找不到源码、依赖非白名单 JSAPI 无替代、app.json 缺 lazyCodeLoading: requiredComponents 等，命中就停、绝不硬凑。

三个工具，逐个看里面的「聪明设计」

generate：6 个阶段 + 一招「不信静态就真机探测」

生成走 6 个强制阶段：0 业务澄清 → 1 项目扫描 → 2 业务识别 → 3 接口提取 → 4 接口设计 → 5 代码生成 → 6 配置集成，每个阶段有契约（入口条件 / 产出物 / 阻断条件），不产齐不许跳。

最值得说的是阶段 3 的运行时探测（probe）。当源码被压缩混淆、URL 动态拼接、请求带签名、响应结构推不出来时（命中 T1~T6），它不靠猜——而是用 miniprogram-automator 拉起真机，evaluate 覆写 wx.request，实地抓一次真实的请求参数和响应数据，再据此生成接口。

这一招直接对应一条我们自己也信的纪律：别信你对代码的阅读，跑一遍看真值。规范里甚至明文写「禁止盲目猜变量名——猜出来的代码会在 validator 大量失败」。

validate：本质是一张巨大的「报错 → 真因 → 修法」对照表

validate 跑「静态校验（V001~V016 规则）→ 真机 execute → render 渲染验证 → 交付文档」闭环，验收目标不可降级：每个接口都得 execute 成功，每个带组件的接口都得 render 过「5 项核对」，单接口连修 5 轮不过才允许挂起。

它最厚的部分，是一套失败分类学：静态错分 T1~T9（命名 / Schema 不一致 / 组件绑定 / 白名单违规 / 注册缺失 / 依赖链路 / 粒度错……），运行时错分 A/B/C/D 类（参数 / storage / 代码网络 / 渲染裁剪），每一类都配「识别特征 + 修复范围 + 具体动作」。

它还有两条铁律值得记：

  • 「真相只在主包里」：分包是主包逻辑的独立拷贝，修 bug 必须回去读主包源码定位真实逻辑，禁止在没读主包的情况下臆测改分包。
  • render 不能只看退出码：判「卡片有没有被裁剪」，要去读 consoleMessages 里的 [ai-mode] ... overflow monitor=on 基线日志和有没有 overflowed=true——日志是真机失败时唯一的排查依据。

这套东西，整个就是 Aaron 那句「有价值的 Skill 不是教 AI 成功，是告诉它哪些坑别踩」的工程化实体：validate 的价值密度，全在那些错误对照表里。

eval：13 节点 pipeline，让「模拟用户」来考你的 Skill

eval 是独立的 Node 工程（CLI + Web UI），跑一条 13 节点串行管线，核心思路是自动构造真实用户任务 → 扮成用户和小程序 Agent 多轮对话 → 给全过程打分 + 缺陷归因：

start → component_check → gen_api_deps → explore → entity_pool → skill_review
   → (每个 case) gen_intent → gen_checklist → gen_trajectory ×K → eval ×K → attribution ×K → pass_k
   → gen_report（聚合出 HTML 报告）

它会基于你在 app.json::agent.skills 里声明的 Skill，结合页面与原子能力，自己编出贴近真实场景的用户任务，然后模拟用户走完意图理解 → 参数收集 → 调用执行 → 结果回复全链路，最后把失败归因到具体环节（是意图没懂？轨迹错了？还是回复不行？），还支持 pass@k 多次独立采样看稳定性。

这正是 Aaron 说的「最小可复现单元」拉满版——一个 Skill 不靠「我觉得能用」，而靠「一个模拟用户能不能端到端把任务跑通」来验收。

核心对比：微信「小程序 AI Skill」 vs Claude「Agent Skill」

两个都叫 Skill，都在兑现「Agent + Skill」那张蓝图，但它们是为不同宿主、解不同问题造的。把它们摆一起，反而能更清楚地看到「Skill」这个概念的两种极端形态。

维度Claude / Anthropic Agent Skill微信 小程序 AI Skill
载体一个文件夹 + SKILL.md（散装脚本 / 参考资料可选）一个独立分包：mcp.json 契约 + index.js 注册 + apis/ 实现 + components/ 卡片 + 路由 SKILL.md
本质是什么写给通用模型看的「说明书 + 工具箱」一捆 MCP 工具 + 结果渲染卡片 + 路由说明
谁来执行模型自己读说明、在 shell 里跑脚本接口代码跑在小程序沙箱里，AI 只决定调哪个、传什么参（MCP tool-calling）
能力边界开放——宿主给什么工具 / shell 就能用什么白名单封闭——只允许清单内的 wx API，禁导航、禁 modal、组件标签受限
要不要 UI基本文本进文本出每个结果都渲染成一张卡片，还带严格的尺寸 / 主题 / 溢出规范
结构化程度松散散文，靠模型理解刚性契约 + 静态规则 + 真机校验，不信模型自觉
配套工具链你直接写就行，无强制校验 / 评测generate（从源码生成）+ validate（真机修复）+ eval（模拟评测）一条龙
来源多为从零手写专家经验多为从存量小程序源码自动派生

但剥开差异，它们共享一套惊人一致的底层哲学——这才是「Skill」作为一种范式真正立得住的地方：

  1. 都把「何时触发」当头等大事。Claude Skill 的 description 字段、微信 SKILL.md 的「触发场景」节，干的是同一件事：让 Agent 在最少信息下判断「这事归不归我管」。微信甚至把它提纯成「只准写路由、禁写手册」——这几乎是 Claude description 字段的强化纪律版。
  2. 都用渐进式披露。Claude：平时只看 name + description，触发了才读完整 SKILL.md。微信：先读 SKILL.md 做路由判断，要调用了才看 mcp.json 契约。两者都是「用到哪翻哪」，所以一个 Agent 能挂着几十上百个 Skill 不糊。
  3. 都把「触发判断」和「怎么做」分了层。一个 Skill 最贵的不是实现，是「被正确地用 / 不被错误地用」。
  4. 都在兑现 Aaron 的宣言——把「已有的能力 / 专家经验」封装成 Agent 可加载的资产。Claude 封装的是人脑里的方法论，微信封装的是已经在线上跑的小程序业务。

一句话收束这组对比：Claude Skill 是「给模型的思维插件」，微信 Skill 是「给 Agent 的能力 + 界面外设」。 前者赌「模型够聪明，给它说明书就行」；后者赌「消费级场景不能赌，所有东西都要编译、校验、评测过」。没有谁对谁错——它们是同一个词，在「开放创作工具」和「亿级消费产品」两种约束下，长出的两副样子。

对「想自己做 Skill 的人」，这套官方实现给了什么启发

这是这次学习我最想沉下来的部分。微信这套虽然是给小程序的，但它把很多「做 Skill 的隐性纪律」显式化、工程化了，几条可以直接搬到我们自己（不管是 Claude Skill 还是别的 Agent）的做法里：

  1. 契约和路由说明分开放，且单一真源。微信硬性规定「参数 / 返回只在 mcp.json，SKILL.md 禁止重复」。我们做 Skill 也该这样：SKILL.md 的 description 专心优化「触发判断」，别塞成功能清单；真正的接口 / 参数细节放它处，避免两边漂移、互相说谎。

  2. 把红线写成「检查」，而不是「祈祷」。Aaron 说「把红线写死」，微信更进一步——白名单和 V001~V016 是会执行的静态规则，违规直接报错，不指望模型自觉。凡是能变成 lint / 校验脚本的约束，就别只写在 prose 里。

  3. Skill 的护城河是那张「失败兜底表」。validate 整个就是一部错误分类手册。这印证了「模型已经会成功路径，你的失败清单才是它学不到的」——做任何 Skill，都专门留一张「报错 → 真因 → 修法」表，比写十遍「正确做法」值钱。

  4. 不信静态，要跑真机。generate 的 probe、validate 的真机 execute，核心都是「别信你对代码 / 数据的推断，实地验一次」。我们做 Skill 同理：链路里每一步可验就验（看日志关键行、看返回真值），别改完就当成了。

  5. 可验收才算做完。eval 的「模拟用户 + pass@k」是「最小可复现单元」的拉满版。给自己的 Skill 配一个能端到端跑通的例子 / golden set，「我写了个 Skill」和「它真能一次跑通」之间隔的就是这个。

  6. 最好的 Skill 往往是「蒸馏」出来的，不是凭空写的。generate 的整个出发点是从已经在跑的小程序源码反推 Skill。这和 把专家 Vibecode 成 Skill、和我们自己「存判断不存搬运」的沉淀法是同一个方向：高价值的能力，多半藏在「已经 work 的东西」里，你的活是把它提纯、固化、封装成可加载件。

迁移提醒：把「做小程序 AI Skill」换成「带新人 / 写团队 SOP / 做内部工具」，上面六条照样成立。微信这套的真正贡献，是把「怎么把一类能力做成可靠的、可复用的、可验收的封装件」，写成了一份能照着执行的工程规范。

开发者怎么上手（可复制步骤）

如果你手上有小程序、想接微信 AI 生态，这套的上手路径是这样的：

前置（一次性）

  • 装微信开发者工具 nightly 版并已登录（扫码），「设置 → 安全设置 → 服务端口」开启。
  • 确认你的 AppID 有「小程序 AI 的开发模式」权限（没有的话 validate 会直接诊断出 appid_no_agent_permission 并停下）。
  • 在 app.json 顶层加 "lazyCodeLoading": "requiredComponents"（缺这个 generate 会按阻断规则停下让你补，不代补）。
  • Node ≥ 18.17（eval 工程需要）。

第 1 步 · 生成（在支持 Skills 的 coding agent 里）

使用 wxa-skills-generate 帮我把这个小程序的「商品检索 + 订单管理」做成小程序 AI 的 SKILL

它会走完 6 个阶段，产出完整的 skills/{skill-name}/ 并改好 app.json / project.config.json，然后主动交棒让你去校验。建议每次只生成一小块业务，验通了再扩。

第 2 步 · 校验

使用 wxa-skills-validate 校验 ./skills 目录

它跑静态校验 → 真机 execute → render → 按错误类型就地修复 → 全通过后写出 DELIVERY.md。三步也可单独跑（比如只想用 mock 数据看组件渲染效果）。

第 3 步 · 评测

cd wxa-skills-eval
pnpm install
node cli/index.js run -p /absolute/path/to/miniprogram --cases 5   # 默认开 Web UI 看实时进度

它会自动造用户任务、模拟多轮对话、打分归因，最后给一份 HTML 报告，告诉你这个 Skill 在「意图理解 / 轨迹 / 回复质量」上哪儿弱。

客观点评：它强在哪、又重在哪

亮点

  • 把「Skill 工程化」做到了少见的完整：从存量代码生成、到真机校验修复、到模拟用户评测，闭环齐全，几乎是「Skill 的 CI/CD」。
  • 不信模型、什么都验的工程基因，让产物可靠性远高于「写段 prompt 赌它能跑」。
  • 失败分类学（T1T9 / AD 类、白名单、阻断规则）信息密度极高，哪怕不做小程序，光读这几张表也能学到「约束该怎么写进结构」。

局限 / 门槛

  • 重：强依赖微信开发者工具、真机权限、AppID 资质，整套跑通的环境门槛不低，远不如「写个文件夹就是 Claude Skill」轻。
  • 窄：它是为「微信小程序 + 小程序 AI」这个特定宿主造的，规范里大量约束（JSAPI 白名单、组件尺寸、独立分包）是这个场景的产物，迁不到通用 Agent。
  • 黑盒依赖：能力边界完全由微信的白名单和「小程序 AI 开发模式」权限决定，开发者是在一个被圈定的沙箱里做 Skill，自由度和 Claude 那套开放体系没法比。

一句话：这是一份**「亿级消费场景下，Skill 该有多严谨」的范本**。它不优雅、不轻量，但它诚实地回答了一个 Claude Skill 可以回避、而微信不能的问题——当你的 Skill 要跑在所有人的手机里，你凭什么相信它真的能用？ 答案是：编译它、校验它、评测它。

拼进地图：四块拼图，一张「Skill 全景」

把这条和博客已拆的三条放一起，正好凑齐从「认知」到「落地」再到「工业级实现」的完整光谱：

在讲哪一层一句话
Aaron · 拉开差距的是 Skill认知 · 为什么别追模型，开始攒你的 Skill
Vibecode 成 Skill方法 · 怎么做把一个专家蒸馏成决策树写进 SKILL.md
老板 Skill · 人格蒸馏玩法 · 蒸馏谁把「一个人」封装成可加载的技能
本篇 · 微信官方工具链工业 · 凭什么信从源码生成、真机校验、模拟评测，把 Skill 做成流水线

串起来：Aaron 告诉你「该攒 Skill」，Vibecode 和人格蒸馏告诉你「怎么把经验 / 人蒸馏成 Skill」，而微信这套告诉你——当 Skill 要真刀真枪上生产，它得经得起编译、校验和评测。前三条是「写出来」，这一条是「靠得住」。一个能长期复利的 Skill，两头都得占。

Sources

  • GitHub 仓库：https://github.com/wechat-miniprogram/ai-mode-skills （腾讯官方，monorepo）
  • 三个 skill 版本：wxa-skills-generate 0.1.20 · wxa-skills-validate 0.1.18 · wxa-skills-eval 0.1.18（2026-06-17 抓取）
  • 关键来源文件：各 skill 的 SKILL.md、references/CODE_TEMPLATES.md / JSAPI_WHITELIST.md / VALIDATE_RULES.md、wxa-skills-eval/references/pipeline.md、仓库 README.md / CHANGELOG.md
  • 同主题对照（已拆）：Aaron · Skill 不是模型 · Vibecode 成 Skill · 老板 Skill 人格蒸馏
  • Skill 形态参考：Anthropic「Agent Skills」/ Claude Code 技能体系（SKILL.md + frontmatter + 脚本，渐进式加载）