用SKILL让Claude Code自动生成管理后台：实操指南与避坑经验

前两天我干了一件事把一套叫admin-panel-builder的 SKILL 装进 Claude Code然后看着它自己把一整个管理后台从头到尾写完了。不是那种“帮我写个页面”的碎活而是从数据库表、接口、列表页、表单校验到权限控制全部一条龙跑通。这件事给我最大的冲击不是 AI 能写代码而是当你能把“套路”固化成一个技能包的时候AI 的产出质量和稳定性会发生质变。这篇博客我会把整套思路拆开讲清楚SKILL 到底是个什么东西它和普通对话式编程有什么区别一个能自动生成管理后台的 SKILL 应该怎么设计以及我在实操过程中踩过的坑和最终的可用方案。适合正在用 Claude Code、想提升 AI 编程效率的开发者也适合刚开始接触 Agent 编程、想知道“skills 怎么用”的新手。1. 为什么要给 Claude Code 装 SKILL从聊天助手到交付工程师1.1 Claude Code 本身已经很能打但它有个隐藏问题Claude Code 是 Anthropic 推出的命令行 AI 编程工具你可以在终端里直接让它读项目代码、改文件、跑命令、看报错甚至连续多轮完成一个完整功能。单论能力它已经比“复制代码到聊天框”领先一大截因为它有项目上下文能感知当前仓库的结构。但用了一段时间之后我发现自己陷入一种重复劳动每次让它做一个新模块我都要重新交代一遍技术栈、目录规范、接口风格、数据模型放哪里、UI 组件用哪个。比如今天做商品列表明天做订单列表后天做用户列表功能长得差不多但每次对话都要从零开始教育模型。如果哪天忘了交代某个约束它就会给你生成一套“看起来能用但和项目风格完全不一致”的代码改起来比从头写还痛苦。1.2 没有 SKILL 的时候我的真实工作流长什么样我之前的流程是这样的打开 Claude Code先来一大段提示词——“我们现在是 Next.js 项目用了 Prisma页面在 app 目录下api 在 app/api 下列表页要分页表单要校验按钮用 shadcn 的 Button颜色用主题变量……”然后才敢说“帮我写一个商品管理”。这个流程有三个问题。第一每次输入大量的背景说明Token 消耗高不说还容易漏第二即使同一个人写提示词今天写一套明天写一套Claude 生成的结果也会跟着飘第三项目里有多个成员时每个人的口头禅和习惯不一样生成出的代码风格很难统一。你可能会说那我把这些规则写进 CLAUDE.md 不就行了确实可以但 CLAUDE.md 更像一个“项目说明书”它描述的是项目是什么、结构怎么样、有哪些依赖。而 SKILL 更像“工序标准书”它描述的是“当你接到某类任务时应该按什么步骤去做、产出什么、自查什么”。拿管理后台来说CLAUDE.md 能告诉它我们用了什么框架SKILL 则能告诉它用户表该怎么出列表页、删除操作要不要做二次确认、接口统一返回什么格式。1.3 SKILL 的真正价值把个人经验变成稳定的流程资产我给 Claude Code 装的这个 SKILL本质上是把“我过去半年写管理后台的经验”固化成了一份可复用的指令。它不是简单告诉模型“你要生成一个后台”而是告诉它拿到数据模型之后先做什么、再做什么遇到关联关系怎么展开页面需要覆盖哪些功能点完成后要自查哪些项。装上之后的变化是肉眼可见的。我再也不用在每次对话里重复项目背景了只要说一句“用 admin-panel-builder 技能按照 schema.prisma 生成后台”它就会自动加载这套工作流产出的代码结构非常稳定。如果说之前的 Claude Code 是一个聪明的实习生那么装了 SKILL 之后它变成了一个“带 SOP 的熟练工”。换个角度说SKILL 的真正价值不是“多了一个技能点”而是把隐性的经验变成了显性的流程资产。你能把某一个领域的交付标准固化下来以后不管是自己用、让同事用、还是换台电脑重新装环境行为一致性都还在。这一点对我来说比“生成的代码本身”更重要。2. SKILL 的结构与核心设计思路2.1 一个 SKILL 到底由什么组成在 Claude Code 的体系里SKILL 是一个目录一般放在两个位置全局目录~/.claude/skills/和项目目录.claude/skills/。全局的适用于所有项目项目级的只对当前仓库生效而且项目级会优先。我的习惯是通用开发能力放全局和特定项目绑定的流程放项目级。比如 admin-panel-builder 这种适配多种框架的技能放全局而只适配当前公司内部代码规范的技能就放项目仓库里。一个标准 SKILL 目录大概长这样admin-panel-builder/ ├── SKILL.md └── resources/ ├── form-template.tsx ├── list-page-template.tsx └── api-route-template.tsSKILL.md是整个技能的核心里面用 YAML front matter 写技能的名字和描述正文写执行步骤和规则。resources目录用来放参考模板、示例代码、数据库设计样例Claude Code 并不会在加载技能时把这些文件全部塞进上下文而是等模型需要时再读取。这个设计很聪明既能提供参考又不占满上下文窗口。2.2 管理后台技能的核心配置拆解先给你看一下我这个技能的SKILL.md长什么样我再解释每一段的意思--- name: admin-panel-builder description: 根据数据模型生成管理后台。当用户提到“后台”“管理页面”“CRUD”“列表页表单页”时需要优先使用。 --- # Admin Panel Builder 你是一个资深全栈工程师负责生成完整的管理后台模块。 执行前先阅读仓库根目录的 schema.prisma 或数据模型文件。 如果存在 resources 目录下的模板优先参考模板中的目录结构、接口写法和 UI 组织方式。 ## 执行步骤 1. 分析数据模型列出所有需要生成后台页面的实体。 2. 对每个实体输出 - 服务端 API 路由列表、详情、新增、更新、删除 - 列表页分页、搜索、状态标签、操作按钮 - 表单页新增/编辑复用包含字段校验 - 删除操作统一加二次确认 3. 遵守项目现有技术栈和目录约定不要引入额外 UI 库。 4. 生成完成后逐项自查 - 接口字段与模型字段是否一致 - 列表页是否有 loading 和错误态 - 表单是否有必填校验 - 外键关联是否做了下拉选择或联动这部分我刻意写得比较“实”。你可以看到我没有说“请优化用户体验”这种空话而是给出了非常具体的执行步骤和自查项。SKILL 的本质就是给模型立规矩先干什么、后干什么、产出什么、怎么才算合格。如果描述写得含糊Claude Code 的执行结果也一定会含糊。2.3 SKILL 的 front matter 和描述决定了它会不会被触发很多人第一次写 SKILL最容易忽略的就是description这一行。Claude Code 是怎么判断什么时候该用哪个技能的呢靠的就是模型根据对话内容去匹配技能描述。所以 description 要写得像“搜索引擎关键词”一样准确覆盖你可能使用的各种说法。比如我的描述里写了“后台”“管理页面”“CRUD”“列表页表单页”这样当我在对话里说“帮我生成一个用户管理后台”时模型就更可能触发这个技能。如果你只写“管理后台”触发率会低很多尤其是当用户换个说法比如“弄个商品管理的界面”时它可能就认不出来。另外技能名字也有讲究。目录名最好用英文小写加连字符SKILL.md是固定的文件名不能改成admin.md或者skill.md大小写写错都不行。我第一次就把文件名写成了Skill.md结果折腾了半天没生效后来才发现 Linux 环境下文件名是严格区分大小写的。还有一点SKILL 不是独立运行的 Agent它是 Agent 的“操作手册”。技能本身不会自己在后台跑必须由 Claude Code 在对话中根据描述来加载。这个概念很多人容易搞混以为装了 SKILL 就等于建了个自动机器人其实不是。SKILL 的作用是“当我要做某类事情时模型会按照这套标准来做”它提升的是质量上限不是自动化程度。3. 实操过程从数据模型到一个自动生成的管理后台3.1 环境准备与技能安装先说安装。确保你已经在系统里装好了 Claude Code并且在项目目录能够正常启动对话。如果是第一次用直接在你的项目根目录下运行claude进入交互界面后确认 Claude Code 有权限读写项目文件。接着我把技能目录放进项目里mkdir -p .claude/skills/admin-panel-builder/resources然后把SKILL.md写进.claude/skills/admin-panel-builder/把模板文件放进resources/。这里我建议直接放在项目级.claude目录里因为管理后台通常和具体项目绑定项目级还能跟随 Git 提交团队其他人 clone 下来就自动有效。装完之后不需要重启直接新开一轮对话即可Claude Code 会在对话过程中动态发现技能。为了测试它到底有没有被加载我习惯在对话里输入/skills查看当前可用的技能列表。如果列表里出现了admin-panel-builder说明加载成功如果没出现优先检查目录路径、文件名大小写、YAML front matter 格式。这三个地方是出错率最高的。3.2 实战演示商品管理后台的生成全过程为了让你有体感我复现一次完整的生成过程。项目用的技术栈是 Next.js 14 Prisma SQLite shadcn/ui。为什么选这套因为本地无需额外装数据库schema 定义清晰页面和接口可以在同一个仓库里生成适合做演示。你完全可以根据自己项目换成 Vue3 Element Plus或者 React 18 Ant DesignSKILL 的核心逻辑不变。假设项目的prisma/schema.prisma里有这样的数据模型model User { id Int id default(autoincrement()) email String unique name String? role String default(user) createdAt DateTime default(now()) } model Product { id Int id default(autoincrement()) title String price Decimal stock Int default(0) categoryId Int? category Category? relation(fields: [categoryId], references: [id]) status String default(draft) createdAt DateTime default(now()) } model Category { id Int id default(autoincrement()) name String products Product[] }我在 Claude Code 里输入一句话用 admin-panel-builder 技能根据 prisma/schema.prisma 生成一个商品管理后台包含分类和用户管理。接下来它做的事让我挺意外的。第一步它没有急着写代码而是先把schema.prisma读了一遍然后在对话里列出它准备生成的实体清单Product、Category、User。每个实体它都规划了“列表页、表单页、API 路由”三个产出物。这基本就是在执行我在 SKILL.md 里写的第一个步骤。然后它开始动手生成。接口部分它在app/api/products/route.ts写了列表接口支持page、pageSize、keyword参数在app/api/products/[id]/route.ts写了详情、更新、删除接口。列表页部分它生成了app/admin/products/page.tsx和app/admin/products/[id]/page.tsx。列表页有表头、分页、加载态、空数据占位表单页有基础校验外键字段categoryId做成了下拉选择框。我特别留意了它对关联关系的处理在 Product 表单里Category 下拉框的数据是异步从/api/categories拉取的而不是写死选项。这说明它在执行 SKILL 时确实考虑了数据模型里的 relation而不是简单地把字段平铺出来。等它全部生成完我让它跑一遍npx prisma migrate dev和npm run lint过程中有报错它会自己读日志、改代码直到通过为止。这一步其实是很多提示词做不到的普通提示词让你“生成管理后台”更多时候是给你一堆代码片段然后让你自己拼有了 SKILL它知道要把接口、页面、校验、错误态当成一个完整功能来交付做完之后还要自查。3.3 我实际验证过的目录结构生成完之后项目里新增的文件结构大致是app/ ├── admin/ │ ├── products/ │ │ ├── page.tsx │ │ └── [id]/page.tsx │ ├── categories/ │ │ ├── page.tsx │ │ └── [id]/page.tsx │ └── users/ │ ├── page.tsx │ └── [id]/page.tsx └── api/ ├── products/ │ ├── route.ts │ └── [id]/route.ts ├── categories/ │ ├── route.ts │ └── [id]/route.ts └── users/ ├── route.ts └── [id]/route.ts结构非常规整没有乱丢文件。这里我要强调一个细节这些文件路径不是我手写死的是因为我在 SKILL.md 里写了“遵守项目现有目录约定”而项目里原本已经有app/admin的路由分组所以 Claude Code 自动把页面塞进了app/admin/productsAPI 放到了app/api/products。这说明 SKILL 不是模板填空而是规则引导它会在规则范围内结合项目情况做判断。当然不是一次生成就完美。我第一次跑的时候Prisma 里Decimal类型被序列化成了字符串前端表格显示没问题但搜索接口不起作用。这不是大问题把它丢给 Claude Code 看报错就能修。后面我会专门讲这类问题。3.4 技能不是越复杂越好关键是能稳定触发这个经验我特别想分享写 SKILL 最忌讳“大而全”。一开始我也尝试写一个超长版本把所有能想到的场景都塞进去比如“如果用户角色是 admin 则隐藏删除按钮”“如果金额大于 1000 显示红色”“支持多语言切换”等等。结果发现描述太长导致模型每次都要花大量上下文“消化规则”反而在基础 CRUD 上容易出错产出也变得更慢。后来我把 SKILL.md 精简到 40 行左右只保留每个后台都通用的骨架读模型、分层生成、遵循项目约定、自查四项。至于那些“如果……就……”的业务逻辑我倾向于不提或者放到resources目录里的模板中按需加载。因为基础 CRUD 本来就该稳定输出业务规则应该由对话里的即时指令去补充而不是全部写死在技能里。4. 管理后台自动生成中的关键细节与代码约束4.1 数据模型设计是自动生成的前提如果你准备让 Claude Code 用 SKILL 生成后台首要前提是数据模型要足够清晰。我这里说的“清晰”不是指字段多复杂而是命名统一、关系明确、有注释。命名统一能让模型准确推断字段含义关系明确能保证外键正确变成下拉框或联动注释则是给模型的“提示词”有时候一行/// 是否上架比你在 SKILL 里写十条规则都管用。比如商品模型里的status字段如果只写status String default(draft)模型大概率会默认做成一个普通文本框。但如果你在注释里写清楚“状态draft-草稿onSale-在售offSale-下架”它就能自动生成一个带选项的 Select 组件而且选项文案都跟着注释走。还有一点字段类型的选择要慎重。能用布尔值表达的就不要用字符串能用外键关联的就不要存冗余 ID 字符串。因为模型在生成查询、接口和表单时会严格按照 Prisma 的字段类型推断组件类型。你把isActive定义成Boolean它在表单里就会生成开关定义成String它就生成输入框。这个体验上的差别直接影响后台好不好用。4.2 权限与危险操作别让 AI 无脑生成删除按钮管理后台最容易出事的地方不是列表查询慢而是删除操作太随意。AI 不知道你的业务场景里哪些记录能删、哪些只能软删所以你必须通过 SKILL 给它立规矩。我在 SKILL.md 里写了一条硬性规则所有删除接口必须返回统一的删除结果格式前端删除按钮必须有二次确认。同时当一个模型设置了deletedAt DateTime?字段时删除操作默认改为软删也就是更新deletedAt而不是执行delete。所有查询默认排除deletedAt不为空的记录。这条规则虽然只有两句话但能挡住绝大多数“AI 爽快写物理删除”的问题。你想想如果让模型自由发挥它看到delete两个字很可能直接生成await prisma.product.delete()这在开发环境没事线上跑起来就是生产事故。任何时候都要记住AI 默认追求“功能实现”不会主动考虑“业务安全”。安全约束必须由人在 SKILL 里写死。除了删除另一个值得关注的点是接口鉴权。生成后台时如果项目已经有了鉴权中间件SKILL 里要明确要求“新接口必须应用现有的鉴权中间件”。我没有写具体实现因为每个项目都不一样但只要 SKILL 明确提出来Claude Code 就会在生成路由时主动去项目里找 middleware 并引入而不是生成一个裸奔的接口。4.3 让生成代码可维护的约束命名和错误处理自动生成代码最大的问题不是“能不能跑”而是“以后谁维护”。所以我给这个 SKILL 加了几个硬性要求第一所有列表接口统一返回{ list: [], total: number }前端分页组件直接消费这个结构不搞花活。第二所有 API 路由用 try/catch 包住业务逻辑错误信息通过统一的ApiError结构返回不让未捕获异常直接抛出导致前端拿到一堆非标准错误。第三函数和组件必须有基础命名规范fetchProductList、DeleteProductButton、ProductForm不允许出现handleClick1、data2这种没意义的命名。这些约束看起来琐碎但正是它们决定了生成代码的质量上限。你可以在 SKILL.md 里直接写也可以放在resources/api-route-template.ts里让模型对照着写。我更推荐后者模板文件能直观地展示“项目代码长什么样”模型照着临摹产出的一致性比单纯看文字描述高很多。比如我的resources/list-page-template.tsx里开头是一个标准的列表页组件包含了useState、useEffect、分页处理、Loading 状态和空数据占位。当 Claude Code 要生成新的列表页时它会以此为准而不是自己从头构思页面结构。这样做的好处非常明显所有新生成的页面风格统一后续维护人员看任何一个页面都能很快上手。5. 常见问题与排查技巧实录5.1 SKILL 不生效先查名字、描述和路径这是我在实践过程中遇到最多的问题。SKILL 装上了但 Claude Code 就是不调用或者明明在对话里提到了关键词它还是按普通模式生成。排查顺序我一般是这样先看目录路径是不是.claude/skills/技能名/SKILL.md注意层级不能错skills和SKILL.md之间必须隔一层技能名目录再看文件名大小写SKILL.md是全大写不能写成Skill.md然后看 front matter 里的name字段是否和目录名一致最后检查description是否覆盖了你的表达方式。如果都没有问题新开一轮对话再试一次因为技能有时是在会话初始化时加载的同一个会话里不会热更新。如果还是不行可以在对话里输入/skills看看技能是否出现在列表中。这个方法能快速判断问题出在“技能没加载成功”还是“描述了但没触发”。5.2 生成的代码报错要不要立刻手动改先让 AI 自己修很多人看到 AI 生成的代码在npm run dev时报错第一反应是直接手动改。我的建议是先别动手直接把报错信息发给 Claude Code它会自己看堆栈、找原因、改代码。管理后台这种 CRUD 项目报错原因无非就是依赖没装、路由路径不对、数据库字段名不一致、类型不匹配这几类模型处理起来绰绰有余。我遇到最有代表性的一个错误是 Prisma 的Decimal类型在 API 返回时被序列化成字符串导致前端表格里显示“19.99”没问题但搜索金额区间时条件一直不生效。这个错误初看很诡异但 Claude Code 在拿到报错后直接读了接口代码发现返回的字段没有做类型转换于是改成了返回数字类型。整个过程我只提供了一条指令“看看这个接口为什么搜索不生效”。所以我的经验是把 Claude Code 当结对程序员它写的代码出问题先让它自己修不要急着接管。只有当它连续修同一处超过三轮还不行或者修改方向明显偏离项目风格时再介入给明确指引。这样既能提升效率也能让 AI 的理解能力得到锻炼。5.3 上下文不够用拆分任务用 resources 代替长指令管理后台一次性生成的页面太多很容易把上下文撑爆。我一开始让 Claude Code 一口气生成四个实体的后台结果写到后面它就开始“失忆”前面定好的命名风格已经忘了接口响应结构也变了。教训是不要贪多。后期我的做法是一次生成一个实体顶多两个。生成的顺序也有讲究先生成 Category因为它最简单而且 Product 表单里的下拉框依赖它的接口再生成 Product因为它涉及分类关联和状态字段是核心最后生成 User。这样每一步的产出都能被下一步复用上下文压力小模型也能更好地保持一致性。另外在SKILL.md里不要写大段代码。代码模板应该放在resources目录下让模型按需读取。SKILL.md 本身只是操作流程说明书规则写太满会导致整个技能在每次对话中都被大量加载挤占用于“干活”的上下文空间。5.4 独家避坑经验注释、锁定 schema、统一风格最后分享几条我在反复折腾中总结出的经验不一定在官方文档里能查到但实战价值非常高。第一给数据模型加中文注释。这个前面说过再强调一次。Claude Code 对英文注释和中文注释的理解深度其实差不多但中文注释能帮你后续自己看懂模型生成的代码逻辑。更重要的是注释写清楚了模型生成表单的 label、筛选项的 placeholder、按钮文案都会更自然几乎不用二次调整。第二生成前锁定 schema不要在生成过程中反复改动模型。有一次我一边让它改商品后台一边自己顺手在 schema 里加了两个字段结果它生成到一半发现模型变了重新读了一遍文件导致前面已经生成的接口和页面和新字段衔接不上浪费了不少时间。现在我会先把 schema 改完锁定再让它动手。第三生成完之后立刻跑一次统一的 lint 和类型检查。如果项目没有配 lint至少跑npx tsc --noEmit或等价的类型检查命令。让 Claude Code 把检查结果里的所有问题一次清完再进入人工 review 环节。这一步能过滤掉绝大多数低级错误人工 review 只需要关注业务逻辑和交互细节压力小很多。第四如果团队多个人一起用SKILL.md 的变更要走 code review。它本质上是代码的一部分甚至影响面比普通代码还大。改一句“所有删除操作用软删除”可能影响后台所有模块的行为。所以别把 SKILL 当成个人备忘录它值得用维护标准库的认真程度来对待。我现在的工作习惯是凡是重复性比较高的开发套路都会先整理成一个 SKILL。管理后台是我用得最多的场景因为现在做 SaaS、做内部工具、做线上项目几乎每个项目最终都逃不掉一个后台。这个 admin-panel-builder 技能包我已经迭代了三版从最开始的“生成一个能看的页面”变成了现在“生成一个能上线、能维护、符合项目规范的后台模块”。根据我个人的体会SKILL 不会让 Claude Code 一夜之间变成高级工程师也不该指望它完全脱离人工作。它真正擅长的是把“稳定、重复、有套路”的活干得又快又好把时间省下来给你去思考那些 AI 干不了的事情——比如业务建模、权限方案、复杂的交互设计和异常边界。你可以直接拿我上面这个技能包改成自己的版本把技术栈、目录约定、UI 组件替换成你们团队的规范跑一遍之后大概率会回来感谢自己。