Agent Skills: WeChat Mini Program Development Rules

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Cross-cutting protocols (required before code changes or deployments):

• Change Safety Protocol: ../cloudbase-platform/references/protocols/change-safety-protocol.md
• Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

Activation Contract

Use this first when

• The request is about WeChat Mini Program structure, pages, preview, publishing, or CloudBase mini program integration.

Read before writing code if

• The user mentions wx.cloud, CloudBase mini programs, OPENID, mini program deployment/debug workflows, Nightly DevTools, wechatide, or WeChat IDE Skills.
• The user mentions message push (消息推送), customer-service auto-reply (客服消息/自动回复), or binding MsgType/Event callbacks to cloud functions.

Then also read

• CloudBase auth -> ../auth-wechat-miniprogram/SKILL.md
• CloudBase document DB -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
• Mini Program WeChat Pay or Integration Center generated payment functions -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md)
• UI generation -> ../ui-design/SKILL.md first

Do NOT use for

• Web auth flows or Web SDK-specific frontend implementation.
• WeChat Pay, payment callbacks, refunds, or Official Account OAuth details; use cloudbase-wechat-integration for those scenarios.

Common mistakes / gotchas

• Generating a Web-style login flow for mini programs.
• Mixing Web SDK assumptions into wx.cloud projects.
• Applying CloudBase constraints before confirming the project actually uses CloudBase.
• Assuming Stable WeChat Developer Tools includes Nightly Skills/wechatide (it may not).
• Forcing CloudBase MCP Tencent Cloud login for daily mini program cloud ops when Nightly wechatide already works.
• Inventing wechatide tool names or flags instead of using --help / Nightly tools.yaml.
• Bypassing wxide CLI / IDE for message-push ops with low-level transport before cloud_msg_push_* is exposed (see message-push-customer-service.md).
• Assuming cloud-function return values auto-reply to customer-service chats (must use cloud.openapi.customerServiceMessage.send).
• Making code or configuration changes without first following the Change Safety Protocol (cloudbase-platform/references/protocols/change-safety-protocol.md).
• Performing mini program upload/publish without first completing the checks in cloudbase-platform/references/protocols/deployment-gate.md.

When to use this skill

Use this skill for WeChat Mini Program development when you need to:

• Build or modify mini program pages and components
• Organize mini program project structure and configuration
• Debug, preview, or publish mini program projects
• Work with WeChat Developer Tools workflows
• Handle mini program runtime behavior, assets, or page config files
• Integrate CloudBase in a mini program project when explicitly needed

Do NOT use for:

• Web frontend development (use web-development)
• Pure backend service development (use cloudrun-development or cloud-functions as appropriate)
• UI design-only tasks without mini program development context (use ui-design)

How to use this skill (for a coding agent)

1. Start with the general mini program workflow

   • Treat WeChat Mini Program development as the default scope
   • Do not assume the project uses CloudBase unless the user or codebase indicates it

2. Follow mini program project conventions

   • Keep mini program source under the configured mini program root
   • Ensure page files include the required configuration file such as index.json
   • Check project.config.json before suggesting preview or IDE workflows

3. Route by scenario

   • If the task involves debugging, previewing, publishing, opening DevTools, console/network, or wechatide, read debug and preview reference first
   • If choosing between WeChat IDE Skills and CloudBase MCP, read WeChat IDE Skills vs CloudBase MCP
   • If the task involves CloudBase, wx.cloud, cloud functions, CloudBase database/storage, or CloudBase identity handling, read CloudBase integration reference
   • If the task involves mini program SEO / WeChat search optimization / page indexing / search promotion (小程序搜索优化、页面收录、搜索推广、关键词排名), read Mini Program SEO & WeChat Search Optimization first
   • If the task involves message push (消息推送), customer-service auto-reply (客服消息自动回复), MsgType/Event → cloud function binding, or push-related function logs, read Message Push & Customer Service Auto-Reply first
   • If the task involves tabBar, icon assets, or label spacing, prefer the text-only custom tabBar default below unless the user explicitly requires icons

4. Use CloudBase rules only when applicable

   • CloudBase / 微信云开发 is an important mini program integration path, but not a universal requirement
   • Only apply CloudBase-specific auth, database, storage, or cloud function constraints when the project is using CloudBase

5. Recommend the right preview/debug/cloud-ops path

   • Prefer Nightly WeChat Developer Tools (built-in Skills/MCP) and execute via wechatide when available — see devtools-debug-preview.md
   • Nightly download: https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html
   • If Nightly / wechatide is unavailable, fall back to miniprogram-ci for preview/upload and CloudBase MCP for cloud resources

WeChat Mini Program Development Rules

General Project Rules

1. Project Structure

   • Mini program code should follow the project root configured in project.config.json
   • Keep page-level files complete, including .json configuration files
   • Ensure referenced local assets actually exist to avoid compile failures

2. Configuration Checks

   • Check project.config.json before opening, previewing, or publishing a project
   • Confirm appid is available when a real preview, upload, or WeChat Developer Tools workflow is required
   • Confirm miniprogramRoot and related path settings are correct

3. Resource Handling

   • For tabBar, prefer a text-only custom tabBar by default when the user does not explicitly need icons. This avoids icon asset handling, removes reserved icon space, and makes the label area easier to align.
   • Only generate local icon assets and configure iconPath / selectedIconPath when the user explicitly asks for tab icons or the design requires them.
   • When generating local asset references such as icons, ensure the files are downloaded into the project.
   • Keep file paths stable and consistent with mini program config files.

Recommended default for simple tabBar

Use tabBar.custom = true, keep only pagePath and text in app.json, and render text-only items in the custom component so there is no icon slot and no extra blank area above the label.

app.json

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

Keep the custom tabBar layout text-only, and use flex centering or matching height and line-height to remove the blank area above the label. Switch to downloaded local icons only when the user explicitly wants icon-based tabs.

CloudBase as a Mini Program Sub-Scenario

• If the user explicitly uses CloudBase, wx.cloud, Tencent CloudBase, 腾讯云开发, or 云开发, follow the CloudBase integration reference
• In CloudBase mini program projects, use wx.cloud APIs and CloudBase environment configuration appropriately
• Do not apply CloudBase-specific rules to non-CloudBase mini program projects

Debugging, Preview, and Publishing

• Prefer Nightly DevTools + wechatide for open project, compile, simulator, console/network debug, preview, upload, and daily cloud ops (WeChat login — no separate Tencent Cloud login)
• Always pass required context: -c <clientName>, absolute --project, valid appid, and cloud env when needed
• If Nightly / wechatide is not available, use miniprogram-ci as the fallback for preview/upload/npm, and CloudBase MCP for cloud resources; tell the user to install Nightly for full Skills/MCP
• For detailed workflows, read debug and preview reference and WeChat IDE Skills vs CloudBase MCP

Message Push & Customer Service Auto-Reply

微信生态专章：消息推送 / 客服自动回复细节以中文 reference 为准（术语保留英文 API 名）。

• Current only ops path: WeChat Developer Tools IDE + wxide CLI. Do not teach low-level bypasses while cloud_msg_push_query / cloud_msg_push_manage are not yet exposed (track 9109db6b).
• Deploy receiver functions with cloud_fn_deploy and --remote-npm-install; bind (MsgType, Event) → one cloud function in the IDE message-push panel until CLI tools land.
• Customer-service auto-reply requires cloud.openapi.customerServiceMessage.send plus config.json openapi permissions — function return values alone do not reply.
• Function logs: IDE 云开发控制台 → 云函数 → 日志; CLI log query is pending (9109db6b / d5735473).
• Full reference: Message Push & Customer Service Auto-Reply

Minimal project skeleton

app.js

App({
  onLaunch() {
    console.log("Mini Program launched");
  },
});

pages/index/index.js

Page({
  data: {
    message: "Hello CloudBase Mini Program",
  },
});

pages/index/index.wxml

<view class="page">
  <text>{{message}}</text>
</view>

pages/index/index.json

{
  "navigationBarTitleText": "Home"
}

project.config.json

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

References

• CloudBase Mini Program Integration — use this when the mini program project explicitly integrates CloudBase
• WeChat DevTools Debug and Preview — Nightly / wechatide paths, required context, and no-Nightly fallbacks
• WeChat IDE Skills vs CloudBase MCP — layering and when to use which execution surface
• Message Push & Customer Service Auto-Reply — 消息推送 / 客服自动回复 via wxide CLI + IDE (no low-level bypass; pending cloud_msg_push_*)
• Mini Program SEO & WeChat Search Optimization — 小程序搜索优化 / page indexing / search promotion (mpcrawler, URL reachability, navigator jumps, titles & thumbnails)
• Common Pitfalls — read before generating code for optional chaining, TDesign styling, Canvas + storage, and environment issues