wxa-create-mp-skill

在已有小程序项目中创建新的 AI Skill。

职责边界

• ✅ 理解用户需求，设计原子接口
• ✅ 产出 SKILL.md + mcp.json 设计文档
• ✅ 调用 wxa-skills-generate 生成完整代码
• ✅ 调用 wxa-skills-validate 校验、执行、渲染
• ✅ 修复校验问题直至全部通过
• ❌ 创建新小程序项目（交给 wxa-create-ai-miniprogram）
• ❌ 搜索安装社区 Skill（交给 wxa-find-skills）
• ❌ 修改小程序主包代码（如 app.js、页面文件）
• ❌ 上架 Skill 到应用市场
• 📦 交付：skills/{skill-name}/ 完整分包 + app.json 注册

术语约定

• 原子接口：对外暴露给小程序 AI 的可调用 API，约定路径 skills/{skill}/apis/{name}.js
• 原子组件：渲染原子接口返回数据的 UI 卡片，约定路径 skills/{skill}/components/{name}/
• SKILL.md：AI 路由元数据，描述业务的触发场景和使用顺序，≤ 16KB
• mcp.json：模型可调用能力声明，去除 outputSchema 后 ≤ 24000 字符
• Wecard 设计规范：原子组件的视觉基线标准，详见项目 SKILL-DEV-GUIDE.md 附录 A

参考资料索引

\x3Cgenerate-dir> 和 \x3Cvalidate-dir> 在 Step 3 中通过 npx mp-skills --help 获取。

硬性约束

A. 项目前置条件

B. 接口设计规范

C. 组件规范

• 遵守 WeCard 设计规范（详见 SKILL-DEV-GUIDE.md 附录 A）
• 组件路径格式：components/{name}/index（相对路径，不带分包前缀）
• 每个带 UI 的接口必须关联 _meta.ui.componentPath

D. 阻断规则（立即停止）

工作流

Step 1 — 需求理解与接口设计

与用户对话明确功能需求。接口划分遵循以下原则：

• 每个接口职责单一：searchItems、getDetail、placeOrder 各管各的
• 不要一个接口做太多事（避免 AI 选择困难）
• 不要拆太细（避免多次 API 调用）
• 建议 3-6 个原子接口

输出接口清单，用户确认后再进入下一步。

Step 2 — 产出设计文档

在 skills/\x3Cskill-name>/ 下创建：

SKILL.md（业务路由说明，≤ 16KB）：

• 能力域定位
• 触发场景（few-shot 用户原话）
• 不适用范围
• 使用顺序

mcp.json（模型可调用能力声明，去除 outputSchema ≤ 24000 字符）：

{
  "apis": [
    {
      "name": "searchItems",
      "description": "搜索商品列表。\
调用前置条件：...\
【严禁场景】...",
      "inputSchema": { "type": "object", "properties": {...}, "required": [...] },
      "_meta": { "ui": { "componentPath": "components/item-list-card/index" } }
    }
  ],
  "components": [
    { "path": "components/item-list-card/index", "relatedPage": "/pages/index/index" }
  ]
}

产出后让用户确认设计。确认前不得进入下一步。

Step 3 — 代码生成

先获取官方技能路径并记录到变量：

npx mp-skills --help

输出底部会显示：

工具型 Skill 路径（供 AI 模型引用）:
  wxa-skills-generate: /Users/xxx/.mp-skills/skills/wxa-skills-generate/SKILL.md
  wxa-skills-validate: /Users/xxx/.mp-skills/skills/wxa-skills-validate/SKILL.md

记录两个路径（去掉末尾的 /SKILL.md）：

• \x3Cgenerate-dir> = wxa-skills-generate 所在目录
• \x3Cvalidate-dir> = wxa-skills-validate 所在目录

然后读取 \x3Cgenerate-dir>/SKILL.md，按它的阶段式工作流执行代码生成。 按它的指引走即可，不需要在这里重复每一步。

注意：wxa-skills-generate 会自动处理 wx API 白名单检查、原子组件约束、分包配置。不要绕过这些约束。

Step 4 — 校验

使用 Step 3 中记录的 \x3Cvalidate-dir> 路径。

4.1 静态校验

node \x3Cvalidate-dir>/scripts/validate.mjs \x3Cproject-path>

通过条件：summary.errors === 0 且 summary.buildStatus === "pass"。

4.2 接口执行 + 组件渲染

静态校验通过后，对每个带 _meta.ui.componentPath 的接口：

# 执行原子接口
node \x3Cvalidate-dir>/scripts/execute.mjs \
  --project \x3Cproject-path> --name \x3Capi-name> --args '{}' \
  --output ./cli-agent-run/execute-result.\x3Cname>.json

# 渲染组件
node \x3Cvalidate-dir>/scripts/render.mjs \
  --project \x3Cproject-path> \
  --from-execute ./cli-agent-run/execute-result.\x3Cname>.json \
  --output ./cli-agent-run/render-result.\x3Cname>.json

Step 5 — 修复问题

如果有校验失败，按 wxa-skills-validate/SKILL.md 的修复流程处理：

修复后重跑校验，直到全部通过。

Step 6 — 收尾

确认 app.json 的 agent.skills[] 中已包含新 Skill。 提示用户运行 npx mp-skills setup 完成环境配置。