前言¶

微信小程序上线后，常见问题往往不是「不会写页面」，而是审核被拒、广告占屏、本地数据莫名丢失，或在别人仓库里改了一处却牵出一串框架报错。通用开发 Skill 多讲脚手架与 API，对「第一天就该写进 app.json 的配置」和「在既有项目里只改指定功能」的纪律讲得少。下面介绍 SkillHub 上的 微信小程序避坑与协作指南（@user_6b038fe4/wechat-miniprogram-guardian），它把生产环境里的教训整理成可交给 Agent 执行的指南。

这是什么¶

微信小程序避坑与协作指南 是面向微信小程序生产项目的 Agent Skill，采用通用 SKILL.md 格式，由 SkillHub 用户 user_6b038fe4 发布。官方入口：

• 页面：https://skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian
• API 路径：https://api.skillhub.cn/user_6b038fe4/wechat-miniprogram-guardian

在 SkillHub 中分类为 dev-programming，公开数据为评分 99778、下载约 900 次（以平台展示为准）。

它解决两类问题：从零搭建时把审核、广告、存储等坑前置到地基；维护已上线小程序时按步骤处理审核整改、广告异常、数据丢失与框架报错，并在他人项目上遵守协作边界。

核心功能¶

资料与 Skill 简介一致，能力可概括为两条线。

线 A：从零搭建（第一天做对的地基）¶

1. app.json 防坑配置：把易导致审核或运行问题的全局配置提前写清，减少后期返工。
2. 本地优先存储模式：围绕数据持久化给出可落地的存储策略，降低「用户数据保存后丢失」类事故。
3. 双广告系统分搭：区分并拆分两套广告体系的接入方式，避免广告占屏、位异常等线上问题。
4. 审核合规内置：把提审常见合规要求纳入搭建流程，而不是提审前一晚临时补材料。

线 B：维护与修复已上线项目¶

1. 审核整改：按被拒原因组织修改与复提思路。
2. 广告位异常：排查与修复广告展示、配置类问题。
3. 数据保存丢失：针对存储与同步链路做定位与修复指引。
4. 框架报错甄别：区分业务代码与基础库/框架层问题，避免误改。
5. 他人项目改动纪律：在陌生仓库中控制改动范围，降低连带风险。

协作铁律（Skill 强调的三条）¶

• 先验证后动手：用日志、真机或最小复现确认现象，再改代码。
• 只改指定功能：不借机做大范围重构。
• 隔离演示：演示、调试与生产逻辑分开，避免污染线上行为。

安装与启用¶

SkillHub 的安装说明见 https://skillhub.cn/install/skillhub.md。先做 CLI 检查，再装到当前 Agent 的 skills 目录（装错目录会导致 Agent 读不到技能）。

1、检查或安装 SkillHub CLI¶

command -v skillhub && skillhub --version

未安装时可执行（完整安装含默认 Skill）：

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

仅 CLI：

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

2、安装本 Skill¶

CLI 解析到的包名为 @user_6b038fe4/wechat-miniprogram-guardian，内部 slug 为 wechat-miniprogram-guardian。安装时需用 --dir 指向当前环境的 skills 目录，例如 Cursor 常用：

skillhub install wechat-miniprogram-guardian --namespace user_6b038fe4 --dir ~/.cursor/skills/

Claude Code 可将 --dir 设为 ~/.claude/skills/；Codex 可为 ~/.codex/skills/ 或项目下的 .agents/skills/（以你当前客户端文档为准）。

3、用自然语言让 Agent 安装（可选）¶

与同站其他用户 Skill 的提示方式一致，可将下面话术发给支持 SkillHub 的 Agent：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_6b038fe4/wechat-miniprogram-guardian。

安装后按客户端要求刷新或重启，使 SKILL.md 被加载。若 skillhub install 下载失败，先到 SkillHub 页面确认技能是否仍上架，再重试或联系发布者。

典型用法¶

本 Skill 无单独脚本入口，用法是 在对话中描述场景，由 Agent 按 SKILL.md 中的检查清单与步骤推进。下列表述与 Skill 自述的触发条件一致，可直接复用。

新建小程序

我要从零做一个微信小程序，请按微信小程序避坑与协作指南：先帮我列 app.json 防坑项、本地优先存储和广告分搭方案，并带上审核合规检查点。

审核被拒

小程序提审被拒，驳回理由是 [粘贴微信后台原文]。请按避坑指南走审核整改，只改与驳回相关的内容，并说明需要我自测的项。

广告或数据问题

线上广告位异常 / 用户反馈数据保存后丢失。请先列验证步骤再改代码，按 Skill 区分是配置、存储还是框架问题。

在他人项目上改动

这是别人的小程序仓库，我只允许改 [具体功能]。请遵守先验证后动手、只改指定功能、隔离演示，改动前先说明影响范围。

经过上面的步骤，Agent 应优先引用 Skill 内的规范，而不是随意扩 scope。

适用场景与注意¶

适合谁

• 准备上线或已上线、需要 生产级 纪律的微信小程序开发者。
• 用 Cursor、Claude Code、Codex 等带 Skills 的 Agent 写小程序、排线上问题时，希望有一套固定的避坑与协作话术。

建议在以下情况启用

• 新建小程序、审核被拒、广告位异常、数据保存丢失、莫名框架报错、在他人项目上做功能修改。

注意

• 本文功能描述来自 SkillHub 公开简介与安装 CLI 解析结果；具体配置字段、代码片段以安装后的 SKILL.md 为准，本文不替代官方技能正文。
• 微信小程序平台规则与基础库会更新，涉及提审、隐私、广告政策时仍需对照 微信开放文档 最新说明。
• 官方 API 页面若返回 405 或安装下载 404，以 SkillHub 网页 skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian 的状态为准。

结尾¶

微信小程序避坑与协作指南 把「审核、广告、存储、协作边界」从零散经验收成一条 Agent 可执行的线：新建时打地基，维护时少误伤。若你正在做生产向的小程序，可在 SkillHub 打开官方页查看详情并安装：https://skillhub.cn/skills/user_6b038fe4/wechat-miniprogram-guardian。