拓冰网站定制 
我一直觉得给AI编程工具写SKILL很多人一开始就走偏了。要么把SKILL写成一个巨无霸式的单一提示词什么场景都想覆盖结果AI在具体项目里经常表现得像个只会背课文的学生——道理都懂一操作就乱要么反过来SKILL只写了几个抽象的原则细节全靠AI临场发挥那效果就跟开盲盒一样这次能用下次就废。这次我对SKILL做了一次全新的尝试把思路彻底调了个个儿。我把手头的两个核心工程 service-api 和 web-admin 全部拆成了“框架 细节”的双层结构。这个改动的核心逻辑是用SKILL定义一套固定的、可复用的思考框架和执行流程把项目里那些真正会变、需要因地制宜的具体信息全部下沉到独立的细节文件里。这样SKILL本身变得极其稳定而细节文件可以随时增删修改完全不碰SKILL主体。折腾完这一轮我最大的感受是这个方向的尝试值得。所以把这套设计思路、拆解过程、实测验证结果和踩过的坑完整记录下来给也在研究SKILL怎么落地的朋友一个参考。1. 为什么非要把 service-api 和 web-admin 拆成“框架细节”先说清楚这次拆分的背景。我这两个工程并不是玩具项目service-api 是一套完整的后端服务接口层web-admin 是配套的后台管理系统两者都经历过好几轮迭代代码量大、业务规则多、模块之间藕断丝连的地方也不少。在打算做SKILL之前我其实陷入过一段时间的纠结。市面上的SKILL大多聚焦在“单任务”上比如“帮我写一个Python脚本”“帮我分析这段日志”这类SKILL把上下文写成一段话就完事了。但面对 service-api 和 web-admin 这种体量的工程单任务式SKILL完全不适用。你需要的是一个能理解整个项目结构、知道代码规范、能按既有模式添加新接口或新页面的“项目级”AI助手。一开始我尝试过把整个项目的所有相关信息都塞进SKILL的指令文件里——项目结构、目录说明、编码规范、数据库表、接口返回格式、分页规则甚至异常处理方式。结果就是SKILL文件膨胀到了几千行AI每次读取要消耗大量上下文窗口而且文件越长AI越容易抓不住重点。更尴尬的是项目里任何细微的变动比如某个表新增了一个字段都得去改SKILL主文件时间一长SKILL本身就成了一个新的维护负担。这就像你给一个新同事写入职手册把“公司食堂在哪”“厕所怎么走”“Git提交规范”“数据库表结构”“前端组件库用法”全塞进一页纸里这不叫手册这叫字典。没人能靠一本字典快速上手工作AI也一样。所以这次我把结构彻底改了。核心思路就一句话SKILL只负责“怎么干活”细节文件负责“项目是什么样的”。框架层是一套通用的思考路径和执行步骤细节层是对 service-api 和 web-admin 两个项目各自的定制化描述。两者通过固定的文件命名约定和引用规则绑定互不污染。这种做法的直接好处有四个SKILL主文件保持精简和稳定不需要频繁修改换新项目时只需要重写细节文件框架可以原样复用AI的执行流程变得可预期因为它每次都走同一套思考路径细节文件和SKILL分离后非技术角色也能参与维护细节内容2. 框架层到底该放什么把“稳定的动作”抽象出来先讲框架层。这部分对应SKILL中相对固定的执行流程是整个拆分的骨架。我把框架层定义成了一套“动作序列”不绑定任何具体业务。无论你要在 service-api 里加一个查询接口还是在 web-admin 里新增一个列表页面都走同一套动作序列。2.1 框架层的五个固定工序我最终把框架层收敛成五个工序顺序固定缺一不可。这五个工序在设计时参考了一个有经验的开发者接到新需求后的真实工作路径先看全貌再定方案然后动手做完自查最后是交付说明。项目结构感知AI先读取整体目录结构和关键配置文件在头脑里重建这个项目的物理地图。没有这一步AI后续的所有操作都是盲人摸象。模式对齐从细节文件中找到“已有功能的代码示例”搞清楚这个项目里一个接口或一个页面通常是怎么写的遵循哪些约定。方案设计基于感知到的结构和模式先用自然语言描述需求要落在哪个模块、新增哪些文件、改动哪些地方。这一步强制AI“先想后做”避免一上来就疯狂生成代码。分步实现按照方案逐文件落地每完成一个文件都做一次局部验证。交付自检对照细节文件里的质量红线逐条过一遍比如是否处理了异常、是否符合命名规范、是否补充了必要注释。这五个工序里最关键的是第2步“模式对齐”。我给每个项目做SKILL的时候都会刻意在细节文件里留出“范例代码”的位置让AI先“抄”再“写”。这样生成的代码风格才能和原项目保持一致否则AI很容易写出一个功能没问题但画风完全不一样的模块。2.2 框架层的指令编写要点框架层本身就是一个标准的SKILL指令文件但我在这次重构里特意做了几个调整效果非常明显用流程指令替代结果指令。不说“完成XX功能”而是说“先读取目录结构再定位相关模块然后参照细节文件中的示例”把AI的注意力引导到过程上。给每个工序设定输出物。比如方案设计阶段必须输出一段简短的“改动影响说明”自检阶段必须输出“自检清单勾选结果”。有输出物AI就不容易偷工减料跳步骤。限制并行度。我在指令里明确要求AI“一次只处理一个模块完成后再进入下一个模块”效果立竿见影生成的代码质量立刻稳定下来。让AI一次性产出整个项目的代码大概率会顾此失彼。框架层稳定下来后真正吃功夫的地方就到了细节层。这是这次尝试里我认为最有价值、也是坑最多的部分。3. 细节层怎么搭service-api 和 web-admin 的定制化实践如果框架层是“道”那细节层就是“术”。同一个框架套上 service-api 的细节就是一个后端服务AI助手套上 web-admin 的细节就是一个前端管理后台AI助手。细节层质量直接决定了SKILL实际干活时靠不靠谱。3.1 细节文件的信息架构我给每个项目都建了一个独立的细节目录带版本号方便回溯放在SKILL的技能包目录下里面分了六个维度项目概览定位、技术栈、运行方式、目录结构说明编码规范命名规则、代码风格、文件组织约定核心模式典型接口/页面的实现范式附完整示例代码数据契约核心数据表、返回结构、通用字段定义依赖清单必须使用的组件库、工具函数、第三方服务比如各类API注意安全合规质量红线绝对不允许出现的写法、必须要处理的分支、上线前必查项这六个维度基本覆盖了“让AI写出符合项目气质的代码”所需的全部信息。但维度定下来只是第一步真正麻烦的是内容怎么组织AI读起来才高效。3.2 service-api 细节层的核心设计service-api 是FastAPI体系的后端工程我一直强调接口层的输出必须稳定可控。所以它的细节层里“数据契约”和“核心模式”是重头戏。数据契约里我明确写了全局统一返回结构列出了请求体、响应体的字段命名规则和类型映射方式。最关键的是我把项目中几个高频场景的完整参数示例直接贴了进去。比如列表查询接口需要包含分页参数、筛选条件、排序规则、返回总条数详情接口需要包含路径参数校验、不存在时抛什么异常、详情字段裁剪规则。这些内容都是直接从线上代码里扒出来整理进去的不是凭空编出来的。核心模式里放了三类范例一个标准CRUD接口的完整实现一个涉及多表联查的复杂接口的拆解过程还有一个定时任务入口的写法。为什么放这三个因为项目里新增需求绝大多数都落在这三类范畴。AI在写新代码时会不断回看这些范例代码画风自然就统一了。还有一点容易被忽略我在细节层里补充了“本地启动的最小配置说明”。AI在做代码生成时经常会自己脑补一些并不存在的配置项或环境变量明确告诉它项目实际怎么跑起来能显著减少这类幻觉。3.3 web-admin 细节层的个性化处理web-admin 是Vue3 TypeScript的后台管理前端它的细节层和 service-api 有完全不同的侧重点。后端接口层最重要的是数据契约前端管理后台最核心的则是页面模式。我花了很长时间整理web-admin的“核心模式”因为后台管理页面的重复度实在太高了——列表页、表单页、详情页、弹窗操作、状态切换每个都是同构的套路。我把这些套路分别整理成了标准范式并且在细节文件里写清楚列表页的统一搜索组件怎么用、表格列的render函数怎么处理枚举状态、表单校验的规则怎么声明、页面权限指令怎么绑定。细节层还专门放了一个“典型列表页完整代码”大概两百行属于这个项目里最有代表性的一个业务页面。之所以选它当范例是因为它同时覆盖了搜索、分页、表格列定制、操作按钮、权限控制、状态标签几乎所有的前端后台常见元素。AI只要读懂这一个页面写其他列表页基本就不会跑偏。我还在web-admin的细节层里额外加了一类内容“禁止做的事”。比如不能直接改全局状态管理文件来塞临时数据不能绕过封装好的请求实例直接调用底层HTTP客户端新增页面必须在路由配置里显式注册。这些规则在编码规范里其实零散写过但把它们集中成一条条明确禁令AI对边界的感知会清晰得多。4. 把“框架细节”绑定起来SKILL的装配与引用机制框架有了细节也有了接下来要解决的是“怎么让AI在干活时知道该用哪套细节”。这一步就是SKILL的装配与引用机制处理不好前面拆得再干净也会打折扣。4.1 用入口文件穿针引线我在SKILL指令文件里设计了一个“入口判断逻辑”放在执行流程的最前面。当AI接收到一个新需求时第一件事不是写代码而是判断这个需求发生在哪个工程——请求内容涉及接口、数据、服务逻辑就加载 service-api 的细节涉及页面、组件、路由、样式就加载 web-admin 的细节。如果两者都涉及按先接口后页面的顺序分两个阶段处理。入口文件里我还会用一段固定格式把这个判断过程显式输出比如“本次需求作用于service-api将加载项目细节版本 v2.1”。这么做看似多余但实际用起来有个好处如果AI判断错了场景你可以在它动手前一眼看出来及时纠正。这也算是一个低成本的人机校验环节。4.2 细节文件的引用粒度细节文件不是让AI一口气全读一遍。所有细节都放出来上下文窗口爆炸不说AI还会迷失重点。我采取的是“按需拉取”的方式入口判断命中项目后AI只读取“项目概览”和“编码规范”建立基础认知。等进入“模式对齐”工序时再读取“核心模式”里的对应范式和“数据契约”里的对应定义。至于“依赖清单”和“质量红线”则在方案设计和交付自检这两个阶段按实际需要局部读取。这样做的好处是精准且省token。唯一的要求是细节文件本身的命名和内容组织必须高度结构化让AI能快速找到自己需要的那一段。我最终用的目录结构大致是这样的skill-project-assistant/ ├── SKILL.md ├── details/ │ ├── shared/ │ │ └── quality-red-line.md │ ├── service-api/ │ │ ├── overview.md │ │ ├── conventions.md │ │ ├── patterns-crud.md │ │ ├── patterns-query.md │ │ ├──> AI编程SKILL设计：框架+细节双层结构实战
我一直觉得给AI编程工具写SKILL很多人一开始就走偏了。要么把SKILL写成一个巨无霸式的单一提示词什么场景都想覆盖结果AI在具体项目里经常表现得像个只会背课文的学生——道理都懂一操作就乱要么反过来SKILL只写了几个抽象的原则细节全靠AI临场发挥那效果就跟开盲盒一样这次能用下次就废。这次我对SKILL做了一次全新的尝试把思路彻底调了个个儿。我把手头的两个核心工程 service-api 和 web-admin 全部拆成了“框架 细节”的双层结构。这个改动的核心逻辑是用SKILL定义一套固定的、可复用的思考框架和执行流程把项目里那些真正会变、需要因地制宜的具体信息全部下沉到独立的细节文件里。这样SKILL本身变得极其稳定而细节文件可以随时增删修改完全不碰SKILL主体。折腾完这一轮我最大的感受是这个方向的尝试值得。所以把这套设计思路、拆解过程、实测验证结果和踩过的坑完整记录下来给也在研究SKILL怎么落地的朋友一个参考。1. 为什么非要把 service-api 和 web-admin 拆成“框架细节”先说清楚这次拆分的背景。我这两个工程并不是玩具项目service-api 是一套完整的后端服务接口层web-admin 是配套的后台管理系统两者都经历过好几轮迭代代码量大、业务规则多、模块之间藕断丝连的地方也不少。在打算做SKILL之前我其实陷入过一段时间的纠结。市面上的SKILL大多聚焦在“单任务”上比如“帮我写一个Python脚本”“帮我分析这段日志”这类SKILL把上下文写成一段话就完事了。但面对 service-api 和 web-admin 这种体量的工程单任务式SKILL完全不适用。你需要的是一个能理解整个项目结构、知道代码规范、能按既有模式添加新接口或新页面的“项目级”AI助手。一开始我尝试过把整个项目的所有相关信息都塞进SKILL的指令文件里——项目结构、目录说明、编码规范、数据库表、接口返回格式、分页规则甚至异常处理方式。结果就是SKILL文件膨胀到了几千行AI每次读取要消耗大量上下文窗口而且文件越长AI越容易抓不住重点。更尴尬的是项目里任何细微的变动比如某个表新增了一个字段都得去改SKILL主文件时间一长SKILL本身就成了一个新的维护负担。这就像你给一个新同事写入职手册把“公司食堂在哪”“厕所怎么走”“Git提交规范”“数据库表结构”“前端组件库用法”全塞进一页纸里这不叫手册这叫字典。没人能靠一本字典快速上手工作AI也一样。所以这次我把结构彻底改了。核心思路就一句话SKILL只负责“怎么干活”细节文件负责“项目是什么样的”。框架层是一套通用的思考路径和执行步骤细节层是对 service-api 和 web-admin 两个项目各自的定制化描述。两者通过固定的文件命名约定和引用规则绑定互不污染。这种做法的直接好处有四个SKILL主文件保持精简和稳定不需要频繁修改换新项目时只需要重写细节文件框架可以原样复用AI的执行流程变得可预期因为它每次都走同一套思考路径细节文件和SKILL分离后非技术角色也能参与维护细节内容2. 框架层到底该放什么把“稳定的动作”抽象出来先讲框架层。这部分对应SKILL中相对固定的执行流程是整个拆分的骨架。我把框架层定义成了一套“动作序列”不绑定任何具体业务。无论你要在 service-api 里加一个查询接口还是在 web-admin 里新增一个列表页面都走同一套动作序列。2.1 框架层的五个固定工序我最终把框架层收敛成五个工序顺序固定缺一不可。这五个工序在设计时参考了一个有经验的开发者接到新需求后的真实工作路径先看全貌再定方案然后动手做完自查最后是交付说明。项目结构感知AI先读取整体目录结构和关键配置文件在头脑里重建这个项目的物理地图。没有这一步AI后续的所有操作都是盲人摸象。模式对齐从细节文件中找到“已有功能的代码示例”搞清楚这个项目里一个接口或一个页面通常是怎么写的遵循哪些约定。方案设计基于感知到的结构和模式先用自然语言描述需求要落在哪个模块、新增哪些文件、改动哪些地方。这一步强制AI“先想后做”避免一上来就疯狂生成代码。分步实现按照方案逐文件落地每完成一个文件都做一次局部验证。交付自检对照细节文件里的质量红线逐条过一遍比如是否处理了异常、是否符合命名规范、是否补充了必要注释。这五个工序里最关键的是第2步“模式对齐”。我给每个项目做SKILL的时候都会刻意在细节文件里留出“范例代码”的位置让AI先“抄”再“写”。这样生成的代码风格才能和原项目保持一致否则AI很容易写出一个功能没问题但画风完全不一样的模块。2.2 框架层的指令编写要点框架层本身就是一个标准的SKILL指令文件但我在这次重构里特意做了几个调整效果非常明显用流程指令替代结果指令。不说“完成XX功能”而是说“先读取目录结构再定位相关模块然后参照细节文件中的示例”把AI的注意力引导到过程上。给每个工序设定输出物。比如方案设计阶段必须输出一段简短的“改动影响说明”自检阶段必须输出“自检清单勾选结果”。有输出物AI就不容易偷工减料跳步骤。限制并行度。我在指令里明确要求AI“一次只处理一个模块完成后再进入下一个模块”效果立竿见影生成的代码质量立刻稳定下来。让AI一次性产出整个项目的代码大概率会顾此失彼。框架层稳定下来后真正吃功夫的地方就到了细节层。这是这次尝试里我认为最有价值、也是坑最多的部分。3. 细节层怎么搭service-api 和 web-admin 的定制化实践如果框架层是“道”那细节层就是“术”。同一个框架套上 service-api 的细节就是一个后端服务AI助手套上 web-admin 的细节就是一个前端管理后台AI助手。细节层质量直接决定了SKILL实际干活时靠不靠谱。3.1 细节文件的信息架构我给每个项目都建了一个独立的细节目录带版本号方便回溯放在SKILL的技能包目录下里面分了六个维度项目概览定位、技术栈、运行方式、目录结构说明编码规范命名规则、代码风格、文件组织约定核心模式典型接口/页面的实现范式附完整示例代码数据契约核心数据表、返回结构、通用字段定义依赖清单必须使用的组件库、工具函数、第三方服务比如各类API注意安全合规质量红线绝对不允许出现的写法、必须要处理的分支、上线前必查项这六个维度基本覆盖了“让AI写出符合项目气质的代码”所需的全部信息。但维度定下来只是第一步真正麻烦的是内容怎么组织AI读起来才高效。3.2 service-api 细节层的核心设计service-api 是FastAPI体系的后端工程我一直强调接口层的输出必须稳定可控。所以它的细节层里“数据契约”和“核心模式”是重头戏。数据契约里我明确写了全局统一返回结构列出了请求体、响应体的字段命名规则和类型映射方式。最关键的是我把项目中几个高频场景的完整参数示例直接贴了进去。比如列表查询接口需要包含分页参数、筛选条件、排序规则、返回总条数详情接口需要包含路径参数校验、不存在时抛什么异常、详情字段裁剪规则。这些内容都是直接从线上代码里扒出来整理进去的不是凭空编出来的。核心模式里放了三类范例一个标准CRUD接口的完整实现一个涉及多表联查的复杂接口的拆解过程还有一个定时任务入口的写法。为什么放这三个因为项目里新增需求绝大多数都落在这三类范畴。AI在写新代码时会不断回看这些范例代码画风自然就统一了。还有一点容易被忽略我在细节层里补充了“本地启动的最小配置说明”。AI在做代码生成时经常会自己脑补一些并不存在的配置项或环境变量明确告诉它项目实际怎么跑起来能显著减少这类幻觉。3.3 web-admin 细节层的个性化处理web-admin 是Vue3 TypeScript的后台管理前端它的细节层和 service-api 有完全不同的侧重点。后端接口层最重要的是数据契约前端管理后台最核心的则是页面模式。我花了很长时间整理web-admin的“核心模式”因为后台管理页面的重复度实在太高了——列表页、表单页、详情页、弹窗操作、状态切换每个都是同构的套路。我把这些套路分别整理成了标准范式并且在细节文件里写清楚列表页的统一搜索组件怎么用、表格列的render函数怎么处理枚举状态、表单校验的规则怎么声明、页面权限指令怎么绑定。细节层还专门放了一个“典型列表页完整代码”大概两百行属于这个项目里最有代表性的一个业务页面。之所以选它当范例是因为它同时覆盖了搜索、分页、表格列定制、操作按钮、权限控制、状态标签几乎所有的前端后台常见元素。AI只要读懂这一个页面写其他列表页基本就不会跑偏。我还在web-admin的细节层里额外加了一类内容“禁止做的事”。比如不能直接改全局状态管理文件来塞临时数据不能绕过封装好的请求实例直接调用底层HTTP客户端新增页面必须在路由配置里显式注册。这些规则在编码规范里其实零散写过但把它们集中成一条条明确禁令AI对边界的感知会清晰得多。4. 把“框架细节”绑定起来SKILL的装配与引用机制框架有了细节也有了接下来要解决的是“怎么让AI在干活时知道该用哪套细节”。这一步就是SKILL的装配与引用机制处理不好前面拆得再干净也会打折扣。4.1 用入口文件穿针引线我在SKILL指令文件里设计了一个“入口判断逻辑”放在执行流程的最前面。当AI接收到一个新需求时第一件事不是写代码而是判断这个需求发生在哪个工程——请求内容涉及接口、数据、服务逻辑就加载 service-api 的细节涉及页面、组件、路由、样式就加载 web-admin 的细节。如果两者都涉及按先接口后页面的顺序分两个阶段处理。入口文件里我还会用一段固定格式把这个判断过程显式输出比如“本次需求作用于service-api将加载项目细节版本 v2.1”。这么做看似多余但实际用起来有个好处如果AI判断错了场景你可以在它动手前一眼看出来及时纠正。这也算是一个低成本的人机校验环节。4.2 细节文件的引用粒度细节文件不是让AI一口气全读一遍。所有细节都放出来上下文窗口爆炸不说AI还会迷失重点。我采取的是“按需拉取”的方式入口判断命中项目后AI只读取“项目概览”和“编码规范”建立基础认知。等进入“模式对齐”工序时再读取“核心模式”里的对应范式和“数据契约”里的对应定义。至于“依赖清单”和“质量红线”则在方案设计和交付自检这两个阶段按实际需要局部读取。这样做的好处是精准且省token。唯一的要求是细节文件本身的命名和内容组织必须高度结构化让AI能快速找到自己需要的那一段。我最终用的目录结构大致是这样的skill-project-assistant/ ├── SKILL.md ├── details/ │ ├── shared/ │ │ └── quality-red-line.md │ ├── service-api/ │ │ ├── overview.md │ │ ├── conventions.md │ │ ├── patterns-crud.md │ │ ├── patterns-query.md │ │ ├──>