AI帮忙写代码这件事很多人用成了“高级搜索引擎”在对话框里反复描述需求生成一段代码粘过来改了又改。真正用得溜的开发者已经在做另一件事——把某一类代码生成的整套经验打包成一个 Agent Skill让 AI 一次性按照你想要的方式产出结果。围绕若依框架RuoYi后台管理系统的自动代码生成就是一个非常典型的场景。本文我会把 Agent Skill 的黄金三层结构掰开揉碎讲清楚再用五步法带你从零打造一个专门生成若依框架业务模块代码的 Skill整个过程全部是实操过的经验不是概念空转。1. 先搞懂为什么要给 AI “配技能”而不是反复“教对话”1.1 多轮对话生成若依代码的三大痛点若依框架的特点是约定非常强Controller 要返回统一响应、Service 要拆分接口与实现、实体类要加数据库映射注解、权限控制要打上RequiresPermissions、分页查询要调用startPage()……这些约定对于老手来说是“肌肉记忆”但对于 AI 来也一样如果每次都是零散对话它会频繁出错。我试过在没有 Skill 的情况下让 AI 生成一个“班级管理”模块结果代码看起来像若依实际上哪都不对Controller 里直接返回了自定义对象应该用AjaxResult或TableDataInfoMapper 层没用 MyBatis 注解也没写 XML实体字段也没有和数据库列做映射最要命的是菜单权限 SQL 完全不符合框架要求插入sys_menu表后菜单根本显示不出来。这类问题的本质在于每轮对话AI 都在“猜测”你的框架约定而不是根据自己的经验进行输出。如果你花了半小时把约定全部写在提示词里下一轮对话又要重写一遍。而 Agent Skill 解决的就是这个问题把框架约定固化成 AI 的长期记忆让它一上来就按标准执行。1.2 Skill 的本质把经验固化成资产理解 Agent Skill 最好的方式是把它类比成一个“入职培训包”。新员工刚进公司你需要让他读规范文档、看老代码、学命名规则培养一阵子才能上手。而 Skill 就是把这个“培养过程”压缩成三块结构化的资料让 AI 读完就上岗。描述层告诉 AI 这个 Skill 的身份、用途、适用边界相当于岗位说明书。规则层列出生成代码时必须遵守的硬性约束相当于开发规范。示例层给出符合所有约定的代码样例相当于老员工写的“标准答案”。三层结构互为支撑缺了哪一层效果都会打折扣。只给描述层AI 知道该干什么但不知道怎么做只给规则层AI 知道约束但缺少具体形态只给示例层AI 能模仿样子但把握不了深层逻辑。这就是为什么叫“黄金三层”——结构稳定可复用。2. Agent Skill 黄金三层结构拆解每一层该怎么填为什么这么填2.1 描述层让 AI 清楚自己的“身份卡”描述层是整个 Skill 最容易被轻视的一层很多人随手写一段话就完事了这是大忌。\ 描述层的写法直接决定了系统会不会在正确的时候加载这个 Skill、会不会跟其他 Skill 混淆。我在实际使用中总结出来描述层至少包含这四块名称NameSkill 的唯一标识建议用“若依-业务模块代码生成”这种格式简洁、可读。触发场景When to Use说明在什么条件下应该使用这个 Skill。比如 NLP 提示词中一旦出现若依、RuoYi、后台管理系统、CRUD 模块等关键词就自动触发。职责边界What It Does / What It Doesnt明确当前 Skill 负责什么、不负责什么。这里建议写得非常清楚。比如“负责生成后端代码与前端页面不负责部署配置、不改动已有业务逻辑、不解释框架原理”。很多人省掉这一块结果在调用时 AI 会“自作主张”做一些超出 Skill 范围的操作比如主动推荐注册中心、扯到微服务改造反而把你带偏。输出风格Output Style说明返回内容的组织方式包括是否给出代码块、是否需要逐文件输出、是否要附带简要说明。若依项目里我一般要求“每个文件一个独立代码块文件名作为代码块标注”这样方便批量建文件。提示描述层的文字要像写需求文档一样精确避免“等等”“可能”“也可以”这类模棱两可的词。AI 的风格是照字面执行的模糊描述等于把选择权还给了它。2.2 规则层框架约定要变成“硬约束”规则层是黄金三层里最体现功力的一层。若依框架的约定非常多但真正影响代码能否跑起来的其实也就十来条。规则不是抄源码而是要提炼成可执行的条目。我可以分享一份若依项目常用的规则清单你可以直接抄到自己的 Skill 里后端包结构com.xxx.system.controller、com.xxx.system.service、com.xxx.system.service.impl、com.xxx.system.mapper、com.xxx.system.domain不允许随意添加新包。Controller 统一继承BaseController返回类型是AjaxResult或TableDataInfo分页列表接口使用startPage()getDataTable()组合。Service 接口定义业务方法ServiceImpl 实现接口并继承ServiceImplMapper, Entity领域服务基类事务注解写在实现类上。Mapper 接口继承BaseMapperEntity复杂查询写在 XML 中简单 CRUD 不写 XML。实体类统一加上TableName注解字段对应数据库列时使用TableField映射驼峰与下划线。权限控制每个 Controller 方法都要标注RequiresPermissions(system:模块:功能)如system:class:list。操作日志写操作增删改、导入导出要在方法上加Log(title班级管理, businessTypeBusinessType.INSERT)。校验入参对象使用ValidatedNotBlank等校验注解不写手写校验逻辑。前端页面放在src/views/对应模块/下统一使用若依封装好的组件列表页必须有搜索区、表格区、操作列。菜单与权限 SQL插入sys_menu表时需包含目录、菜单、按钮三级节点并配置perms标识与后端RequiresPermissions对应。规则不宜过多。我一开始把几十条全部塞进去结果 Skill 文件巨大AI 检索时反而抓不住重点。后来精简到核心 12 条左右效果反而更稳定因为 AI 的上下文窗口看待一堆规则跟看待十几条规则筛选能力是不一样。2.3 示例层用“标准答案”调教输出口径示例层的价值怎么强调都不过分。规则写得再细AI 生成的代码还是会存在细节偏差因为语言模型是根据概率来生成内容的它需要看到具体的“正确答案”来锚定输出风格。示例层不需要把整个项目源码都放进去而是精选几个有代表性的完整文件。以若依系统为例我建议准备这六类示例一个实体类示例涵盖TableName、TableField、时间字段的JsonFormat、逻辑删除标记。一个 Controller 示例涵盖分页列表、详情、新增、修改、删除、权限注解、日志注解。一个 Service 接口与实现类示例展示接口与实现分离、事务注解、调用 Mapper 的写法。一个 Mapper 接口示例展示BaseMapper继承、XML 的写法边界。一个前端列表页示例展示搜索表单、表格、操作按钮、分页组件的使用。一个菜单 SQL 示例展示目录、菜单、按钮三级的 insert 语句。每个示例文件都不需要太长关键是结构完整、风格统一。AI 在生成新模块时会以这些示例为模板进行相似度匹配示例的质量直接决定生成结果的质量。我在实际使用中感觉示例代码中的注释风格、方法命名、参数顺序都会被模型模仿得很到位因此示例代码要像你希望 AI 产出的最终代码一样高标准。注意示例层不是让你贴大段源码就完了。建议给每个示例加一小段“示例说明”指出这段代码体现了哪些规则。这样 AI 才能把示例和规则关联起来而不是单纯死抄示例。3. 五步法实操从若依源码到可复用的 Agent Skill3.1 第一步找标准——从哪几类资料里抽取约定五步法的起点不是写文档而是收集资料。若依框架的约定分散在多个地方你需要按下面的清单去“挖”框架源码里自带的后端示例模块比如系统管理模块的代码这是最权威的样本。前端views目录下的页面代码观察列表页、表单页的写法。数据库初始化脚本如.sql文件看sys_menu表的数据结构理解菜单权限的层级关系。一套完整的业务模块比如某公司基于若依做过的实际项目看真实项目中额外的约定。我建议把收集到的资料分门别类放进五个文件夹controller示例、service示例、mapper示例、前端页面示例、sql示例。注意不要全塞进 Skill 里这些文件更多是你提炼规则和编写示例的素材如果全量塞入会导致文件过于庞大、检索困难。收集完成后通读一遍把你自己平时写若依代码时的“下意识动作”记录下来。这些动作往往是约定最核心的部分不会被写在框架文档里但直接影响代码是否能通过编译、能否跑到上线。3.2 第二步定边界——明确 Skill 负责什么、不碰什么这一步是我踩过最大的坑。最开始我做的 Skill 什么都能干既能生成后端代码又能做数据库设计还能帮忙处理服务器部署结果在实际运行中AI 经常把需求理解得很奇怪然后走向了一些奇怪的方向——本来是让它生成一个班级模块它却开始指导我修改配置文件、调整组件版本。后来我下决心把边界做了严格划分负责生成某个业务模块的后端 Java 代码Controller、Service、ServiceImpl、Mapper、实体类、DTO、前端 Vue 页面、菜单 SQL。不负责修改既有模块的代码、设计数据库表结构只基于已有表设计、解释框架原理、排查运行报错、处理部署配置。边界一旦清晰AI 的工作方式反而高效很多——它知道自己是“代码生成工具”而不是“全能助手”。这看起来约束了 AI 的能力实际上是解放了输出质量。\ 另外边界里还应该写明“输入要求”调用者必须提供什么信息才能开始生成比如“请提供业务模块的中文名称、表名、字段列表、所属权限前缀如 system 或 monitor”。否则 AI 连字段都没有就只能凭感觉硬编生成的结果当然没法用。3.3 第三步建素材——整理一份“框架弹药库”有了素材和边界接下来就是把素材“加工”成 Skill 能用的弹药。这一步具体做三件事第一提炼规则清单。把第一步收集的素材里反复出现的行为模式汇总成 10~15 条硬性规则。规则要写成祈使句尽量简短让 AI 一眼看明白执行要点。比如“Controller 必须继承 BaseController”就比“Controller 继承 BaseController 以获得分页等公共能力”更直接有效。第二编写精简示例。从素材中挑选 6~8 个代表性文件适当删减非核心代码保留关键结构和风格特征。每个示例文件用“文件名 代码 注意点”三个部分组织。注意点是提炼的规则在使用中的体现这样示例就不只是一个代码粘贴而是一个带讲解的教学材料。第三设计调用模板。也就是写清楚 Skill 被调用时的输入输出格式。我在自己的 Skill 里设计了一个简单的交互模板要求调用者按固定格式给出“模块名称、数据表名、业务字段列表、权限标识前缀”。这种模板化的方式能让后续输出非常稳定因为 AI 一旦收到结构化输入它会十分稳定地按这套路径来组织输出。3.4 第四步写 Skill——三层结构组装细节素材准备好后进入真正写 Skill 的环节。这里我以最通用的 Agent Skill Markdown 文件格式为例展示黄金三层结构如何落进文件里--- name: 若依-业务模块代码生成 description: 当用户需要基于若依框架生成业务模块的后端Java代码、前端Vue页面或菜单权限SQL时使用。触发词若依、RuoYi、后台管理系统、CRUD模块、代码生成。 ---这一整段只是元信息部分真正的结构要从正文开始。我的经验是在正文中第一段先写身份定位描述层接着写规则清单规则层最后是示例文件块示例层。三个部分用醒目的分隔线隔开让 AI 在加载时能非常清楚地识别结构。这里要特别提醒Skill 不是越长越好。一个合格的若依代码生成 Skill我建议控制在 8000 到 12000 字左右。内容太少覆盖不全内容太多则检索和加载都会变慢而且在 AI 面对长 Skill 时容易出现“前面规则写得很好后面示例根本没用上”的情况。解决方案是把最重要的规则放前面示例按“后端代码优先、前端与SQL其次”排列。3.5 第五步验效果——用三层测试用例检验 SkillSkill 写完不是终点要用测试用例来验证。我一般设计三类测试第一类叫“冒烟测试”给一个最简单的模块比如“字典类型管理”或者“公告管理”要求生成完整的后端 CRUD 代码。目标是验证代码能不能跑通基本流程有没有致命的结构错误。这类测试应该在 Skill 开发过程中反复执行每次修改规则或示例后都要重新跑一遍。第二类叫“边界测试”故意给一个特殊场景例如“数据表的字段特别多30”、“需要同时生成父子表结构”、“需要导入导出功能”。目的是检验 Skill 在复杂场景下的鲁棒性是不是一复杂就崩、就胡乱输出。第三类叫“回归测试”拿一个你已经手动开发过的模块让 AI 用 Skill 重新生成一遍交叉对比代码风格和实现逻辑。这能发现 Skill 是不是把某些自定义习惯带偏了导致生成的代码和你团队风格不一致。我在实际验证中发现一个特别管用的小技巧先在 AI 对话界面里单独加载 Skill然后用测试用例去触发不要跳过多轮对话直接让 Skill 生成。用多轮对话去执行会更符合实际使用方式因为 Skill 往往在对话中需要与用户交互确认信息。\ 每一轮测试后把 AI 的产出逐行对照规则清单检查把不符合项记录下来反向去修改规则或补充示例。通常需要迭代 3~5 轮Skill 的输出质量才会明显稳定。4. 实战演练让 Skill 生成一个“班级管理”模块4.1 一个可直接抄作业的 Skill 文件结构为了让你看得更明白我直接贴一个精简但完整的若依 Skill 文件框架。这个文件我用在一套基于若依框架的教务管理系统模拟项目里效果相当稳定。--- name: 若依-业务模块代码生成 description: 若依框架业务模块后端与前端代码生成。触发词若依/RuoYi/后台管理系统/业务模块 ---身份定位 你是一名资深 Java 开发工程师长期使用若依框架Spring Boot Vue MyBatis熟悉若依框架的所有代码规范和约定。你的职责是基于用户提供的业务信息生成符合若依框架规范的完整业务模块代码。严格遵守以下规则Controller 统一放在 controller 包继承 BaseController返回 AjaxResult 或 TableDataInfo。Service 接口与实现类分离ServiceImpl 继承 ServiceImpl并添加 Service 注解。所有 Controller 中写操作接口必须添加 Log 注解和 RequiresPermissions 注解。实体类使用 TableName 注解映射表字段使用 TableField 映射列时间字段添加 JsonFormat。分页列表接口调用 startPage()返回 getDataTable(list)。前端页面放在 src/views/目录对应模块下使用 el-form 与 el-table分页使用若依封装的 Pagination 组件。提供插入 sys_menu 表的 SQL包含目录、菜单、按钮三级按钮的 perms 标识与后端注解对应。输入信息不完整时先列出所需字段信息并等待用户补充不自行臆造。示例文件实体类示例 [示例1实体类代码]示例文件Controller 示例 [示例2Controller代码]示例文件ServiceImpl 示例 [示例3ServiceImpl代码]示例文件Mapper 接口与 XML 示例 [示例4Mapper代码]示例文件前端列表页示例 [示例5Vue代码]示例文件菜单 SQL 示例 [示例6SQL代码]这个结构你可以直接用。需要注意中间的人工提示语气全部用“你”来称呼 AI保持命令式。实际运行中要记得把 [示例1实体类代码] 等占位符换成真实的示例代码你手上如果有某个做完的若依项目直接把这些模块代码摘出来作为示例就好。 ### 4.2 完整跑一遍从输入到四个文件一次生成 我以“班级管理”模块为例实际跑一遍这个 Skill。给 AI 输入以下信息模块名称班级管理 表名tb_class 业务字段class_name班级名称、grade_name年级、head_teacher班主任、student_count学生人数、create_time创建时间 权限标识前缀system:classSkill 被触发后AI 会进行多维度的审视判断注意看它的处理步骤。我观察到 AI 先在内部逻辑里分析表字段和后端实体类的映射关系然后按“实体类 → Mapper → Service → Controller → 前端页面 → SQL”的结构逐个文件生成。中途不会有多余的提问因为输入信息已经齐了它会直接执行。 以下是几个关键文件的生成效果我摘一段最重要的 Controller 代码 java RestController RequestMapping(/system/class) public class ClassController extends BaseController { Autowired private IClassService classService; RequiresPermissions(system:class:list) GetMapping(/list) public TableDataInfo list(ClassQuery query) { startPage(); ListClass list classService.selectClassList(query); return getDataTable(list); } Log(title 班级管理, businessType BusinessType.INSERT) RequiresPermissions(system:class:add) PostMapping public AjaxResult add(Validated RequestBody Class clazz) { return toAjax(classService.insertClass(clazz)); } Log(title 班级管理, businessType BusinessType.UPDATE) RequiresPermissions(system:class:edit) PutMapping public AjaxResult edit(Validated RequestBody Class clazz) { return toAjax(classService.updateClass(clazz)); } Log(title 班级管理, businessType BusinessType.DELETE) RequiresPermissions(system:class:remove) DeleteMapping(/{ids}) public AjaxResult remove(PathVariable Long[] ids) { return toAjax(classService.deleteClassByIds(ids)); } }可以看到权限注解、日志注解、统一返回结构、校验注解都齐了格式与若依日常代码保持一致。这个结果靠纯对话很难一次做到而 Skill 加持后基本是每次稳定输出这个水平。实体类示例则按规则把TableName(tb_class)写到类上TableField处理了驼峰和下划线的映射时间字段加上JsonFormat(pattern yyyy-MM-dd HH:mm:ss)。Mapper 层查询接口使用了Param注解XML 路径和命名空间配置也准确。前端页面生成的则是若依常见的搜索区加表格区结构。4.3 Skill 化前后的效果对比到底差在哪我把同一需求分别在“无 Skill 对话”和“有 Skill 输出”两种场景下跑了一遍差异非常明显。无 Skill 时生成一个完整模块平均需要 4~6 轮对话且至少会出现 2 到 3 处约定性错误比如权限注解漏写、返回类型不对、菜单 SQL 缺少按钮层级。有 Skill 时基本上一次生成、小幅修订即可交付代码风格更统一集成时间减少一半以上。差异的根源不是“聪明程度”不同而是 AI 在无 Skill 时需要从长距离上下文里自己拼凑约定容易丢失关键约束在有 Skill 时规则与示例直接注入上下文相当于 AI 有了“记忆锚点”。这也是为什么我强烈建议团队里凡是基于若依开发的人都配一个这样的 Skill——它能消除大量低级错误让团队把精力花在真正的业务逻辑上。5. 常见问题与排查经验Skill 不好用大概率是这几件事没做对5.1 三个最容易踩的坑第一个坑是“规则与示例冲突”。我在某次迭代中调整了规则要求 Controller 列表方法返回TreeDataInfo因为一个模块需要树表但示例层还是老的分页结构。结果 AI 生成时一会儿用新规则一会儿照旧示例代码里两种风格并存根本没有整体逻辑。解决办法是每次改规则必须同步检查所有示例确保两者指向同一个标准。第二个坑是“示例太特殊化”。从前端示例中有一处使用了自定义组件来处理级联选择这个组件只在我那套系统里存在。Skill 生成其他模块时AI 也依样画葫芦写了个不存在的组件导入前端运行直接报错。示例一定要选择“通识部分”把个性化逻辑剔除干净或者明确标注“以下为个性化代码不通用”。第三个坑是“Skill 的容错不足”。用户提供的信息不完整时Skill 如果没有写清“等待补充”的规则AI 就会自己编造表名、编造字段。比如你只说了“生成学生模块”没给表名AI 可能生成一套基于student表的代码实际库里的表叫tb_student_info这样直接不能用。所以规则层必须有这一条输入不完整时要停下来索要信息而不是硬着头皮生成。提示如果你发现 Skill 生成一个模块要五轮以上对话反复修改才能用不是你的建模思路有问题而是 Skill 的规则/示例明细不够。建议先输出一次结果把 AI 犯的每类错误记录成表再回头看规则层和示例层缺了什么。5.2 排查口诀与效率提升技巧我用了很长一段时间总结出四个字的口诀看、查、改、验。看是看他生成的代码结构整体是否连贯有没有文件缺失。查是把生成代码的注解、返回类型、导入路径等项目逐条对照检查。改是一旦发现某类问题反复出现回到 Skill 修改对应规则或示例。验是用回归测试确认修改有效、且没影响其他模块的生成效果。效率上还有一个很实用的技巧是“给 Skill 配备配套输入模板”。我在 Skill 描述层中设置了标准输入格式每次使用时直接把表结构导出信息粘过来AI 就能自动完成“表字段 → 实体类字段 → 表单字段 → SQL 菜单”的映射。这会减少海量的来回确认时间。5.3 后续迭代方向从单模块生成到全模块规划这个 Skill 的初级形态是“单模块 CRUD 生成”实际用顺手之后完全可以迭代成多版本的“全套后台管理系统生成”。比如你可以给 Skill 增加“支持树表结构”“支持主子表结构”“支持导入导出功能”“支持定时任务代码生成”等扩展模块每次新增一个扩展能力就找一份对应的真实案例塞进示例层。我最近在往这个方向推进给 Skill 增加了一套“项目级初始化”规则让 AI 可以根据需求描述一次性生成多张表、多个模块的后端代码和前端菜单甚至输出完整的菜单初始化 SQL 脚本。虽然还做不到完美但已经能让我在搭建模拟项目原型时省下一天的重复劳动。6. 最后分享一点我个人的实操体会做 Agent Skill 这件事技术含量不在于会写 Markdown、会写规则而在于你能不能把自己脑子里那些“不成文的经验”摊开来变成 AI 能执行的条目。我先后迭代过不少版本最开始的规则清单写得又全又细反而不好用因为 AI 被太多约束困住输出变得很僵硬。后来我学会了“少即是多”只保留关键约束把判断空间留给模型效果反而提升。另外有个习惯值得培养每次让 AI 生成一段若依代码之后不管代码是不是直接能跑我都会花两分钟对照检查一遍。不是不信任 AI而是这个检查过程本身就是打磨 Skill 的素材——你把发现的问题记下来回到规则层补一句下次生成就会少一类问题。这样反复迭代你的 Skill 会越用越顺手越用越“懂你”。如果你所在的团队也在用若依这类强约定框架我建议你下一周就动手做一个专属 Skill。不用追求一步到位先从最常写的 CRUD 模块开始跑顺手了再逐步加功能。这套“黄金三层结构 五步法”不止适用于若依任何有固定代码模式的框架场景——比如生成报表模板、写特定风格的接口文档——都可以用同样的套路去沉淀和复用。 
长河君 · 2026/10/21 23:59:16 · 阅读 1.2k Agent Skill黄金三层结构：用五步法打造若依框架代码生成技能
AI帮忙写代码这件事很多人用成了“高级搜索引擎”在对话框里反复描述需求生成一段代码粘过来改了又改。真正用得溜的开发者已经在做另一件事——把某一类代码生成的整套经验打包成一个 Agent Skill让 AI 一次性按照你想要的方式产出结果。围绕若依框架RuoYi后台管理系统的自动代码生成就是一个非常典型的场景。本文我会把 Agent Skill 的黄金三层结构掰开揉碎讲清楚再用五步法带你从零打造一个专门生成若依框架业务模块代码的 Skill整个过程全部是实操过的经验不是概念空转。1. 先搞懂为什么要给 AI “配技能”而不是反复“教对话”1.1 多轮对话生成若依代码的三大痛点若依框架的特点是约定非常强Controller 要返回统一响应、Service 要拆分接口与实现、实体类要加数据库映射注解、权限控制要打上RequiresPermissions、分页查询要调用startPage()……这些约定对于老手来说是“肌肉记忆”但对于 AI 来也一样如果每次都是零散对话它会频繁出错。我试过在没有 Skill 的情况下让 AI 生成一个“班级管理”模块结果代码看起来像若依实际上哪都不对Controller 里直接返回了自定义对象应该用AjaxResult或TableDataInfoMapper 层没用 MyBatis 注解也没写 XML实体字段也没有和数据库列做映射最要命的是菜单权限 SQL 完全不符合框架要求插入sys_menu表后菜单根本显示不出来。这类问题的本质在于每轮对话AI 都在“猜测”你的框架约定而不是根据自己的经验进行输出。如果你花了半小时把约定全部写在提示词里下一轮对话又要重写一遍。而 Agent Skill 解决的就是这个问题把框架约定固化成 AI 的长期记忆让它一上来就按标准执行。1.2 Skill 的本质把经验固化成资产理解 Agent Skill 最好的方式是把它类比成一个“入职培训包”。新员工刚进公司你需要让他读规范文档、看老代码、学命名规则培养一阵子才能上手。而 Skill 就是把这个“培养过程”压缩成三块结构化的资料让 AI 读完就上岗。描述层告诉 AI 这个 Skill 的身份、用途、适用边界相当于岗位说明书。规则层列出生成代码时必须遵守的硬性约束相当于开发规范。示例层给出符合所有约定的代码样例相当于老员工写的“标准答案”。三层结构互为支撑缺了哪一层效果都会打折扣。只给描述层AI 知道该干什么但不知道怎么做只给规则层AI 知道约束但缺少具体形态只给示例层AI 能模仿样子但把握不了深层逻辑。这就是为什么叫“黄金三层”——结构稳定可复用。2. Agent Skill 黄金三层结构拆解每一层该怎么填为什么这么填2.1 描述层让 AI 清楚自己的“身份卡”描述层是整个 Skill 最容易被轻视的一层很多人随手写一段话就完事了这是大忌。\ 描述层的写法直接决定了系统会不会在正确的时候加载这个 Skill、会不会跟其他 Skill 混淆。我在实际使用中总结出来描述层至少包含这四块名称NameSkill 的唯一标识建议用“若依-业务模块代码生成”这种格式简洁、可读。触发场景When to Use说明在什么条件下应该使用这个 Skill。比如 NLP 提示词中一旦出现若依、RuoYi、后台管理系统、CRUD 模块等关键词就自动触发。职责边界What It Does / What It Doesnt明确当前 Skill 负责什么、不负责什么。这里建议写得非常清楚。比如“负责生成后端代码与前端页面不负责部署配置、不改动已有业务逻辑、不解释框架原理”。很多人省掉这一块结果在调用时 AI 会“自作主张”做一些超出 Skill 范围的操作比如主动推荐注册中心、扯到微服务改造反而把你带偏。输出风格Output Style说明返回内容的组织方式包括是否给出代码块、是否需要逐文件输出、是否要附带简要说明。若依项目里我一般要求“每个文件一个独立代码块文件名作为代码块标注”这样方便批量建文件。提示描述层的文字要像写需求文档一样精确避免“等等”“可能”“也可以”这类模棱两可的词。AI 的风格是照字面执行的模糊描述等于把选择权还给了它。2.2 规则层框架约定要变成“硬约束”规则层是黄金三层里最体现功力的一层。若依框架的约定非常多但真正影响代码能否跑起来的其实也就十来条。规则不是抄源码而是要提炼成可执行的条目。我可以分享一份若依项目常用的规则清单你可以直接抄到自己的 Skill 里后端包结构com.xxx.system.controller、com.xxx.system.service、com.xxx.system.service.impl、com.xxx.system.mapper、com.xxx.system.domain不允许随意添加新包。Controller 统一继承BaseController返回类型是AjaxResult或TableDataInfo分页列表接口使用startPage()getDataTable()组合。Service 接口定义业务方法ServiceImpl 实现接口并继承ServiceImplMapper, Entity领域服务基类事务注解写在实现类上。Mapper 接口继承BaseMapperEntity复杂查询写在 XML 中简单 CRUD 不写 XML。实体类统一加上TableName注解字段对应数据库列时使用TableField映射驼峰与下划线。权限控制每个 Controller 方法都要标注RequiresPermissions(system:模块:功能)如system:class:list。操作日志写操作增删改、导入导出要在方法上加Log(title班级管理, businessTypeBusinessType.INSERT)。校验入参对象使用ValidatedNotBlank等校验注解不写手写校验逻辑。前端页面放在src/views/对应模块/下统一使用若依封装好的组件列表页必须有搜索区、表格区、操作列。菜单与权限 SQL插入sys_menu表时需包含目录、菜单、按钮三级节点并配置perms标识与后端RequiresPermissions对应。规则不宜过多。我一开始把几十条全部塞进去结果 Skill 文件巨大AI 检索时反而抓不住重点。后来精简到核心 12 条左右效果反而更稳定因为 AI 的上下文窗口看待一堆规则跟看待十几条规则筛选能力是不一样。2.3 示例层用“标准答案”调教输出口径示例层的价值怎么强调都不过分。规则写得再细AI 生成的代码还是会存在细节偏差因为语言模型是根据概率来生成内容的它需要看到具体的“正确答案”来锚定输出风格。示例层不需要把整个项目源码都放进去而是精选几个有代表性的完整文件。以若依系统为例我建议准备这六类示例一个实体类示例涵盖TableName、TableField、时间字段的JsonFormat、逻辑删除标记。一个 Controller 示例涵盖分页列表、详情、新增、修改、删除、权限注解、日志注解。一个 Service 接口与实现类示例展示接口与实现分离、事务注解、调用 Mapper 的写法。一个 Mapper 接口示例展示BaseMapper继承、XML 的写法边界。一个前端列表页示例展示搜索表单、表格、操作按钮、分页组件的使用。一个菜单 SQL 示例展示目录、菜单、按钮三级的 insert 语句。每个示例文件都不需要太长关键是结构完整、风格统一。AI 在生成新模块时会以这些示例为模板进行相似度匹配示例的质量直接决定生成结果的质量。我在实际使用中感觉示例代码中的注释风格、方法命名、参数顺序都会被模型模仿得很到位因此示例代码要像你希望 AI 产出的最终代码一样高标准。注意示例层不是让你贴大段源码就完了。建议给每个示例加一小段“示例说明”指出这段代码体现了哪些规则。这样 AI 才能把示例和规则关联起来而不是单纯死抄示例。3. 五步法实操从若依源码到可复用的 Agent Skill3.1 第一步找标准——从哪几类资料里抽取约定五步法的起点不是写文档而是收集资料。若依框架的约定分散在多个地方你需要按下面的清单去“挖”框架源码里自带的后端示例模块比如系统管理模块的代码这是最权威的样本。前端views目录下的页面代码观察列表页、表单页的写法。数据库初始化脚本如.sql文件看sys_menu表的数据结构理解菜单权限的层级关系。一套完整的业务模块比如某公司基于若依做过的实际项目看真实项目中额外的约定。我建议把收集到的资料分门别类放进五个文件夹controller示例、service示例、mapper示例、前端页面示例、sql示例。注意不要全塞进 Skill 里这些文件更多是你提炼规则和编写示例的素材如果全量塞入会导致文件过于庞大、检索困难。收集完成后通读一遍把你自己平时写若依代码时的“下意识动作”记录下来。这些动作往往是约定最核心的部分不会被写在框架文档里但直接影响代码是否能通过编译、能否跑到上线。3.2 第二步定边界——明确 Skill 负责什么、不碰什么这一步是我踩过最大的坑。最开始我做的 Skill 什么都能干既能生成后端代码又能做数据库设计还能帮忙处理服务器部署结果在实际运行中AI 经常把需求理解得很奇怪然后走向了一些奇怪的方向——本来是让它生成一个班级模块它却开始指导我修改配置文件、调整组件版本。后来我下决心把边界做了严格划分负责生成某个业务模块的后端 Java 代码Controller、Service、ServiceImpl、Mapper、实体类、DTO、前端 Vue 页面、菜单 SQL。不负责修改既有模块的代码、设计数据库表结构只基于已有表设计、解释框架原理、排查运行报错、处理部署配置。边界一旦清晰AI 的工作方式反而高效很多——它知道自己是“代码生成工具”而不是“全能助手”。这看起来约束了 AI 的能力实际上是解放了输出质量。\ 另外边界里还应该写明“输入要求”调用者必须提供什么信息才能开始生成比如“请提供业务模块的中文名称、表名、字段列表、所属权限前缀如 system 或 monitor”。否则 AI 连字段都没有就只能凭感觉硬编生成的结果当然没法用。3.3 第三步建素材——整理一份“框架弹药库”有了素材和边界接下来就是把素材“加工”成 Skill 能用的弹药。这一步具体做三件事第一提炼规则清单。把第一步收集的素材里反复出现的行为模式汇总成 10~15 条硬性规则。规则要写成祈使句尽量简短让 AI 一眼看明白执行要点。比如“Controller 必须继承 BaseController”就比“Controller 继承 BaseController 以获得分页等公共能力”更直接有效。第二编写精简示例。从素材中挑选 6~8 个代表性文件适当删减非核心代码保留关键结构和风格特征。每个示例文件用“文件名 代码 注意点”三个部分组织。注意点是提炼的规则在使用中的体现这样示例就不只是一个代码粘贴而是一个带讲解的教学材料。第三设计调用模板。也就是写清楚 Skill 被调用时的输入输出格式。我在自己的 Skill 里设计了一个简单的交互模板要求调用者按固定格式给出“模块名称、数据表名、业务字段列表、权限标识前缀”。这种模板化的方式能让后续输出非常稳定因为 AI 一旦收到结构化输入它会十分稳定地按这套路径来组织输出。3.4 第四步写 Skill——三层结构组装细节素材准备好后进入真正写 Skill 的环节。这里我以最通用的 Agent Skill Markdown 文件格式为例展示黄金三层结构如何落进文件里--- name: 若依-业务模块代码生成 description: 当用户需要基于若依框架生成业务模块的后端Java代码、前端Vue页面或菜单权限SQL时使用。触发词若依、RuoYi、后台管理系统、CRUD模块、代码生成。 ---这一整段只是元信息部分真正的结构要从正文开始。我的经验是在正文中第一段先写身份定位描述层接着写规则清单规则层最后是示例文件块示例层。三个部分用醒目的分隔线隔开让 AI 在加载时能非常清楚地识别结构。这里要特别提醒Skill 不是越长越好。一个合格的若依代码生成 Skill我建议控制在 8000 到 12000 字左右。内容太少覆盖不全内容太多则检索和加载都会变慢而且在 AI 面对长 Skill 时容易出现“前面规则写得很好后面示例根本没用上”的情况。解决方案是把最重要的规则放前面示例按“后端代码优先、前端与SQL其次”排列。3.5 第五步验效果——用三层测试用例检验 SkillSkill 写完不是终点要用测试用例来验证。我一般设计三类测试第一类叫“冒烟测试”给一个最简单的模块比如“字典类型管理”或者“公告管理”要求生成完整的后端 CRUD 代码。目标是验证代码能不能跑通基本流程有没有致命的结构错误。这类测试应该在 Skill 开发过程中反复执行每次修改规则或示例后都要重新跑一遍。第二类叫“边界测试”故意给一个特殊场景例如“数据表的字段特别多30”、“需要同时生成父子表结构”、“需要导入导出功能”。目的是检验 Skill 在复杂场景下的鲁棒性是不是一复杂就崩、就胡乱输出。第三类叫“回归测试”拿一个你已经手动开发过的模块让 AI 用 Skill 重新生成一遍交叉对比代码风格和实现逻辑。这能发现 Skill 是不是把某些自定义习惯带偏了导致生成的代码和你团队风格不一致。我在实际验证中发现一个特别管用的小技巧先在 AI 对话界面里单独加载 Skill然后用测试用例去触发不要跳过多轮对话直接让 Skill 生成。用多轮对话去执行会更符合实际使用方式因为 Skill 往往在对话中需要与用户交互确认信息。\ 每一轮测试后把 AI 的产出逐行对照规则清单检查把不符合项记录下来反向去修改规则或补充示例。通常需要迭代 3~5 轮Skill 的输出质量才会明显稳定。4. 实战演练让 Skill 生成一个“班级管理”模块4.1 一个可直接抄作业的 Skill 文件结构为了让你看得更明白我直接贴一个精简但完整的若依 Skill 文件框架。这个文件我用在一套基于若依框架的教务管理系统模拟项目里效果相当稳定。--- name: 若依-业务模块代码生成 description: 若依框架业务模块后端与前端代码生成。触发词若依/RuoYi/后台管理系统/业务模块 ---身份定位 你是一名资深 Java 开发工程师长期使用若依框架Spring Boot Vue MyBatis熟悉若依框架的所有代码规范和约定。你的职责是基于用户提供的业务信息生成符合若依框架规范的完整业务模块代码。严格遵守以下规则Controller 统一放在 controller 包继承 BaseController返回 AjaxResult 或 TableDataInfo。Service 接口与实现类分离ServiceImpl 继承 ServiceImpl并添加 Service 注解。所有 Controller 中写操作接口必须添加 Log 注解和 RequiresPermissions 注解。实体类使用 TableName 注解映射表字段使用 TableField 映射列时间字段添加 JsonFormat。分页列表接口调用 startPage()返回 getDataTable(list)。前端页面放在 src/views/目录对应模块下使用 el-form 与 el-table分页使用若依封装的 Pagination 组件。提供插入 sys_menu 表的 SQL包含目录、菜单、按钮三级按钮的 perms 标识与后端注解对应。输入信息不完整时先列出所需字段信息并等待用户补充不自行臆造。示例文件实体类示例 [示例1实体类代码]示例文件Controller 示例 [示例2Controller代码]示例文件ServiceImpl 示例 [示例3ServiceImpl代码]示例文件Mapper 接口与 XML 示例 [示例4Mapper代码]示例文件前端列表页示例 [示例5Vue代码]示例文件菜单 SQL 示例 [示例6SQL代码]这个结构你可以直接用。需要注意中间的人工提示语气全部用“你”来称呼 AI保持命令式。实际运行中要记得把 [示例1实体类代码] 等占位符换成真实的示例代码你手上如果有某个做完的若依项目直接把这些模块代码摘出来作为示例就好。 ### 4.2 完整跑一遍从输入到四个文件一次生成 我以“班级管理”模块为例实际跑一遍这个 Skill。给 AI 输入以下信息模块名称班级管理 表名tb_class 业务字段class_name班级名称、grade_name年级、head_teacher班主任、student_count学生人数、create_time创建时间 权限标识前缀system:classSkill 被触发后AI 会进行多维度的审视判断注意看它的处理步骤。我观察到 AI 先在内部逻辑里分析表字段和后端实体类的映射关系然后按“实体类 → Mapper → Service → Controller → 前端页面 → SQL”的结构逐个文件生成。中途不会有多余的提问因为输入信息已经齐了它会直接执行。 以下是几个关键文件的生成效果我摘一段最重要的 Controller 代码 java RestController RequestMapping(/system/class) public class ClassController extends BaseController { Autowired private IClassService classService; RequiresPermissions(system:class:list) GetMapping(/list) public TableDataInfo list(ClassQuery query) { startPage(); ListClass list classService.selectClassList(query); return getDataTable(list); } Log(title 班级管理, businessType BusinessType.INSERT) RequiresPermissions(system:class:add) PostMapping public AjaxResult add(Validated RequestBody Class clazz) { return toAjax(classService.insertClass(clazz)); } Log(title 班级管理, businessType BusinessType.UPDATE) RequiresPermissions(system:class:edit) PutMapping public AjaxResult edit(Validated RequestBody Class clazz) { return toAjax(classService.updateClass(clazz)); } Log(title 班级管理, businessType BusinessType.DELETE) RequiresPermissions(system:class:remove) DeleteMapping(/{ids}) public AjaxResult remove(PathVariable Long[] ids) { return toAjax(classService.deleteClassByIds(ids)); } }可以看到权限注解、日志注解、统一返回结构、校验注解都齐了格式与若依日常代码保持一致。这个结果靠纯对话很难一次做到而 Skill 加持后基本是每次稳定输出这个水平。实体类示例则按规则把TableName(tb_class)写到类上TableField处理了驼峰和下划线的映射时间字段加上JsonFormat(pattern yyyy-MM-dd HH:mm:ss)。Mapper 层查询接口使用了Param注解XML 路径和命名空间配置也准确。前端页面生成的则是若依常见的搜索区加表格区结构。4.3 Skill 化前后的效果对比到底差在哪我把同一需求分别在“无 Skill 对话”和“有 Skill 输出”两种场景下跑了一遍差异非常明显。无 Skill 时生成一个完整模块平均需要 4~6 轮对话且至少会出现 2 到 3 处约定性错误比如权限注解漏写、返回类型不对、菜单 SQL 缺少按钮层级。有 Skill 时基本上一次生成、小幅修订即可交付代码风格更统一集成时间减少一半以上。差异的根源不是“聪明程度”不同而是 AI 在无 Skill 时需要从长距离上下文里自己拼凑约定容易丢失关键约束在有 Skill 时规则与示例直接注入上下文相当于 AI 有了“记忆锚点”。这也是为什么我强烈建议团队里凡是基于若依开发的人都配一个这样的 Skill——它能消除大量低级错误让团队把精力花在真正的业务逻辑上。5. 常见问题与排查经验Skill 不好用大概率是这几件事没做对5.1 三个最容易踩的坑第一个坑是“规则与示例冲突”。我在某次迭代中调整了规则要求 Controller 列表方法返回TreeDataInfo因为一个模块需要树表但示例层还是老的分页结构。结果 AI 生成时一会儿用新规则一会儿照旧示例代码里两种风格并存根本没有整体逻辑。解决办法是每次改规则必须同步检查所有示例确保两者指向同一个标准。第二个坑是“示例太特殊化”。从前端示例中有一处使用了自定义组件来处理级联选择这个组件只在我那套系统里存在。Skill 生成其他模块时AI 也依样画葫芦写了个不存在的组件导入前端运行直接报错。示例一定要选择“通识部分”把个性化逻辑剔除干净或者明确标注“以下为个性化代码不通用”。第三个坑是“Skill 的容错不足”。用户提供的信息不完整时Skill 如果没有写清“等待补充”的规则AI 就会自己编造表名、编造字段。比如你只说了“生成学生模块”没给表名AI 可能生成一套基于student表的代码实际库里的表叫tb_student_info这样直接不能用。所以规则层必须有这一条输入不完整时要停下来索要信息而不是硬着头皮生成。提示如果你发现 Skill 生成一个模块要五轮以上对话反复修改才能用不是你的建模思路有问题而是 Skill 的规则/示例明细不够。建议先输出一次结果把 AI 犯的每类错误记录成表再回头看规则层和示例层缺了什么。5.2 排查口诀与效率提升技巧我用了很长一段时间总结出四个字的口诀看、查、改、验。看是看他生成的代码结构整体是否连贯有没有文件缺失。查是把生成代码的注解、返回类型、导入路径等项目逐条对照检查。改是一旦发现某类问题反复出现回到 Skill 修改对应规则或示例。验是用回归测试确认修改有效、且没影响其他模块的生成效果。效率上还有一个很实用的技巧是“给 Skill 配备配套输入模板”。我在 Skill 描述层中设置了标准输入格式每次使用时直接把表结构导出信息粘过来AI 就能自动完成“表字段 → 实体类字段 → 表单字段 → SQL 菜单”的映射。这会减少海量的来回确认时间。5.3 后续迭代方向从单模块生成到全模块规划这个 Skill 的初级形态是“单模块 CRUD 生成”实际用顺手之后完全可以迭代成多版本的“全套后台管理系统生成”。比如你可以给 Skill 增加“支持树表结构”“支持主子表结构”“支持导入导出功能”“支持定时任务代码生成”等扩展模块每次新增一个扩展能力就找一份对应的真实案例塞进示例层。我最近在往这个方向推进给 Skill 增加了一套“项目级初始化”规则让 AI 可以根据需求描述一次性生成多张表、多个模块的后端代码和前端菜单甚至输出完整的菜单初始化 SQL 脚本。虽然还做不到完美但已经能让我在搭建模拟项目原型时省下一天的重复劳动。6. 最后分享一点我个人的实操体会做 Agent Skill 这件事技术含量不在于会写 Markdown、会写规则而在于你能不能把自己脑子里那些“不成文的经验”摊开来变成 AI 能执行的条目。我先后迭代过不少版本最开始的规则清单写得又全又细反而不好用因为 AI 被太多约束困住输出变得很僵硬。后来我学会了“少即是多”只保留关键约束把判断空间留给模型效果反而提升。另外有个习惯值得培养每次让 AI 生成一段若依代码之后不管代码是不是直接能跑我都会花两分钟对照检查一遍。不是不信任 AI而是这个检查过程本身就是打磨 Skill 的素材——你把发现的问题记下来回到规则层补一句下次生成就会少一类问题。这样反复迭代你的 Skill 会越用越顺手越用越“懂你”。如果你所在的团队也在用若依这类强约定框架我建议你下一周就动手做一个专属 Skill。不用追求一步到位先从最常写的 CRUD 模块开始跑顺手了再逐步加功能。这套“黄金三层结构 五步法”不止适用于若依任何有固定代码模式的框架场景——比如生成报表模板、写特定风格的接口文档——都可以用同样的套路去沉淀和复用。