---
name: miniprogram-development
description: WeChat Mini Program development skill for building, debugging, previewing, testing, publishing, and optimizing mini program projects (小程序开发、调试、预览、发布). Covers project structure and config (`project.config.json`, `appid`, `miniprogramRoot`, `tabBar`, routing/navigation, icon assets), WeChat Developer Tools Nightly workflows (`wechatide` CLI, WeChat IDE Skills/MCP), `miniprogram-ci` preview/upload, console/network debugging, message push (消息推送) and customer-service auto-reply (客服消息), mini program SEO / search indexing (小程序搜索优化、页面收录、搜索推广、mpcrawler), and CloudBase integration (`wx.cloud`, 腾讯云开发, 云开发) when explicitly used. Use when users create, develop, modify, debug, preview, deploy, publish, or promote WeChat Mini Programs. NOT for Web frontend (use web-development), pure backend services (use cloudrun-development / cloud-functions), or UI-design-only tasks (use ui-design).
version: 2.34.6
alwaysApply: false
---

## 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`

**Post-deployment (optional, non-intrusive)**: after a mini program upload/publish is verified successful, you may offer **at most once** to generate anonymized shareables (visual card + paste-ready copy) — see `../cloudbase-platform/references/protocols/deployment-share.md` for trigger boundaries, required information, anonymization red lines, and deliverable formats. Never follow up if declined; never publish on the user's behalf.

## 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, 虚拟支付 (virtual payment, `wx.requestVirtualPayment`), or Integration Center generated payment functions -> `../cloudbase-wechat-integration/SKILL.md` (official docs: `https://docs.cloudbase.net/integration/wechat-pay-miniprogram.md`)
- UI generation -> `../ui-design/SKILL.md` first

### Do NOT use for

- Web auth flows or Web SDK-specific frontend implementation.
- WeChat Pay, 虚拟支付 / `wx.requestVirtualPayment`, 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](references/message-push-customer-service.md)).
- Assuming cloud-function return values auto-reply to customer-service chats (must use `cloud.openapi.customerServiceMessage.send`).
- Treating a grayed-out 云开发 button as a DevTools bug — trial/test accounts do not support CloudBase; confirm a registered mini program account first (see [CloudBase integration reference](references/cloudbase-integration.md), section 环境开通).
- 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](references/devtools-debug-preview.md) first
   - If choosing between WeChat IDE Skills and CloudBase MCP, read [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)
   - If the task involves CloudBase, `wx.cloud`, cloud functions, CloudBase database/storage, or CloudBase identity handling, read [CloudBase integration reference](references/cloudbase-integration.md)
   - If the task involves mini program SEO / WeChat search optimization / page indexing / search promotion (小程序搜索优化、页面收录、搜索推广、关键词排名), read [Mini Program SEO & WeChat Search Optimization](references/seo-search-optimization.md) 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](references/message-push-customer-service.md) 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](references/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`

```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](references/devtools-debug-preview.md) and [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)

## 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_query_msg_push` / `cloud_manage_msg_push` are not yet exposed (pending WeChat IDE CLI support).
- 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 **云开发控制台 → 云函数 → 日志**; the wxide CLI does not expose log query yet — do not teach low-level log CGI bypasses.
- Full reference: [Message Push & Customer Service Auto-Reply](references/message-push-customer-service.md)

## Minimal project skeleton

`app.js`

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

`pages/index/index.js`

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

`pages/index/index.wxml`

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

`pages/index/index.json`

```json
{
  "navigationBarTitleText": "Home"
}
```

`project.config.json`

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

## References

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