前言¶

用 AI 写微信小程序时，常见问题不是「能不能生成页面」，而是生成物是否贴合微信工程约束：目录是否在 project.config.json 里配置正确、appid 与预览上传流程是否对齐、tabBar 与路由是否可编译，以及项目若使用 CloudBase 时 wx.cloud 初始化与环境绑定是否一致。单靠通用前端提示词，Agent 容易把 Web 习惯带进小程序，或在未确认 CloudBase 的前提下套用云开发规则。

下面介绍 SkillHub 企业源上架的 微信小程序开发 Skill（坐标 @zcwl/miniprogram-development）。它面向 AI 编码场景，把小程序从构建、调试、预览、测试到发布的流程约定，以及 CloudBase 集成相关指引，整理成 Agent 可遵循的 SKILL 规则。

这是什么¶

一句话定位：面向 Agent 的微信小程序开发 Skill，覆盖构建、调试、预览、测试、发布等全流程约定；在明确使用 CloudBase / wx.cloud 时，再按云开发集成规则推进。

出品与分发：SkillHub 页面显示发布者为「智创未来」，分类为 dev-programming，来源标记为 enterprise；官方 Skill 入口为 https://api.skillhub.cn/tencent-adm/miniprogram-development，社区页为 https://www.skillhub.cn/skills/zcwl/miniprogram-development。当前上架版本为 v1.28.19，标签 requires_api_key=false，安装 Skill 本身不需要 API Key。

与 CloudBase 文档的关系：腾讯云开发 CloudBase 文档站「应用集成：微信小程序」页面对 miniprogram-development 这一 Skill 族有专门说明，涵盖 tabBar 配置、wx.cloud 集成、DevTools / wechatide 与 miniprogram-ci 等主题，并给出可复现的测试提示词。SkillHub 包与 CloudBase AI Toolkit 中的同名能力属于同一技术脉络；在 SkillHub 安装时使用坐标 @zcwl/miniprogram-development，在 CloudBase 生态中也可通过 npx skills 从官方仓库单独拉取同名 Skill（见下文安装节）。

核心功能¶

以下能力均可在 SkillHub 简介或 CloudBase 官方 Skill 说明中核对；写作时按「先通用小程序、再按需 CloudBase」组织。

工程结构与配置¶

• 页面与组件的创建、修改，以及项目目录组织。
• 检查 project.config.json（含 appid、miniprogramRoot 等）后再建议打开、预览或发布。
• 页面级 .json 配置齐全，本地资源路径与配置文件一致，避免编译失败。

tabBar、路由与资源¶

• 处理 tabBar、路由导航、图标资源与标签间距；未明确要求图标时，文档规则倾向 纯文字 custom tabBar（tabBar.custom = true，列表项保留 pagePath 与 text），减少图标占位与留白问题。
• 需要图标时再配置 iconPath / selectedIconPath，并确保资源已下载到项目内。

调试、预览与发布¶

• 覆盖构建、调试、预览、测试、发布（SkillHub 简介原文）。
• CloudBase 文档侧补充：默认推荐 Nightly 版微信开发者工具 与 wechatide CLI 做打开工程、编译、模拟器、控制台/网络调试、预览与上传；若本机缺少 wechatide，应说明这是环境缺口并询问是否安装 Nightly，用户拒绝或无法安装时，再退到 miniprogram-ci 预览/上传并结合 CloudBase MCP 等路径，并说明能力差异。
• Nightly 下载页：https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html。

CloudBase / wx.cloud 集成（按需）¶

• 仅在用户或代码库明确使用 CloudBase、wx.cloud、腾讯云开发或云开发时，才应用云开发约束（鉴权、数据库、存储、云函数等）；非 CloudBase 小程序不要强行套用。
• 涉及主体选择、测试号、云开发入口置灰、环境在 DevTools 中不可见等，需先读 CloudBase 集成 reference 中的账号与环境诊断，而非直接改代码。
• 支付、虚拟支付、公众号 OAuth 等场景文档要求转读 cloudbase-wechat-integration 等兄弟 Skill，本 Skill 不包办。

其他专题（CloudBase 规则原文中列出）¶

• 小程序 SEO / 微信搜索收录（mpcrawler 等），见 dedicated reference。
• 消息推送与客服自动回复（需 cloud.openapi.customerServiceMessage.send 等），见 dedicated reference。
• 变更安全协议（Change Safety Protocol）与发布门禁（Deployment Gate）在配套 cloudbase-platform 兄弟 Skill 中，改代码或上传发布前应遵循。

明确不适用于：纯 Web 前端（应使用 web-development）、纯后端服务（cloudrun-development / cloud-functions）、仅 UI 设计无小程序工程上下文（ui-design）。

安装与启用¶

方式一：通过 SkillHub 安装（推荐，对应当前坐标）¶

SkillHub 页面给出的 Agent 提示为：请 Agent 阅读安装说明并安装 @zcwl/miniprogram-development。

请根据 https://skillhub.cn/install/skillhub.md，安装 `@zcwl/miniprogram-development`。

若本机已有 skillhub CLI，安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别：

command -v skillhub && skillhub --version

skillhub install @zcwl/miniprogram-development --dir <你的 Agent skills 目录>

未安装 CLI 时，可按 SkillHub 安装文档执行（完整安装示例）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

常用 Agent 的 skills 路径（摘自 SkillHub 安装文档）：

安装后按各 Agent 要求重启或刷新，使 Skill 进入上下文。

方式二：从 CloudBase 官方仓库安装同名 Skill¶

若你已在 CloudBase AI Toolkit 生态内工作，文档提供 npx skills 安装方式（与 SkillHub 坐标不同，但 Skill 名均为 miniprogram-development）：

npx skills add tencentcloudbase/cloudbase-skills

仅安装当前 Skill：

npx skills add https://github.com/tencentcloudbase/skills --skill miniprogram-development

兄弟 CloudBase Skill（如 auth、文档型数据库、UI 等）需与 miniprogram-development 同目录并列安装；缺失时应提示用户安装完整 CloudBase 插件，而不是在对话中 HTTP 拉取远程 SKILL 正文凑数。

典型用法¶

启用 Skill 后，用自然语言描述小程序任务即可；CloudBase 文档页给出了可直接复制的测试提示词：

帮我创建一个微信小程序项目并集成 CloudBase

实现小程序与 CloudBase 的完整集成

我想把微信小程序 tabBar 调整为纯文字样式，怎么去掉图标占位并消除标签上方留白？

帮我做小程序 SEO：优化页面让微信搜索能收录（小程序搜索优化指南）

Agent 侧应遵循的规则摘要（来自 CloudBase 文档中的 Skill 原文）：

1. 默认按通用微信小程序处理，不预设已接 CloudBase。
2. 改代码前检查 project.config.json 与页面 index.json 等配置。
3. 按场景阅读 references：调试预览、CloudBase 集成、SEO、消息推送等分文件展开。
4. 预览/上传前完成 deployment-gate 等门禁检查（需已安装 cloudbase-platform 兄弟 Skill）。

文档还给出了最小工程骨架示例，便于 Agent 对齐文件布局。例如 project.config.json：

{
  "appid": "your-mini-program-appid",
  "projectname": "cloudbase-mini-program",
  "miniprogramRoot": "./",
  "compileType": "miniprogram"
}

纯文字 tabBar 的 app.json 片段：

{
  "tabBar": {
    "custom": true,
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/travel/travel", "text": "行程" },
      { "pagePath": "pages/my/my", "text": "我的" }
    ]
  }
}

适用场景与注意¶

适合谁

• 在微信小程序仓库里用 Cursor、Claude Code、Codex 等 Agent 做日常开发、联调与发布准备的团队或个人。
• 项目已用或计划用 CloudBase / wx.cloud，希望 Agent 不要生成 Web 式登录或错误的 SDK 假设。
• 需要 tabBar、DevTools Nightly、miniprogram-ci、搜索收录或消息推送等专题时，希望 Agent 按 reference 分文件查阅，而不是一次性幻觉出 CLI 参数。

限制与坑

• SkillHub 统计（截至资料抓取）：评分 100000，下载 16583；Skill 规则会随版本更新，SkillHub 当前为 v1.28.19，与 GitHub 上开源 SKILL 的版本号可能不一致，以你实际安装的包为准。
• requires_api_key=false 仅表示 Skill 安装层不要求 Key；真实预览、上传、CloudBase 资源操作仍依赖微信小程序 appid、开发者工具与云开发环境等账号侧配置。
• 稳定版微信开发者工具未必包含 Nightly 的 Skills / wechatide；缺少 CLI 时应沟通安装 Nightly，而不是静默降级为「手动导入」作为默认方案。
• 测试号不支持 CloudBase、主体类型影响支付与类目：文档强调先诊断账号与环境，再改工程。
• 完整 CloudBase 能力常依赖多个兄弟 Skill；只装 miniprogram-development 时，遇到 auth、支付、platform 协议等应引导补装，而非在单 Skill 内硬写。

结尾¶

微信小程序开发 Skill（@zcwl/miniprogram-development）把小程序工程结构、调试发布路径以及按需的 CloudBase 集成规则写进 Agent 工作流，适合在 AI 辅助编码时减少「能跑但不能编译/不能上传」的返工。官方 Skill 入口：https://api.skillhub.cn/tencent-adm/miniprogram-development；SkillHub 社区页：https://www.skillhub.cn/skills/zcwl/miniprogram-development。CloudBase 侧说明与规则镜像：https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/miniprogram-development。