前言¶
用 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 版微信開發者工具 與
wechatideCLI 做打開工程、編譯、模擬器、控制台/網絡調試、預覽與上傳；若本機缺少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 | skills 目錄 |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或項目下 .agents/skills/ |
安裝後按各 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 原文）：
- 默認按通用微信小程序處理，不預設已接 CloudBase。
- 改代碼前檢查
project.config.json與頁面index.json等配置。 - 按場景閱讀 references：調試預覽、CloudBase 集成、SEO、消息推送等分文件展開。
- 預覽/上傳前完成 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。
