做微信小程序开发的人大概率经历过这种场景需求文档写了满满两三页真正落地时却发现光是让一个项目在微信开发者工具里跑起来就要处理 AppID、app.json 页面注册、rpx 布局、开发者工具导入方式、域名校验等一串约束。任何一个环节卡住首屏都出不来。最近我在 AI 编程工具里做了一个专门服务微信小程序开发的 Skill把“从需求到首次运行”的流程拆成可执行步骤让 AI 不再是泛泛地补代码而是像有项目经验的人一样先出页面清单再生成工程骨架再自动做运行前自检。这篇文章不是教你背 API而是想讲清楚三件事第一Skill 到底是什么它和普通 Prompt 之间隔着什么样的设计思维第二一份面向微信小程序场景的 Skill 应该包含哪些内容为什么这些内容能显著降低首跑失败率第三用一个“会议预约小程序”的真实示例完整跑通从需求描述到微信开发者工具里看到首页的流程。文章偏实操但会把容易踩坑的地方讲透建议收藏备用。先给一个明确判断Skill 的真正价值不在于让 AI 多写几行代码而在于让 AI 在特定场景下按正确的顺序做事、检查正确的约束。微信小程序这种“文件多、配置多、验证链路长”的项目恰好是 Skill 收益最明显的场景。1. 为什么要给 AI 加一个“微信小程序 Skill”1.1 通用 AI 编程助手在小程序场景下差在哪通用 AI 编程助手写单页代码确实很强但把它丢进微信小程序项目你会很快发现三个问题。第一微信小程序不是一个“HTML 文件”而是一个复合工程。一个页面至少要包含.js、.wxml、.wxss、.json四个文件还要在app.json的pages数组里注册路径。AI 如果只是按“我要一个列表页”来理解很容易漏掉注册这一步结果代码看着没问题一编译就报“页面路径未注册”或者干脆白屏。第二微信小程序有大量工程级约束是通用模型不会主动考虑的。比如rpx自适应单位、navigationBarTitleText的页面标题配置、wx.request的域名校验、TabBar 图标路径必须真实存在、sitemap.json的索引配置。这些约束分散在多个文件里靠一段临时 Prompt 很难让 AI 全部遵守。第三运行验证有壁垒。小程序不能直接在浏览器里跑通必须借助微信开发者工具。AI 生成的代码如果没有project.config.json、没有 AppID 说明用户拿到项目后连“如何让这个项目跑起来”都得自己摸索。很多 AI 生成的小程序项目就是这样死在“最后一步”。1.2 Skill 解决的是“上下文 流程”问题Skill 的本质是把一组领域知识、工作流脚本和使用边界打包成可复用模块。在支持 Skill/Agent 机制的编程工具中例如 Claude Code、Codex、Cursor 等一个 Skill 通常包含一个描述文件常见命名为SKILL.md里面写清楚这个技能处理什么问题、触发条件是什么、实施步骤是什么、输出规范是什么必要时还可以带上模板资源和辅助脚本。对比一下更有感觉。用普通 Prompt 时你每次都要给 AI 重新描述一遍背景AI 只能靠当前对话上下文猜用 Skill 时AI 识别需求属于“微信小程序项目生成”后会自动加载一套既定工作流先解析需求为页面清单再生成工程骨架然后补页面代码最后做运行前自检。相当于把“团队里最熟悉小程序工程的同事”的经验沉淀成了可复用的文件。这也解释了为什么会有一批人专门在做 Skill、分享 Skill。Skill 表面上是给 AI 写说明书本质上是在做“工程经验的结构化”。对微信小程序这种约束密集的场景这种结构化的收益非常直接。2. 微信小程序从需求到首次运行要闯几道关2.1 需求层一句话需求不等于页面清单“我要个会议室预约小程序”这句话距离可开发的项目还差很远。需求层要做的是拆解小程序是工具类、展示类还是表单类首页展示什么是否需要详情页是否需要提交表单是否涉及登录是否需要真实后端在这个阶段AI 最常犯的错误是“过度设计”和“缺页”。过度设计是指把用户一句话需求扩展出一堆不存在的功能缺页则是漏掉最核心的页面。Skill 里应该明确要求先输出页面清单和字段说明和用户确认后再动手生成代码。这一步看起来慢实际能省掉大量返工。2.2 工程层文件与配置必须成对出现小程序工程的一个核心规则是“注册即生效未注册即报错”。app.json里的pages数组是项目的地图这里声明了哪些页面存在window配置全局窗口样式tabBar配置底部导航。每个页面则要对应四个文件page.js、page.wxml、page.wxss、page.json。任何一个文件缺失或者路径写错编译阶段就会失败。这个环节是 AI 代码最容易出问题的地方也是 Skill 最应该发力做自检的地方。与其让用户去开发者工具里看报错不如在生成阶段就完成“文件存在性检查”和“路径一致性检查”。2.3 运行层小程序必须有开发者工具介入小程序不像网页项目npm run dev之后浏览器就能看效果。它需要微信开发者工具导入项目目录、指定 AppID、点击编译。首次运行能否顺利很大程度取决于project.config.json是否完整以及appid是占位符还是真实测试号。Skill 的输出里必须把“如何导入”和“如何替换 AppID”写成明确的指引否则项目再规范用户也进不了下一步。3. Skill 的目录结构与 SKILL.md 设计3.1 推荐的 Skill 目录结构我做的这个 Skill 按“描述 模板 脚本 清单”四部分组织目录结构如下weapp-builder/ ├── SKILL.md ├── resources/ │ ├── templates/ │ │ ├── page.js.hbs │ │ ├── page.wxml.hbs │ │ ├── page.wxss.hbs │ │ └── page.json.hbs │ └── checklists/ │ └── pre-run-check.md └── scripts/ ├── generate-project.js └── verify-project.jsSKILL.md是入口负责告诉 AI 在什么情况下使用这个技能、按什么步骤执行resources/templates放页面模板resources/checklists放运行前自检清单scripts放真正可执行的校验脚本。这样 AI 既能看到“方法论”也能直接调用“工具”两件事各司其职。3.2 SKILL.md 里到底写了什么SKILL.md的核心不是长篇大论教 AI 什么是小程序而是给出一套可执行的作业流程。我的经验是一份有效的小程序构建 Skill 必须包含六个部分触发条件明确什么输入会触发这个 Skill例如“用户要求生成小程序项目”“用户描述了一个小程序需求”。输入处理把用户需求拆成页面清单并列出每个页面的功能点、字段、跳转关系。工程规范写入必须遵守的约束例如使用rpx作为尺寸单位、页面需在app.json注册、跳转路径必须与页面路径一致。实施步骤定义从骨架到页面再到自检的执行顺序禁止跳步。输出规范规定最终交付物的清单包括工程目录、AppID 说明、运行指引。自检清单在交付前由 AI 或脚本完成的关键检查项。3.3 一份可参考的 SKILL.md 片段下面是我在 Skill 中使用的一段SKILL.md核心内容可以直接作为参考--- name: weapp-builder description: 根据需求生成可运行的微信小程序项目骨架与页面代码 --- # 微信小程序构建技能 ## 触发条件 - 用户要求生成微信小程序项目或描述了一个需要做小程序的业务需求。 - 当前工作区没有微信小程序工程结构或用户明确要求重新生成。 ## 输入处理 1. 将需求拆解为页面清单输出表格包含页面路径、页面功能、主要交互。 2. 与用户确认页面清单确认后再生成代码不要跳步。 ## 工程规范 - 所有尺寸单位使用 rpx容器布局优先使用 flex。 - 页面必须包含 js / wxml / wxss / json 四个文件。 - app.json 的 pages 数组必须包含所有页面页面路径以 pages/ 开头。 - 暂未接后端时页面内使用本地 mock 数据禁止直接 wx.request 到未配置域名。 - 使用 project.config.json 描述项目配置appid 使用占位符 __APPID__。 ## 实施步骤 1. 生成 app.json / app.js / app.wxss / project.config.json / sitemap.json。 2. 按页面清单逐个生成页面四个文件。 3. 运行 node scripts/verify-project.js 检查工程一致性。 4. 输出运行指引如何用微信开发者工具导入项目如何替换 AppID。 ## 自检清单 - [ ] app.json 中 pages 数组与 pages 目录文件一一对应。 - [ ] project.config.json 中 appid 不为空允许占位符。 - [ ] 所有页面 json 文件均为合法 JSON。 - [ ] 页面跳转路径与实际页面路径一致。这里的关键不是让 AI “尽量遵守”而是让它在执行时把这些规则当成硬性任务。用清单而不是散文描述规则AI 的执行稳定性会高很多。4. 环境准备与前置条件4.1 工具链清单要在本地完整跑通这个小程序生成流程你需要准备以下工具工具用途说明Node.js运行生成和校验脚本建议使用 LTS 版本具体版本以项目实际为准微信开发者工具导入并编译小程序从微信官方渠道下载稳定版即可AI 编程工具加载 Skill、执行生成流程支持 Skill/Agent 机制的工具均可Git管理项目版本便于回滚和记录 Skill 的迭代这些工具里微信开发者工具是刚需。没有它小程序项目无法完成“首次运行”的验证。Node.js 则用于运行verify-project.js这类辅助脚本版本不需要太新能运行常见脚本即可。4.2 AppID 的两种选择小程序项目必须绑定一个 AppID但很多新手就是在这里卡住的。实际上 AppID 有两种选择第一种是正式 AppID需要在小程序公众平台注册账号后获取。个人开发者可以注册个人主体的小程序适合个人项目和功能演示企业主体的小程序则能使用更多能力。第二种是测试号微信开发者工具在新建项目时可以直接选择“测试号”不需要注册就能编译和预览。测试号适合先跑通页面逻辑但真机预览、云开发、部分开放接口会受限。从“需求到首次运行”的目标看我的建议是先使用测试号或占位符把项目跑起来确认页面和交互没问题再替换为正式 AppID。不要在第一轮验证时就卡在注册流程上。project.config.json中的appid字段是 AppID 的落点生成项目时可以先写占位符__APPID__在导入工具时手动替换。4.3 最小可跑的验证环境所谓“最小可跑”是指不需要后端、不需要数据库、不需要域名就能在开发者工具里看到的项目状态。达到这个状态你只需要一个完整的工程骨架和本地 mock 数据。这也是这个 Skill 强制“首跑阶段不引入网络请求”的原因。等到小程序在模拟器里跑通了再逐步接入真实的wx.request、云开发或后端服务。5. 完整示例从需求到首跑的“会议预约”小程序5.1 需求输入与 Skill 处理结果下面用一个真实场景演示整个流程。你给 AI 的原始输入是做一个公司内部会议预约小程序能看到会议室列表和空闲状态可以点进去填写预约人、时间和用途提交后提示成功。样式干净即可。Skill 解析后输出页面清单如下页面路径功能主要交互pages/rooms/rooms会议室列表展示名称、位置、容量、空闲状态点击会议室进入预约页pages/book/book预约表单填写预约人、日期时间、用途提交表单校验后提示成功pages/rooms/rooms是首页通过app.json的pages数组第一项指定。pages/book/book通过wx.navigateTo跳转进入。5.2 工程骨架生成Skill 生成工程骨架时核心是以下几个文件。app.json是整个项目的地图所有页面必须先在这里注册{ pages: [ pages/rooms/rooms, pages/book/book ], window: { navigationBarTitleText: 会议室预约, navigationBarBackgroundColor: #4A90D9, navigationBarTextStyle: white, backgroundColor: #F5F6FA }, style: v2, sitemapLocation: sitemap.json }project.config.json负责告诉微信开发者工具“这是一个可导入的小程序项目”{ compileType: miniprogram, appid: __APPID__, projectname: meeting-room-booking, miniprogramRoot: ./, setting: { es6: true, postcss: true, minified: true, urlCheck: false } }app.js是最小入口这个阶段不需要复杂逻辑// 文件路径app.js App({ onLaunch() { console.log(小程序启动); } });这个阶段有一个容易犯的错误忘记sitemap.json。微信开发者工具编译时会对sitemapLocation做检查缺少文件会报警告。所以 Skill 也会顺带生成一个最小配置{ rules: [ { action: allow, page: * } ] }5.3 首页列表实现本地数据先行首页是会议室列表。这里有一个非常重要的设计决策首跑阶段不要用wx.request直接使用本地 mock 数据数组。原因是wx.request会触发合法域名校验开发者工具即使勾选了“不校验合法域名”也会给新手带来额外的中断感。先用本地数据把页面渲染出来后面再替换成接口是成本最低的路径。pages/rooms/rooms.js// 文件路径pages/rooms/rooms.js const rooms [ { id: 1, name: A101 小会议室, location: 1 层东侧, capacity: 6, status: 空闲 }, { id: 2, name: B203 中会议室, location: 2 层西侧, capacity: 12, status: 使用中 }, { id: 3, name: C305 大会议室, location: 3 层中部, capacity: 30, status: 空闲 } ]; Page({ data: { rooms: [] }, onLoad() { this.setData({ rooms }); }, goBook(e) { const id e.currentTarget.dataset.id; wx.navigateTo({ url: /pages/book/book?id${id} }); } });pages/rooms/rooms.wxmlview classcontainer view classroom-card wx:for{{rooms}} wx:keyid>.container { padding: 24rpx; } .room-card { background: #fff; border-radius: 16rpx; padding: 32rpx; margin-bottom: 24rpx; box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.05); } .room-name { font-size: 32rpx; font-weight: 600; color: #333; } .room-meta { font-size: 24rpx; color: #888; margin-top: 12rpx; } .room-status { display: inline-block; margin-top: 16rpx; padding: 6rpx 20rpx; border-radius: 20rpx; font-size: 24rpx; } .room-status.free { background: #E8F7EE; color: #2BA245; } .room-status.busy { background: #FDECEC; color: #D9534F; }pages/rooms/rooms.json{ navigationBarTitleText: 会议室列表 }这里的布局刻意用了rpx和flex这也是 Skill 工程规范的一部分。小程序里750rpx等于屏幕宽度按这个基准做自适应比用px稳定得多。5.4 预约表单与提交反馈点击会议室卡片后通过wx.navigateTo进入预约页。预约页需要接收上一个页面传递的id在onLoad的options参数里读取。pages/book/book.js// 文件路径pages/book/book.js Page({ data: { roomId: , name: , date: , purpose: }, onLoad(options) { this.setData({ roomId: options.id || }); }, onInput(e) { const field e.currentTarget.dataset.field; this.setData({ [field]: e.detail.value }); }, submitBooking() { const { name, date, purpose } this.data; if (!name || !date || !purpose) { wx.showToast({ title: 请填写完整信息, icon: none }); return; } wx.showToast({ title: 预约成功, icon: success }); setTimeout(() wx.navigateBack(), 1500); } });pages/book/book.wxmlview classcontainer view classform-item text classlabel预约人/text input classinput placeholder请输入姓名>// 文件路径scripts/verify-project.js const fs require(fs); const path require(path); const root process.argv[2] || .; const appJsonPath path.join(root, app.json); if (!fs.existsSync(appJsonPath)) { console.error([FAIL] app.json 不存在); process.exit(1); } const appJson JSON.parse(fs.readFileSync(appJsonPath, utf8)); const pages appJson.pages || []; let hasError false; pages.forEach((page) { const basePath path.join(root, page); [.js, .wxml, .wxss, .json].forEach((ext) { const file basePath ext; if (!fs.existsSync(file)) { console.error([FAIL] 缺少文件: ${page}${ext}); hasError true; } }); }); const projectConfigPath path.join(root, project.config.json); if (!fs.existsSync(projectConfigPath)) { console.error([FAIL] project.config.json 不存在); hasError true; } else { const projectConfig JSON.parse(fs.readFileSync(projectConfigPath, utf8)); if (!projectConfig.appid || projectConfig.appid __APPID__) { console.warn([WARN] appid 仍是占位符导入开发者工具前需替换); } } if (hasError) { console.error([FAIL] 工程结构检查未通过); process.exit(1); } else { console.log([PASS] 工程结构检查通过可以尝试导入微信开发者工具); }运行方式是node scripts/verify-project.js ./meeting-room-booking这个脚本把“能不能跑”的一部分判断从人肉变成自动化也正好体现了 Skill 里“脚本 清单”的组合价值清单是做规则约束脚本是提供可验证的客观结果。6. 在微信开发者工具中运行与验证6.1 导入项目的正确姿势生成的项目目录包含project.config.json微信开发者工具会把它识别为小程序项目。导入步骤如下打开微信开发者工具选择“导入项目”。项目目录选择包含project.config.json的根目录也就是整个meeting-room-booking文件夹。AppID 选择“测试号”或手动填入你的正式 AppID。点击“确定”等待工具加载并在模拟器中编译。如果工具提示“不是小程序项目目录”优先检查project.config.json是否存在、compileType是否为miniprogram、miniprogramRoot是否指向正确目录。6.2 预期效果与判断标准编译成功后模拟器里应显示首页列表展示三个会议室卡片其中“A101”和“C305”状态为“空闲”“B203”状态为“使用中”。点击“A101 小会议室”会跳转到预约页填写完整信息后点击“提交预约”页面弹出“预约成功”提示并在 1.5 秒后返回列表页。判断是否成功的标准有三个编译无红色报错、模拟器出现预期页面、交互链路完整。只要这三条满足这个由 AI 生成的微信小程序就完成了“从需求到首次运行的完整流程”。6.3 首跑失败的通用排查顺序如果首次编译没有出现预期效果按下面的顺序排查效率最高先看微信开发者工具“调试器”的 Console 面板红色报错是首选线索然后确认app.json中页面路径与实际目录是否一致再看project.config.json的appid是否已被替换最后检查每个页面的.json文件是否是合法 JSON一个多余逗号都会导致编译失败。这套排查顺序也应该被写进 Skill 的自检清单里因为它是 AI 下次生成时最容易出错的位置。7. 常见问题与排查方法以下是 AI 生成微信小程序项目时最常见的问题也基本覆盖了大多数首跑失败场景问题现象可能原因排查方式解决方案页面白屏或报“页面路径未注册”app.json的pages数组漏配或路径与文件目录不一致检查app.json对比pages目录结构在pages数组补充页面路径路径必须以pages/开头点击卡片跳转无反应wx.navigateTo的url路径错误或目标页面未注册查看 Console 报错检查跳转路径修正url并在app.json中注册目标页面样式错位、尺寸混乱混用rpx和px或容器没有用flex布局查看页面的wxss文件统一使用rpx列表容器改为flex布局请求报错或数据加载失败请求域名未配置或开发者工具未关闭域名校验查看 Console 中的请求报错信息开发阶段勾选“不校验合法域名”上线前配置 HTTPS 合法域名导入工具时提示 appid 无效project.config.json中appid是占位符或已过期打开project.config.json查看appid字段替换为测试号或正式 AppID编译失败、提示文件不存在页面四个文件不完整或 JSON 语法错误查看编译日志定位具体文件补齐缺失文件修正 JSON 格式TabBar 图标不显示或编译报错tabBar.list中的iconPath指向不存在的图片检查图标文件是否存在替换为真实图标路径或去掉tabBar配置修改代码后页面不刷新开发者工具未触发重新编译点击工具栏“编译”按钮手动重新编译或在编辑器中开启自动编译这些问题是 Skill 设计和迭代时最好的素材。每遇到一个新问题都可以把它整理成一条规则加进SKILL.md的自检清单让 Skill 越用越“懂行”。8. 最佳实践从“能跑”到“能上线”8.1 首跑阶段不要碰网络请求AI 生成的小程序项目默认应该优先保证“本地可跑”。任何wx.request、云函数调用都应该在页面跑通之后再接入。这既是为了减少域名校验带来的干扰也是为了把“页面逻辑问题”和“网络问题”分开排查。首跑阶段用本地 mock 数据等页面稳定后再替换为接口返回会顺畅很多。8.2 管理好 AppID 与 project.config.jsonproject.config.json里包含appid和projectname这类文件如果提交到公开仓库建议把appid写成占位符__APPID__通过README说明如何替换。真实appid属于账号敏感信息不应该出现在公开代码中。团队协作时也可以约定每个人使用自己的测试号避免互相覆盖开发者工具中的登录态。8.3 让 Skill 持续“长记性”Skill 不是一次写完就固定的。每当你发现 AI 在某个环节反复出错正确的做法是把这个问题沉淀成SKILL.md里的规则。比如发现 AI 经常忘记生成sitemap.json就在“自检清单”中加一项发现 AI 生成的wx.navigateTo路径经常多一个或少一个前缀就在“工程规范”中明确写法。Skill 本质上是一个可以持续迭代的经验库迭代速度越快AI 的表现越稳定。8.4 安全与合规边界使用 AI 生成业务代码时要特别注意数据安全和权限边界。生成的项目如果涉及用户数据应遵循最小权限原则只申请必要的接口权限不采集与业务无关的敏感信息。生产环境的接口调用必须经过合法授权不能在客户端保存密钥。涉及数据库或服务端变更时也要先在测试环境验证并做好备份和回滚方案。这些约束同样建议写进 Skill 的说明中让 AI 在生成代码时主动规避高风险设计。9. 总结与后续学习方向这个 Skill 的核心思路可以概括为把微信小程序从需求到首跑的流程从“靠经验、靠运气”变成“靠流程、靠清单”。它做的不是魔法而是把一个小程序工程师应该检查的事项结构化地交给 AI 去执行。从实践效果看这类 Skill 对两类人最有价值一类是被工程配置反复折磨的新手一类是想把重复性脚手架工作交给 AI 的进阶开发者。项目跑通之后可以继续往三个方向深入。第一是接入真实后端把本地 mock 数据替换为wx.request调用注意配置合法域名和错误处理第二是接入微信云开发用云函数和数据库让小程序具备完整的后台能力省去自己搭建服务器的成本第三是研究订阅消息推送这是小程序触达用户的重要方式也是很多线上项目的刚需。如果你正在做自己的 Skill我的建议是不要一开始就追求大而全先从一个你真正疲劳的场景切入把一次成功的流程固定下来再逐步迭代。小程序生成本身就是一个很好的起点因为它约束明确、验证链路清晰、失败反馈直接——你很快就能感受到Skill 到底把哪些体力活真正省掉了。
基于AI Skill的微信小程序开发：从需求到首次运行全流程指南
做微信小程序开发的人大概率经历过这种场景需求文档写了满满两三页真正落地时却发现光是让一个项目在微信开发者工具里跑起来就要处理 AppID、app.json 页面注册、rpx 布局、开发者工具导入方式、域名校验等一串约束。任何一个环节卡住首屏都出不来。最近我在 AI 编程工具里做了一个专门服务微信小程序开发的 Skill把“从需求到首次运行”的流程拆成可执行步骤让 AI 不再是泛泛地补代码而是像有项目经验的人一样先出页面清单再生成工程骨架再自动做运行前自检。这篇文章不是教你背 API而是想讲清楚三件事第一Skill 到底是什么它和普通 Prompt 之间隔着什么样的设计思维第二一份面向微信小程序场景的 Skill 应该包含哪些内容为什么这些内容能显著降低首跑失败率第三用一个“会议预约小程序”的真实示例完整跑通从需求描述到微信开发者工具里看到首页的流程。文章偏实操但会把容易踩坑的地方讲透建议收藏备用。先给一个明确判断Skill 的真正价值不在于让 AI 多写几行代码而在于让 AI 在特定场景下按正确的顺序做事、检查正确的约束。微信小程序这种“文件多、配置多、验证链路长”的项目恰好是 Skill 收益最明显的场景。1. 为什么要给 AI 加一个“微信小程序 Skill”1.1 通用 AI 编程助手在小程序场景下差在哪通用 AI 编程助手写单页代码确实很强但把它丢进微信小程序项目你会很快发现三个问题。第一微信小程序不是一个“HTML 文件”而是一个复合工程。一个页面至少要包含.js、.wxml、.wxss、.json四个文件还要在app.json的pages数组里注册路径。AI 如果只是按“我要一个列表页”来理解很容易漏掉注册这一步结果代码看着没问题一编译就报“页面路径未注册”或者干脆白屏。第二微信小程序有大量工程级约束是通用模型不会主动考虑的。比如rpx自适应单位、navigationBarTitleText的页面标题配置、wx.request的域名校验、TabBar 图标路径必须真实存在、sitemap.json的索引配置。这些约束分散在多个文件里靠一段临时 Prompt 很难让 AI 全部遵守。第三运行验证有壁垒。小程序不能直接在浏览器里跑通必须借助微信开发者工具。AI 生成的代码如果没有project.config.json、没有 AppID 说明用户拿到项目后连“如何让这个项目跑起来”都得自己摸索。很多 AI 生成的小程序项目就是这样死在“最后一步”。1.2 Skill 解决的是“上下文 流程”问题Skill 的本质是把一组领域知识、工作流脚本和使用边界打包成可复用模块。在支持 Skill/Agent 机制的编程工具中例如 Claude Code、Codex、Cursor 等一个 Skill 通常包含一个描述文件常见命名为SKILL.md里面写清楚这个技能处理什么问题、触发条件是什么、实施步骤是什么、输出规范是什么必要时还可以带上模板资源和辅助脚本。对比一下更有感觉。用普通 Prompt 时你每次都要给 AI 重新描述一遍背景AI 只能靠当前对话上下文猜用 Skill 时AI 识别需求属于“微信小程序项目生成”后会自动加载一套既定工作流先解析需求为页面清单再生成工程骨架然后补页面代码最后做运行前自检。相当于把“团队里最熟悉小程序工程的同事”的经验沉淀成了可复用的文件。这也解释了为什么会有一批人专门在做 Skill、分享 Skill。Skill 表面上是给 AI 写说明书本质上是在做“工程经验的结构化”。对微信小程序这种约束密集的场景这种结构化的收益非常直接。2. 微信小程序从需求到首次运行要闯几道关2.1 需求层一句话需求不等于页面清单“我要个会议室预约小程序”这句话距离可开发的项目还差很远。需求层要做的是拆解小程序是工具类、展示类还是表单类首页展示什么是否需要详情页是否需要提交表单是否涉及登录是否需要真实后端在这个阶段AI 最常犯的错误是“过度设计”和“缺页”。过度设计是指把用户一句话需求扩展出一堆不存在的功能缺页则是漏掉最核心的页面。Skill 里应该明确要求先输出页面清单和字段说明和用户确认后再动手生成代码。这一步看起来慢实际能省掉大量返工。2.2 工程层文件与配置必须成对出现小程序工程的一个核心规则是“注册即生效未注册即报错”。app.json里的pages数组是项目的地图这里声明了哪些页面存在window配置全局窗口样式tabBar配置底部导航。每个页面则要对应四个文件page.js、page.wxml、page.wxss、page.json。任何一个文件缺失或者路径写错编译阶段就会失败。这个环节是 AI 代码最容易出问题的地方也是 Skill 最应该发力做自检的地方。与其让用户去开发者工具里看报错不如在生成阶段就完成“文件存在性检查”和“路径一致性检查”。2.3 运行层小程序必须有开发者工具介入小程序不像网页项目npm run dev之后浏览器就能看效果。它需要微信开发者工具导入项目目录、指定 AppID、点击编译。首次运行能否顺利很大程度取决于project.config.json是否完整以及appid是占位符还是真实测试号。Skill 的输出里必须把“如何导入”和“如何替换 AppID”写成明确的指引否则项目再规范用户也进不了下一步。3. Skill 的目录结构与 SKILL.md 设计3.1 推荐的 Skill 目录结构我做的这个 Skill 按“描述 模板 脚本 清单”四部分组织目录结构如下weapp-builder/ ├── SKILL.md ├── resources/ │ ├── templates/ │ │ ├── page.js.hbs │ │ ├── page.wxml.hbs │ │ ├── page.wxss.hbs │ │ └── page.json.hbs │ └── checklists/ │ └── pre-run-check.md └── scripts/ ├── generate-project.js └── verify-project.jsSKILL.md是入口负责告诉 AI 在什么情况下使用这个技能、按什么步骤执行resources/templates放页面模板resources/checklists放运行前自检清单scripts放真正可执行的校验脚本。这样 AI 既能看到“方法论”也能直接调用“工具”两件事各司其职。3.2 SKILL.md 里到底写了什么SKILL.md的核心不是长篇大论教 AI 什么是小程序而是给出一套可执行的作业流程。我的经验是一份有效的小程序构建 Skill 必须包含六个部分触发条件明确什么输入会触发这个 Skill例如“用户要求生成小程序项目”“用户描述了一个小程序需求”。输入处理把用户需求拆成页面清单并列出每个页面的功能点、字段、跳转关系。工程规范写入必须遵守的约束例如使用rpx作为尺寸单位、页面需在app.json注册、跳转路径必须与页面路径一致。实施步骤定义从骨架到页面再到自检的执行顺序禁止跳步。输出规范规定最终交付物的清单包括工程目录、AppID 说明、运行指引。自检清单在交付前由 AI 或脚本完成的关键检查项。3.3 一份可参考的 SKILL.md 片段下面是我在 Skill 中使用的一段SKILL.md核心内容可以直接作为参考--- name: weapp-builder description: 根据需求生成可运行的微信小程序项目骨架与页面代码 --- # 微信小程序构建技能 ## 触发条件 - 用户要求生成微信小程序项目或描述了一个需要做小程序的业务需求。 - 当前工作区没有微信小程序工程结构或用户明确要求重新生成。 ## 输入处理 1. 将需求拆解为页面清单输出表格包含页面路径、页面功能、主要交互。 2. 与用户确认页面清单确认后再生成代码不要跳步。 ## 工程规范 - 所有尺寸单位使用 rpx容器布局优先使用 flex。 - 页面必须包含 js / wxml / wxss / json 四个文件。 - app.json 的 pages 数组必须包含所有页面页面路径以 pages/ 开头。 - 暂未接后端时页面内使用本地 mock 数据禁止直接 wx.request 到未配置域名。 - 使用 project.config.json 描述项目配置appid 使用占位符 __APPID__。 ## 实施步骤 1. 生成 app.json / app.js / app.wxss / project.config.json / sitemap.json。 2. 按页面清单逐个生成页面四个文件。 3. 运行 node scripts/verify-project.js 检查工程一致性。 4. 输出运行指引如何用微信开发者工具导入项目如何替换 AppID。 ## 自检清单 - [ ] app.json 中 pages 数组与 pages 目录文件一一对应。 - [ ] project.config.json 中 appid 不为空允许占位符。 - [ ] 所有页面 json 文件均为合法 JSON。 - [ ] 页面跳转路径与实际页面路径一致。这里的关键不是让 AI “尽量遵守”而是让它在执行时把这些规则当成硬性任务。用清单而不是散文描述规则AI 的执行稳定性会高很多。4. 环境准备与前置条件4.1 工具链清单要在本地完整跑通这个小程序生成流程你需要准备以下工具工具用途说明Node.js运行生成和校验脚本建议使用 LTS 版本具体版本以项目实际为准微信开发者工具导入并编译小程序从微信官方渠道下载稳定版即可AI 编程工具加载 Skill、执行生成流程支持 Skill/Agent 机制的工具均可Git管理项目版本便于回滚和记录 Skill 的迭代这些工具里微信开发者工具是刚需。没有它小程序项目无法完成“首次运行”的验证。Node.js 则用于运行verify-project.js这类辅助脚本版本不需要太新能运行常见脚本即可。4.2 AppID 的两种选择小程序项目必须绑定一个 AppID但很多新手就是在这里卡住的。实际上 AppID 有两种选择第一种是正式 AppID需要在小程序公众平台注册账号后获取。个人开发者可以注册个人主体的小程序适合个人项目和功能演示企业主体的小程序则能使用更多能力。第二种是测试号微信开发者工具在新建项目时可以直接选择“测试号”不需要注册就能编译和预览。测试号适合先跑通页面逻辑但真机预览、云开发、部分开放接口会受限。从“需求到首次运行”的目标看我的建议是先使用测试号或占位符把项目跑起来确认页面和交互没问题再替换为正式 AppID。不要在第一轮验证时就卡在注册流程上。project.config.json中的appid字段是 AppID 的落点生成项目时可以先写占位符__APPID__在导入工具时手动替换。4.3 最小可跑的验证环境所谓“最小可跑”是指不需要后端、不需要数据库、不需要域名就能在开发者工具里看到的项目状态。达到这个状态你只需要一个完整的工程骨架和本地 mock 数据。这也是这个 Skill 强制“首跑阶段不引入网络请求”的原因。等到小程序在模拟器里跑通了再逐步接入真实的wx.request、云开发或后端服务。5. 完整示例从需求到首跑的“会议预约”小程序5.1 需求输入与 Skill 处理结果下面用一个真实场景演示整个流程。你给 AI 的原始输入是做一个公司内部会议预约小程序能看到会议室列表和空闲状态可以点进去填写预约人、时间和用途提交后提示成功。样式干净即可。Skill 解析后输出页面清单如下页面路径功能主要交互pages/rooms/rooms会议室列表展示名称、位置、容量、空闲状态点击会议室进入预约页pages/book/book预约表单填写预约人、日期时间、用途提交表单校验后提示成功pages/rooms/rooms是首页通过app.json的pages数组第一项指定。pages/book/book通过wx.navigateTo跳转进入。5.2 工程骨架生成Skill 生成工程骨架时核心是以下几个文件。app.json是整个项目的地图所有页面必须先在这里注册{ pages: [ pages/rooms/rooms, pages/book/book ], window: { navigationBarTitleText: 会议室预约, navigationBarBackgroundColor: #4A90D9, navigationBarTextStyle: white, backgroundColor: #F5F6FA }, style: v2, sitemapLocation: sitemap.json }project.config.json负责告诉微信开发者工具“这是一个可导入的小程序项目”{ compileType: miniprogram, appid: __APPID__, projectname: meeting-room-booking, miniprogramRoot: ./, setting: { es6: true, postcss: true, minified: true, urlCheck: false } }app.js是最小入口这个阶段不需要复杂逻辑// 文件路径app.js App({ onLaunch() { console.log(小程序启动); } });这个阶段有一个容易犯的错误忘记sitemap.json。微信开发者工具编译时会对sitemapLocation做检查缺少文件会报警告。所以 Skill 也会顺带生成一个最小配置{ rules: [ { action: allow, page: * } ] }5.3 首页列表实现本地数据先行首页是会议室列表。这里有一个非常重要的设计决策首跑阶段不要用wx.request直接使用本地 mock 数据数组。原因是wx.request会触发合法域名校验开发者工具即使勾选了“不校验合法域名”也会给新手带来额外的中断感。先用本地数据把页面渲染出来后面再替换成接口是成本最低的路径。pages/rooms/rooms.js// 文件路径pages/rooms/rooms.js const rooms [ { id: 1, name: A101 小会议室, location: 1 层东侧, capacity: 6, status: 空闲 }, { id: 2, name: B203 中会议室, location: 2 层西侧, capacity: 12, status: 使用中 }, { id: 3, name: C305 大会议室, location: 3 层中部, capacity: 30, status: 空闲 } ]; Page({ data: { rooms: [] }, onLoad() { this.setData({ rooms }); }, goBook(e) { const id e.currentTarget.dataset.id; wx.navigateTo({ url: /pages/book/book?id${id} }); } });pages/rooms/rooms.wxmlview classcontainer view classroom-card wx:for{{rooms}} wx:keyid>.container { padding: 24rpx; } .room-card { background: #fff; border-radius: 16rpx; padding: 32rpx; margin-bottom: 24rpx; box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.05); } .room-name { font-size: 32rpx; font-weight: 600; color: #333; } .room-meta { font-size: 24rpx; color: #888; margin-top: 12rpx; } .room-status { display: inline-block; margin-top: 16rpx; padding: 6rpx 20rpx; border-radius: 20rpx; font-size: 24rpx; } .room-status.free { background: #E8F7EE; color: #2BA245; } .room-status.busy { background: #FDECEC; color: #D9534F; }pages/rooms/rooms.json{ navigationBarTitleText: 会议室列表 }这里的布局刻意用了rpx和flex这也是 Skill 工程规范的一部分。小程序里750rpx等于屏幕宽度按这个基准做自适应比用px稳定得多。5.4 预约表单与提交反馈点击会议室卡片后通过wx.navigateTo进入预约页。预约页需要接收上一个页面传递的id在onLoad的options参数里读取。pages/book/book.js// 文件路径pages/book/book.js Page({ data: { roomId: , name: , date: , purpose: }, onLoad(options) { this.setData({ roomId: options.id || }); }, onInput(e) { const field e.currentTarget.dataset.field; this.setData({ [field]: e.detail.value }); }, submitBooking() { const { name, date, purpose } this.data; if (!name || !date || !purpose) { wx.showToast({ title: 请填写完整信息, icon: none }); return; } wx.showToast({ title: 预约成功, icon: success }); setTimeout(() wx.navigateBack(), 1500); } });pages/book/book.wxmlview classcontainer view classform-item text classlabel预约人/text input classinput placeholder请输入姓名>// 文件路径scripts/verify-project.js const fs require(fs); const path require(path); const root process.argv[2] || .; const appJsonPath path.join(root, app.json); if (!fs.existsSync(appJsonPath)) { console.error([FAIL] app.json 不存在); process.exit(1); } const appJson JSON.parse(fs.readFileSync(appJsonPath, utf8)); const pages appJson.pages || []; let hasError false; pages.forEach((page) { const basePath path.join(root, page); [.js, .wxml, .wxss, .json].forEach((ext) { const file basePath ext; if (!fs.existsSync(file)) { console.error([FAIL] 缺少文件: ${page}${ext}); hasError true; } }); }); const projectConfigPath path.join(root, project.config.json); if (!fs.existsSync(projectConfigPath)) { console.error([FAIL] project.config.json 不存在); hasError true; } else { const projectConfig JSON.parse(fs.readFileSync(projectConfigPath, utf8)); if (!projectConfig.appid || projectConfig.appid __APPID__) { console.warn([WARN] appid 仍是占位符导入开发者工具前需替换); } } if (hasError) { console.error([FAIL] 工程结构检查未通过); process.exit(1); } else { console.log([PASS] 工程结构检查通过可以尝试导入微信开发者工具); }运行方式是node scripts/verify-project.js ./meeting-room-booking这个脚本把“能不能跑”的一部分判断从人肉变成自动化也正好体现了 Skill 里“脚本 清单”的组合价值清单是做规则约束脚本是提供可验证的客观结果。6. 在微信开发者工具中运行与验证6.1 导入项目的正确姿势生成的项目目录包含project.config.json微信开发者工具会把它识别为小程序项目。导入步骤如下打开微信开发者工具选择“导入项目”。项目目录选择包含project.config.json的根目录也就是整个meeting-room-booking文件夹。AppID 选择“测试号”或手动填入你的正式 AppID。点击“确定”等待工具加载并在模拟器中编译。如果工具提示“不是小程序项目目录”优先检查project.config.json是否存在、compileType是否为miniprogram、miniprogramRoot是否指向正确目录。6.2 预期效果与判断标准编译成功后模拟器里应显示首页列表展示三个会议室卡片其中“A101”和“C305”状态为“空闲”“B203”状态为“使用中”。点击“A101 小会议室”会跳转到预约页填写完整信息后点击“提交预约”页面弹出“预约成功”提示并在 1.5 秒后返回列表页。判断是否成功的标准有三个编译无红色报错、模拟器出现预期页面、交互链路完整。只要这三条满足这个由 AI 生成的微信小程序就完成了“从需求到首次运行的完整流程”。6.3 首跑失败的通用排查顺序如果首次编译没有出现预期效果按下面的顺序排查效率最高先看微信开发者工具“调试器”的 Console 面板红色报错是首选线索然后确认app.json中页面路径与实际目录是否一致再看project.config.json的appid是否已被替换最后检查每个页面的.json文件是否是合法 JSON一个多余逗号都会导致编译失败。这套排查顺序也应该被写进 Skill 的自检清单里因为它是 AI 下次生成时最容易出错的位置。7. 常见问题与排查方法以下是 AI 生成微信小程序项目时最常见的问题也基本覆盖了大多数首跑失败场景问题现象可能原因排查方式解决方案页面白屏或报“页面路径未注册”app.json的pages数组漏配或路径与文件目录不一致检查app.json对比pages目录结构在pages数组补充页面路径路径必须以pages/开头点击卡片跳转无反应wx.navigateTo的url路径错误或目标页面未注册查看 Console 报错检查跳转路径修正url并在app.json中注册目标页面样式错位、尺寸混乱混用rpx和px或容器没有用flex布局查看页面的wxss文件统一使用rpx列表容器改为flex布局请求报错或数据加载失败请求域名未配置或开发者工具未关闭域名校验查看 Console 中的请求报错信息开发阶段勾选“不校验合法域名”上线前配置 HTTPS 合法域名导入工具时提示 appid 无效project.config.json中appid是占位符或已过期打开project.config.json查看appid字段替换为测试号或正式 AppID编译失败、提示文件不存在页面四个文件不完整或 JSON 语法错误查看编译日志定位具体文件补齐缺失文件修正 JSON 格式TabBar 图标不显示或编译报错tabBar.list中的iconPath指向不存在的图片检查图标文件是否存在替换为真实图标路径或去掉tabBar配置修改代码后页面不刷新开发者工具未触发重新编译点击工具栏“编译”按钮手动重新编译或在编辑器中开启自动编译这些问题是 Skill 设计和迭代时最好的素材。每遇到一个新问题都可以把它整理成一条规则加进SKILL.md的自检清单让 Skill 越用越“懂行”。8. 最佳实践从“能跑”到“能上线”8.1 首跑阶段不要碰网络请求AI 生成的小程序项目默认应该优先保证“本地可跑”。任何wx.request、云函数调用都应该在页面跑通之后再接入。这既是为了减少域名校验带来的干扰也是为了把“页面逻辑问题”和“网络问题”分开排查。首跑阶段用本地 mock 数据等页面稳定后再替换为接口返回会顺畅很多。8.2 管理好 AppID 与 project.config.jsonproject.config.json里包含appid和projectname这类文件如果提交到公开仓库建议把appid写成占位符__APPID__通过README说明如何替换。真实appid属于账号敏感信息不应该出现在公开代码中。团队协作时也可以约定每个人使用自己的测试号避免互相覆盖开发者工具中的登录态。8.3 让 Skill 持续“长记性”Skill 不是一次写完就固定的。每当你发现 AI 在某个环节反复出错正确的做法是把这个问题沉淀成SKILL.md里的规则。比如发现 AI 经常忘记生成sitemap.json就在“自检清单”中加一项发现 AI 生成的wx.navigateTo路径经常多一个或少一个前缀就在“工程规范”中明确写法。Skill 本质上是一个可以持续迭代的经验库迭代速度越快AI 的表现越稳定。8.4 安全与合规边界使用 AI 生成业务代码时要特别注意数据安全和权限边界。生成的项目如果涉及用户数据应遵循最小权限原则只申请必要的接口权限不采集与业务无关的敏感信息。生产环境的接口调用必须经过合法授权不能在客户端保存密钥。涉及数据库或服务端变更时也要先在测试环境验证并做好备份和回滚方案。这些约束同样建议写进 Skill 的说明中让 AI 在生成代码时主动规避高风险设计。9. 总结与后续学习方向这个 Skill 的核心思路可以概括为把微信小程序从需求到首跑的流程从“靠经验、靠运气”变成“靠流程、靠清单”。它做的不是魔法而是把一个小程序工程师应该检查的事项结构化地交给 AI 去执行。从实践效果看这类 Skill 对两类人最有价值一类是被工程配置反复折磨的新手一类是想把重复性脚手架工作交给 AI 的进阶开发者。项目跑通之后可以继续往三个方向深入。第一是接入真实后端把本地 mock 数据替换为wx.request调用注意配置合法域名和错误处理第二是接入微信云开发用云函数和数据库让小程序具备完整的后台能力省去自己搭建服务器的成本第三是研究订阅消息推送这是小程序触达用户的重要方式也是很多线上项目的刚需。如果你正在做自己的 Skill我的建议是不要一开始就追求大而全先从一个你真正疲劳的场景切入把一次成功的流程固定下来再逐步迭代。小程序生成本身就是一个很好的起点因为它约束明确、验证链路清晰、失败反馈直接——你很快就能感受到Skill 到底把哪些体力活真正省掉了。