1. 先搞清楚官方库和私人文件夹到底差在哪这句话说出来可能有点得罪人但我还是要说Anthropic 官方库里的 skills平均质量真的没有很多人想象中那么高。我自己前前后后把官方库翻过几遍也在 Claude Code 里实际用了一段时间结论是——它更像一个入门演示集解决的是让大家知道 skills 大概长什么样这个层面的问题。真要放到自己的日常开发流里那些官方技能往往有种什么都沾一点但什么都不够顶用的感觉。而我自己那个从零攒起来的私人 skills 文件夹一共也就十来个技能但它解决的都是我在真实项目里反复遇到的痛。比如我每天都要处理的前端页面复刻、接口联调时的数据结构分析、写单元测试时的边界场景枚举——这些活我用私人 skills 处理效率比裸奔或者是硬套官方技能高出一大截。为什么会这样我琢磨了很久最后想明白了一个很朴素的道理**官方库是给所有人用的而私人文件夹是给我用的。**这两个定位从根上就决定了它们的设计思路完全不一样。1.1 官方库的天然短板Anthropic 官方库的定位是覆盖尽可能多的通用场景所以它的技能设计偏保守、偏通用参数也往往很多因为要照顾各种不同的用法。这就带来一个特别现实的问题一个技能里面的 prompt 越长模型被带偏的概率就越高。官方技能为了追求通用性会把很多场景条件、分支逻辑都写进提示词里结果就是真正执行的时候模型经常该抓的重点没抓住不该有的多余动作倒是一大堆。我在官方库那段经历里踩过最典型的一个坑是用官方那个 web 开发相关的技能去生成一个营销落地页。技能本身确实能跑起来但生成的页面框架感特别重——很像一个按照教程教的写法写出来的项目而不是一个老前端自然而然会写出来的东西。它缺少我对真实业务的理解比如转化率优先的视觉层级、首屏加载性能的基本约束、还有那些只有踩过坑才知道要避免的布局陷阱。这些 know-how 不是一个官方通用技能能覆盖的它只能靠你自己在日常开发里沉淀。1.2 私人文件夹的核心优势——上下文即权力再说回私人文件夹。这是我在实际使用中最强烈的一个感受一个 skills 文件夹本质上就是一个上下文资产的沉淀池。你每往里面加一个技能本质上是把你的某一部分经验、标准、偏好固化成了一段可复用的提示词资产。这跟写代码时沉淀工具函数是一样的逻辑——不要每次重新造轮子而是把轮子存起来下次直接用。拿我最常用的几个私人技能来说它们的写法跟官方库完全不同官方技能会写请帮助用户完成 web 开发任务这种高度抽象的描述。我的私人技能会写当用户要求把一个设计稿图片还原成前端页面时先分析设计稿的布局结构——栅格、间距、色彩系统再输出一个完整实现并且默认使用我的技术栈和代码风格。这个差异在 AI 的世界里是决定性的。Claude 这类大模型的推理质量高度依赖 prompt 的上下文清晰度——越明确、越贴合具体场景的指示生成质量越高。这跟人一样你说帮我处理一下图片和帮我把这张 1200 宽的产品主图压缩到 800 宽以内的 JPEG保持背景透明——后者得到的响应质量完全不一样。所以在我看来私人 skills 文件夹能干过官方库靠的不是什么黑魔法而是上下文密度和场景贴合度的降维打击。2. 私人 skills 文件夹的架构与设计思路说完了理念层面的东西我们来点实际可操作的。很多人一开始搞 skills容易掉进一个陷阱拼命去看别人分享的 skills 清单今天看到这个推荐就装一个明天看到那个推荐就加一个最后文件夹里堆了三四十个技能真正常用的没几个还占用了大量的上下文空间。我自己的经验是skills 文件夹应该遵循小而精、按需沉淀的原则。与其追求数量不如认真打磨那几个真正高频使用的技能。下面我详细拆解一下我自己这个文件夹的架构方式你可以直接参考。2.1 目录结构设计——按使用频率与场景分层我把私人 skills 文件夹分成了三个层级这个分法是从实际使用频率出发的第一层通用但高频。这一类是每天都会用的比如代码审查、单元测试生成、git commit 信息规范化。它们的特征是跨项目复用跟具体技术栈没什么关系。放在最外层方便直接加载。第二层特定技术栈类。这一类跟着项目走比如React 组件开发、Tailwind 样式调试、Python 数据处理。这类技能我会写得更具体直接把我惯用的技术方案、依赖库、代码组织风格写进去所以它们特别适合复用。第三层任务性一次性。比如把设计稿转成前端页面、分析这段 JSON 数据并生成接口文档。这类技能往往跟某个具体项目绑定任务做完之后过一段可能就失效了。所以我一般会为它们单独开一个projects子目录避免污染主目录。三层之间的转移原则也很简单一个任务类技能如果做完了第二次、第三次说明它其实是高频任务那就升级到技术栈类如果一个技术栈类技能连续两个月没碰过果断删掉或者归档。这个原则保证我的文件夹永远保持精简不会沦为收藏夹吃灰。2.2 命名规范与元数据——别让 AI 看不懂你的技能skills 文件夹的第二个关键点在于命名和元数据。我见过太多人把技能文件命名为my_skill.md或者test.md这种名字在 AI 读取的时候基本就是灾难。因为它无法让模型从文件名里推断出这个技能是干什么的进而导致加载判断出错——要么该用的技能没被加载要么不该用的技能反而被激活了。我采用的命名规范是动词 对象 场景generate_unit_test.md review_pr_code.md convert_design_to_frontend.md debug_tailwind_layout.md这种命名方式的优势在于当模型扫描文件夹时它能在几十个文件里快速找到与当前任务匹配的技能。而且文件名本身就像是技能的标题即使没有打开正文模型也能大致推断出这个技能的适用范围。再来说元数据。每一个技能文件的头部我都会写清楚name: 技能名称简短description: 一句话描述包含触发条件和适用场景when_to_use: 明确告诉模型什么情况下使用这个技能when_not_to_use: 明确告诉模型什么情况下不要用这个技能这个when_not_to_use是我踩了很多坑之后才加上的。一开始我不写这个字段结果经常出现模型在错误的任务上套用了技能——比如明明是让我写一个移动端的适配方案结果模型却加载了React 组件开发的技能输出了桌面版的布局代码。加了when_not_to_use之后这个误触发的情况大大减少。2.3 技术栈映射表——让技能与真实项目精准对接这个是我私人文件夹里比较特殊的一个设计我觉得非常有价值。我会在 skills 文件夹的根目录放一个stack-map.md文件里面记录了我常用的技术栈对应关系# 技术栈映射表 ## 前端 - 框架: Vue 3 TypeScript Vite - UI: Naive UI - 样式: TailwindCSS CSS Modules - 状态管理: Pinia - 请求库: Axios - 路由: Vue Router ## 后端 - 语言: Node.js (TypeScript) - 框架: NestJS - ORM: Prisma - 数据库: PostgreSQL - 缓存: Redis ## 测试 - 框架: Vitest - 断言: Jest DOM - 端到端: Playwright这个文件的妙处在于它是我所有私人技能的基础设施。每一个技能在执行的时候都会读取这个文件来校准自己的输出风格。比如generate_unit_test.md这个技能它会先读取 stack-map知道项目是用 Vitest 而不是 Jest然后生成的测试代码就直接对标 Vitest 的写法不需要我每次在 prompt 里手动指定。这个体验一旦适应了真的回不去官方库那种什么都要问一遍的状态。3. 手工打磨核心技能的完整过程思路讲完了下面我以一个具体的案例完整演示一下我是怎么从零手工打磨一个能直接提升开发效率的技能的。这个例子是把设计稿还原成前端页面的技能也就是热搜词里提到的图片还原设计稿给前端开发。这个技能的产生背景很直接——我经常需要把产品经理或者设计师给的设计稿图片还原成可用的前端页面。以前没有技能的时候我需要做一大堆操作先把图片下载下来、肉眼分析布局结构、构思组件拆分方案、最后再开始写代码。这个过程既慢又容易出错且每次都是重复劳动。所以后来我决定把它固化成技能。3.1 挑选痛点场景——先问自己三个问题并不是所有任务都值得做成 skill。在动手之前我会先问自己三个问题这个任务的频率够不够高如果一个月才做一次做成 skill 的性价比不高。这个任务的标准化程度够不够高如果每次的做法都完全不一样那 skill 只能提供一个非常泛化的框架帮助有限。这个任务能不能明确描述如果你自己都说不清怎么做好这件事那也别指望能用一段 prompt 把它固化下来。设计稿还原这个任务三个问题的答案都是肯定的频率高、标准化程度高都是从图到代码、而且我很清楚一个好的还原应该有哪些步骤。所以它特别适合做成 skill。3.2 编写 SKILL.md 的核心要素——把隐形经验显性化确定了场景之后下一步就是真正的编写过程。这是一件充满了经验显性化微妙之处的工作。我自己习惯用的模板结构大概是这样的--- name: convert_design_to_frontend description: 将设计稿图片转换成高质量的前端页面实现适配桌面端和移动端。 when_to_use: 用户提供设计稿图片PNG、JPG、Figma导出图等并要求实现为页面时。 when_not_to_use: 用户只是要求修改现有页面的某个局部样式不需要从零实现。 --- # 设计稿还原工具 ## 1. 分析阶段 - 识别设计稿的**整体布局结构**是单栏还是多栏有没有侧边栏内容区域如何划分 - 提取设计稿的**色彩系统**背景色、文字色、主色、辅助色整理成 CSS 变量。 - 提取设计稿的**字体与字号**标题、正文、辅助文字的字体族、字号、字重。 - 提取设计稿的**间距规则**观察不同元素之间的距离规律推断栅格系统。 ## 2. 组件拆分阶段 - 将页面拆解为组件树结构标注每个组件的职责与数据来源。 - 标识出可复用的公共组件如按钮、卡片、输入框。 - 识别出需要响应式处理的断点位置。 ## 3. 实现阶段 - 读取根目录的 stack-map.md按照技术栈偏好生成代码。 - 样式方案优先使用 CSS 变量统一管理颜色与间距。 - 布局实现优先使用 Flexbox 或 Grid减少使用绝对定位。 - 实现完成后检查边框圆角、阴影、渐变等视觉细节是否与设计稿一致。 ## 4. 自我检查清单 - [ ] 所有颜色值是否已提取为 CSS 变量 - [ ] 页面在 320px、768px、1440px 宽度下是否正常显示 - [ ] 字体加载是否使用了合适的 fallback - [ ] 是否存在无用的重复样式代码这里有一个很重要的创作原则不要只写做什么要写怎么做和按什么标准做。官方的很多技能恰恰败在这一环——它们会告诉你生成一个页面但不会告诉你应该在分析布局之前先提取色彩系统这种具体的执行顺序。而正是这些执行顺序和执行标准才是一个技能真正有价值的核心。3.3 写一个好的 prompt 模板——把经验融入模板技能里除了步骤之外还需要一个 prompt 模板。这个模板是给模型在真正执行任务时做参照的。我的经验是模板里面最好预填一些好的做法提示词让模型在高频场景下直接走正确的路径。例如在设计稿还原技能的 prompt 模板里我会写注意在分析设计稿时重点关注对齐关系和间距规律这两者是还原度的核心。如果设计稿中含有交互态如 hover、active、focus必须在实现中完整还原。页面性能方面首屏图片需要加上 loading 属性非首屏图片要使用懒加载。这种模板的价值在于它把那些你以为模型应该知道但它其实不知道的东西显式写了出来。比如间距规律——一个没受过训练的大模型看到设计稿之后大概率会照着像素值一比一还原但那样做出来的页面往往非常古怪因为真实的间距是有节奏和规律的。你在模板里点明这一点模型输出质量会瞬间上一个台阶。3.4 迭代与测试——技能是活的不是死的技能写完了并不代表工作结束真正的打磨才开始。我自己的习惯是每个新技能在第一个月内至少迭代三到五轮。每一次实际使用后我都会回到 SKILL.md 里去修补那些模型没有按预期执行的环节。具体怎么发现哪里需要修补我的方法特别朴素就是每次用完之后回看一次生成的代码或结果凡是发现有不够满意的地方就倒推如果我在技能里多写一句什么样的提示词这次结果是不是就能更好如果是那就把这一句加进 SKILL.md。这样反复迭代之后技能的质量会越来越稳定最终进入输入即输出最佳结果的良性状态。举个真实的例子。第一版设计稿还原技能跑出来时我发现模型总是把字体大小直接写成设计稿上的像素值而没有考虑不同屏幕的缩放。于是我在技能实现阶段加了一句字号大小建议使用 clamp() 函数实现响应式缩放。第二版跑出来就好多了。这个加一句的过程就是技能质量不断爬升的引擎。4. 常见问题与排查技巧实录这节写给那些已经动手或者准备动手搞自己 skills 文件夹的朋友。下面这些问题是我在过去几个月的实操中真实踩过的坑每条都有具体的排查思路和解决方案。4.1 技能生效不稳定同一个技能有时灵有时不灵这是最初级的坑也是最让人头大的。明明同一个技能同一个任务有时候效果惊人有时候乱七八糟。排查下来你会发现问题大概率不出在技能文件本身而在于触发条件写得不够清晰。模型加载技能的逻辑是根据用户描述与技能 description 的语义匹配度决定是否激活。如果你的 description 写得太宽泛比如帮助用户进行前端开发那么模型在遇到各种看起来沾边但不尽相同的任务时都可能误触发也可能因为描述不够具体而错过触发。解决方案是把 description 写得更精确同时配合 when_to_use 和 when_not_to_use 双向校准。4.2 上下文膨胀技能加载太多反而拖慢速度这是技能爱好者最容易犯的毛病。技能越多每次会话要携带的基础上下文就越多这带来的直接后果是模型响应变慢而且因为上下文里塞了太多无关技能的描述推理质量还会下降。我自己的解决方案是把 skills 分成默认加载和按需加载两组。默认加载的只有三四个——那些我每个任务都会用到的基础技能。其余的一律不写进默认加载列表而是在真正需要的时候通过明确的指令让模型去读取相应的技能文件。这样既保证了高频技能的稳定生效又避免了上下文被无谓的膨胀拖垮。4.3 技术栈冲突技能按自己的偏好写跟项目实际不符这个问题在我早期也踩过。比如我做generate_unit_test技能的时候一开始直接用 Jest 写模板。结果后来接了一个用 Vitest 的项目生成的测试代码就全废了。排查发现技能里写死了 Jest 的接口而项目实际用的是 Vitest。后来我引入了前面说的 stack-map.md把技术栈从技能里解耦出来。技能模板统一使用按 stack-map 读取项目技术栈并生成对应代码的占位逻辑。这样同一个技能就能适配不同的项目通用性大幅提升。4.4 技能文件太长系统反而消化不良这是很多人容易忽略的一个点。技能文件不是越长越好。长度越长模型在处理时消耗的注意力就越多反而可能让核心指令的执行效果变弱。我个人的经验标准是一个技能文件的正文最好控制在 300 到 600 行之间。超过这个范围要么说明你试图用一个技能覆盖了太多场景应该拆分要么说明你写了太多冗余的解释应该精简。真正核心的执行指令应该集中在前面 100 行内后面的部分可以作为参考示例、边界情况说明等辅助信息这样既不影响核心指令的注意力又能给模型提供足够的背景支持。4.5 版本管理与同步私人文件夹不是一次写完就完事最后一条是关于工程化管理的。技能文件说到底也是代码是代码就应该纳入版本管理。我自己是把整个文件夹放在 Git 仓库里管理的每次修改都走一次 commit。这样做的直接好处是当某一次修改让技能质量不升反降的时候我能随时回退到前一个可用版本。另外我还会在每次大幅修改之后写一个简短的 changelog记录这次改了什么、为什么改。这习惯听起来有点过度工程但当你某天突然发现自己把一个本来好用的技能改废了、却忘了之前是怎么写的时你就知道这个习惯有多救命了。5. 扩展思路从私人文件夹到团队共享技能库吃完自己的螃蟹之后我自然而然想到了下一步既然私人 skills 能秒杀官方库那如果我把公司团队里所有前端工程师的私人技能聚合起来做一个团队共享技能库是不是效果也会很好这部分我确实实践过一阵子进展和踩坑都有这里分享一些观察。5.1 团队技能库与个人技能库的核心差异个人技能库的特点是为自己量身定制而团队技能库的难点在于每个人的工作习惯和偏好都不一样。如果直接拿某一个人的私人技能去给整个团队共用效果往往会打折扣。因为你觉得重要的点别人可能完全无感你惯用的代码风格别人可能觉得别扭。所以团队技能库更适合的形式是一个公共基础层加上每个人自己的私有个性层。公共基础层里放的是团队统一的标准——比如代码风格规范、提交信息规范、代码审查清单。私有个性层里放的是个人的偏好和技巧。模型在执行任务时先加载公共基础层再根据当前使用者的身份叠加私有个性层。这样既能保证团队标准的统一又不牺牲个人效率的灵活性。5.2 团队技能库建设的三个关键动作如果你想在团队里搞技能库我建议先做这三件事第一建立一个技能评审机制。每个技能在合并进公共层之前必须经过至少两个人的实际试用和评审把我觉得好用变成我们觉得好用。这个过程能过滤掉大量个人风格的噪音。第二明确技能的更新责任人。没有责任人的技能库三个月后大概率就变成一堆没人维护的死文件。每一个核心技能都得有明确的 owner负责定期维护、问题修复、版本更新。第三周期性地做一次技能清理。每两个月检查一次所有技能的激活率——哪些技能一直在被使用哪些自从加进来就没人碰过。激活率为零的技能直接删掉或归档绝不手软。这跟代码库里的死代码清理是一个道理清理过后整个库的质量和效率都会有明显提升。最后分享一个小技巧我个人在实际操作中体会最深的一点skills 文件夹不是用来收藏的用来迭代才有价值。技能的价值不在于创建那一刻的完美而在于每一次使用之后你怎么修补它。我把这个当作副产品来理解——就像写代码里最重要的不是代码本身而是你从每次调试里学到的东西。Skills 的迭代过程本质上就是你把自己对 AI 协作的理解不断地显性化、固化下来的过程。所以如果你也想开始建设自己的 skills 文件夹我的建议非常简单别等完美先从一个你明天就会用到的任务开始写一个粗糙但能用的版本然后实际用起来边用边改。十来个这样的迭代下来你再回头用官方库会有种从自己家精致的厨房走进大食堂的感觉——功能都有但味道终究差了那么点意思。祝大家都能折腾出属于自己的那个碾压官方库的私人文件夹。