我一直觉得拿 Claude 或 Cursor 这种工具只用来聊聊天、问问代码有点浪费。刚上手那阵子我也和大多数人一样在对话框里问一句、等一句AI 答得再漂亮回头还得自己逐段改、逐段接本质上只是把搜索引擎换了个更会说话的样子并没有真的改变干活的方式。真正让我从“会聊天”变成“能交付”的是发现了 Skills 这套机制——它相当于给 AI 发了一本岗位手册告诉它你在这个项目里是什么角色、按什么流程干活、最终要交什么东西。把常用的 8 个 Skills 整理成固定工具箱之后我整个工作流几乎重写了一遍需求拆解、代码审查、结构图生成、文档输出、安全自查、日志排障每一个环节都不用我再对着 AI 反复解释背景和约束。这篇文章就把我这半年经常在用的 8 个 Claude/Cursor Skills 逐个拆开讲清楚每个解决什么问题、底层是怎么运作的、我实际怎么用以及自己动手写 Skill 时踩过的坑。无论你是在用 Claude Code 还是 Cursor或者正准备入坑 Skills都应该能从里面找到点能直接拿走用的东西。1. 为什么需要 Skill给 AI 一张明确的“岗位说明书”先说一个我观察到的现象。很多人抱怨 AI 写代码“看着对一跑就废”或者改需求时答非所问总觉得 AI 笨。但多数时候问题不在模型本身而在你给它的上下文太少了。你只丢给它一个函数、一段报错它就像一个临时被拉来顶班的实习生既不知道项目背景也不知道现有代码规范更不知道你想要的交付物长什么样只能凭通用知识硬答。结果就是每次都给你一个“看起来合理但接不上项目现状”的方案。Skill 这个机制就是专门解决这个问题的。它不改变模型本身的能力而是改变模型在进入项目时的“初始状态”。一个 Skill 本质上是一个放在特定目录下的文件夹里面有一个SKILL.md文件用 Markdown 写清楚这个“技能”的触发条件、执行步骤、输出格式和注意事项。AI 读取这个文件之后就相当于是“入职培训”过了知道自己在这个项目里到底该干什么。我经常打一个比方没有 Skills 的 Claude/Cursor是一个很聪明但没有行业手册的新人有了 Skills新人手里多了一本《XX 公司 XX 岗位工作手册》遇到什么情况翻哪一章、产出物按什么模板写、哪些红线不能碰全部写清楚了。你不需要每次对话都用几百字重新交代一遍。而且 Skill 和普通 Prompt 最大的区别在于Prompt 是一次性的这次说清楚了下次打开新会话又得从头说Skill 是结构化的、可复用的资产写好一次可以在任意项目里反复调用也可以分享给团队其他人。它把“你个人积累的行业经验”沉淀成了“项目里的固定资产”。这一点对我的吸引力非常大因为我最烦的就是同一件事翻来覆去地讲。当然Skill 也不是银弹。它解决的是“AI 知道该按什么流程干活”的问题解决不了“你的需求本身没想清楚”的问题。如果你的需求是模糊的Skill 再完善也只能在模糊的地基上盖房子。所以真正用好的姿势是先靠 Skill 把 AI 从一个零背景的实习生变成一个有手册的熟手再靠你自己的判断力去控制目标。接下来的内容就是围绕这 8 个 Skill 具体怎么做到这一步展开的。2. 动手前的准备Claude Code 和 Cursor 里加载 Skill 的正确姿势很多人在网上看到别人分享 Skill 配置第一反应是“好牛我也要装”结果装完发现 AI 完全不理会或者报了一堆错。其实大部分安装问题都出在同一个地方放错目录或者描述信息写得不到位。这里把我验证过的目录规则和排查思路统一说一遍。2.1 目录结构全局和项目级要分清先说 Claude Code。它读取 Skill 的位置主要是两个项目级项目根目录下的.skills/文件夹里面每个子文件夹代表一个 Skill每个子文件夹里必须有一个SKILL.md。全局级用户目录下的~/.claude/skills/放进去之后在任何项目里都能用适合放那些和具体业务无关的通用技能。Cursor 的情况类似。较新版本已经支持读取项目根目录的.skills/文件夹目录结构和 Claude Code 完全一致。所以你在 Claude Code 里写的 Skill拷贝到 Cursor 项目里通常也能直接用反过来也一样。这是一个很友好的设计意味着你不需要为两个工具各维护一套技能库。目录结构长这样.skills/ task-breakdown/ SKILL.md code-review/ SKILL.md doc-writer/ SKILL.md每一个 Skill 文件夹里SKILL.md是主文件也可以带上references/子目录放参考资料、模板文件之类的补充内容。主文件必须存在否则 AI 不会认为这是一个 Skill。2.2 SKILL.md 的格式要点frontmatter 是命门SKILL.md和其他 Markdown 文件最大的不同在于文件开头有一个 YAML frontmatter里面至少要有name和description两个字段。其中description尤其关键因为 AI 不是每一次对话都会主动把所有 Skill 读一遍而是根据你当前的请求内容结合description来判断“这次该不该用这个技能”。我见过很多 Skill 不生效的案例七成是因为description写得太宽泛比如“用于代码开发”那模型根本不知道什么时候触发还有三成是写得太具体把调用场景限定死了结果换个说法问就触不到了。description的正确写法是明确在什么场景下、遇到什么类型的问题时使用写清楚输入是什么、输出是什么。一个相对合理的示例长这样--- name: code-review description: 在完成代码修改、提交 PR 或合并分支之前对代码变更进行审查。适用于代码规范检查、潜在 bug 定位、安全隐患识别等场景。输入是待审查的代码或 diff输出是带严重级别标注的问题清单和修改建议。 ---正文部分我习惯按下面几个维度组织角色设定你是谁、按什么标准工作。工作流程从输入到输出的固定步骤。输出模板要求模型按什么格式输出。经验规则那些不说清楚模型就容易踩的坑。2.3 安装 Claude Code 时最常见的报错热词里有一个出现频率特别高的报错“claude : 无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称。”这个在 Windows 上很常见本质就是 npm 全局包的安装目录不在 PATH 环境变量里。解决办法有两个一是重新打开终端很多情况下新装完 npm 包PATH 不会自动刷新重开终端就好了二是在系统环境变量里手动把 npm 的全局 bin 目录加进去通常是C:\Users\你的用户名\AppData\Roaming\npm。如果加了还不行检查一下 Node.js 版本尽量保持在官方支持的最新 LTS 版本。从这里开始环境就算准备好了。接下来的内容更实用我把 8 个 Skill 分成两组先讲偏管理和文档的 4 个再讲偏工程和排查的 4 个每个都按“解决什么问题 关键配置 我的使用心得”来讲。3. 先用起来4 个让交付更省心的管理型 Skill3.1 task-breakdown把“做个后台系统”拆成能落地的任务清单这个 Skill 是我每个新项目启动时第一个用的没有之一。它的核心作用是把一句模糊的需求比如“给内部做一个工单管理后台”拆成一份带优先级、依赖关系、验收标准的任务清单。没有这个 Skill 之前我经常犯的错是拿到需求直接让 Claude 写代码结果写到一半发现表结构不对、角色权限没想清楚返工成本极高。有了 task-breakdown 之后流程变成先拆任务、对齐方案再进入编码。这个 Skill 的SKILL.md里我写了几个固定要求必须输出用户故事、必须标注上下游依赖、必须给每个任务写“完成的定义”、必须把不确定的点单独列成“待确认问题”。用了这半年最大的感受是它的价值不在“生成任务列表”本身而在于逼着我在动手之前把模糊的东西讲清楚。AI 只是把你脑子里的想法结构化但它会追问你没想到的问题这其实是免费的思维教练。3.2 diagram-gen用文本描述生成结构图不再手动画 PPT网上一搜“结构图 skills”能找到不少相关资源因为画图这件事对很多人来说比写代码还痛苦。diagram-gen 这个 Skill 的作用就是让 AI 读代码生成一张描述当前系统架构、模块依赖、调用关系或者数据库关系的文本化图定义。它解决的是项目交接和方案评审时的老大难问题。代码一堆摆在那里新同事接手根本不知道从哪里看起方案评审时口头讲半天不如一张图直观。diagram-gen 能自动把散落在各个模块里的关系提取出来按结构化的图定义格式输出复制到支持在线渲染的编辑器里就能生成图。我对它的配置要求里有一行重要约束画图之前必须先读指定目录的代码不能凭空猜结构。实际用下来它对中小型项目的架构还原比较准项目特别大时会有“画得太粗”或者“关系判断错误”的情况。我的经验是拿它当第一版草图自己核对关键链路再手动调整细节效率依然比纯手动画图快得多。3.3 doc-writer从“不想写文档”到“文档被迫交出来”文档这个东西大家都知道重要但真的没几个人愿意写。doc-writer 这个 Skill 就是为了对抗这件事存在的。它专门负责根据代码和变更记录生成 README、API 文档、变更日志、接口说明等各类技术文档。这个 Skill 我一开始觉得没必要因为让 AI 写文档很多人都会但后来发现普通 Prompt 写出来的文档和 Skill 驱动写出来的文档差距很大。普通 Prompt 写文档AI 经常写得像“产品说明书”满篇正确的废话而 doc-writer 里我固定了输出模板必须写清楚“这个模块解决什么问题、在什么场景下使用、核心数据结构长什么样、有哪些坑”。另一个关键约束是文档必须基于代码事实不能凭空补全。我会在 Skill 里要求它先列出引用到的文件和函数再写正文这样至少能保证每个结论都有出处。我现在几乎所有项目的 README 首版都是它生成的省下来的时间足够我去刷两集剧。3.4 research-summarizer把“翻一堆资料”压缩成“读一份笔记”第四个管理型 Skill 叫 research-summarizer专门用于技术调研、方案选型和信息整理。它的触发场景是当我面对一个陌生技术、需要调研几个方案做对比、或者要快速了解一篇论文 / 一个开源项目时让 AI 去读资料然后按固定结构输出决策笔记。这个 Skill 的产出物不是“摘要”而是“决策笔记”。我要求的输出结构包括这个方案解决了什么问题、核心原理是什么、和同类方案的差异点在哪里、适用的边界条件、推荐的验证路径。这些字段都是我实际做技术选型时会问自己的问题把它们固定下来之后AI 产出物的质量就稳定了。这里一个很重要的心得是Skill 可以把“好问题”沉淀成“固定模板”。技术调研这件事高手和新手差的不是搜索能力而是脑子里那套提问框架。把框架写进 Skill相当于把你的判断力复制给 AI这个思路适用于几乎所有知识型工作。4. 再挖深一层4 个研发一线最能打的工程型 Skill4.1 code-review合并代码前多一双“不偷懒的眼睛”code-review 是我所有 Skill 里使用频率最高的。说实话人看自己的代码容易产生“我写的肯定没问题”的错觉而且看多了会疲劳。这个 Skill 的作用就是让 AI 以一个独立审查者的身份对代码 diff 做逐行检查重点盯逻辑错误、边界情况、安全问题、性能隐患、风格不一致。制作这个 Skill 时我特别注意一点必须让 AI 先复述它理解的变更意图再给出审查意见。这个设计和很多人想的不一样我解释一下原理如果 AI 上来就找问题它会把所有它看不太懂的写法都标成“问题”产生大量噪音但让它先复述意图它就不得不先理解上下文然后再判断这个实现方式是否真的满足意图。这一步看起来多余实际上大幅提高了审查意见的准确率。还有一点审查意见一定要带严重级别和修改建议不能只报问题不给方案。我在SKILL.md里把严重级别分成了阻断、主要、次要、建议四档合入前必须解决前两档。有了这个约束审查结果才能真正拿来当合入依据。4.2 frontend-factory前端页面从“思路”到“组件”的加速器网上关于“前端开发 skills”的讨论特别多因为前端改动视觉效果直观最容易感受到 AI 带来的效率提升。我用的是一个叫 frontend-factory 的 Skill专攻前端页面的开发和改动。它的触发范围包括根据设计稿描述写页面、按设计系统规范调整现有组件、把响应式布局的常见问题一次修完。这个 Skill 里写死了几个规则优先使用项目已有的组件库和样式变量不能私自发明一套新风格Tailwind 类名和自定义样式混用时要注明理由移动端断点必须覆盖。这些规则听起来不复杂但你不写进 SkillAI 每次都会用自己熟悉的方式写结果就是页面“能用但完全不像你项目的东西”。实际使用中的一个比较反直觉的经验是给 AI 看设计图不如给它看“现成的目标代码示例”效果来得好。因为模型天生擅长模仿代码结构而不是从像素生成代码。所以我会在 Skill 的 references 目录里放一个“参考组件示例”文件每次让它改页面时先参考这个示例的写代码。这样统一风格这件事就不需要每次人工强调了。4.3 security-audit只做防御性自查不碰任何越界行为这个 Skill 我需要先强调一句边界security-audit 只用于检查你自己有权限的代码项目目的是发现并修复安全问题绝对不应该被用来扫描或攻击任何你没有授权的目标。这一点写在我的 Skill 的第一行选型时也要避开那些打着“渗透测试”旗号但实际诱导工具做越界行为的第三方 Skill。它在实际工作中的价值非常具体检查代码里有没有硬编码的密钥检查接口有没有未授权的访问路径检查 SQL 拼接处有没有注入风险检查依赖版本里有没有已知漏洞检查前端有没有把敏感信息直接暴露在响应里。它不会去做什么特别的“攻击演示”就是把常见的安全隐患按清单排查一遍输出结论和为修复建议。我给这个 Skill 设定的输出是一个“安全自查报告”会按风险等级列出问题、影响面、修复建议。安全这个东西很多时候不是你写代码时故意不写好而是根本没想到那层。这个 Skill 的价值就是补上那层思考在合入前把它挡掉。我自己在项目上线前跑一遍心里会踏实很多。4.4 debug-detective从“反复试错”变成“按图索骥”最后一个工程型 Skill是定位线上问题和本地报错用的。它的设计初衷是很多人在排错时毫无章法看到报错就直接换个写法试一次十有八九越试越乱。debug-detective 会让 AI 按一套固定的排查流程走先复现问题、再还原日志链路、再定位可疑代码、再输出根因假设和验证方案。这个 Skill 里我最得意的一条规则是禁止 AI 在没有完整日志的情况下直接给修改建议。很多人用 AI 排错贴三行报错就让它改代码这在模型那里几乎必然会给出“看起来对但根本不解决问题”的建议。要求它先列出已经收集到的关键证据然后指出还缺少哪块信息最后才允许给出假设虽然多花了一点时间但方案的准确率高了一截。它还有一个很实用的点处理完问题之后会生成一份“排错复盘”把这个坑的根因、表象、排查路径记录下来。日积月累项目里相当于多了一本自己的排错手册。下次再遇到类似问题直接搜复盘文档就能定位不用重新走一遍排查流程。5. 把 8 个 Skill 串成工作流一个真实项目的跑法刚接触 Skills 的时候我容易犯一个毛病一次把所有 Skill 全丢给 AI让它“自己看着办”结果 AI 反而不知道该干什么。后来我意识到Skill 的正确用法不是全部怼上去而是像工具箱一样按需拿出来。这里用一个我最近实际做的内部项目来演示一个带前端页面、后端接口和数据库表的工具系统改版。阶段一启动对齐。我先用 task-breakdown 把客户给的模糊需求拆成任务清单。因为我心里清楚这个阶段的核心诉求不是“让 AI 帮我写代码”而是“让需求变得可执行”。这次拆完清单之后AI 列出来三个我一开始没想到的待确认问题比如旧的权限模型要不要兼容、历史数据怎么迁移。带着这几个问题去找业务方对齐比自己蒙头开工稳妥太多。阶段二方案调研。清单里有一个技术点我们没接触过涉及文件解析。这时候用 research-summarizer让 AI 对比几种主流的解析方案输出侧重点在不同库的适用边界和性能表现。这里我不要求它出“完整教程”只要决策笔记拿到笔记之后我自己只花了半小时就定了方案。阶段三编码实现。前端页面方面用 frontend-factory 按照项目里既有的组件规范批量生成页面后端接口和数据层的部分则配合 code-review 并行跑。并行这里有个技巧每完成一个小模块就切到 code-review 过一遍不要等全部写完再审。提前发现问题比事后返工省得多。阶段四文档与上线。功能和代码都稳定之后用 doc-writer 生成接口文档和变更日志上线前跑一遍 security-audit扫出来一处日志里打印了用户手机号的隐患当场修掉最后用 diagram-gen 生成新版本的模块关系图放到团队文档里方便后续维护。这个流程走下来最大的变化不是“省了时间”是我不用再时刻盯着 AI 做每一步因为它每一步都知道该输出什么、按什么标准做。Skill 真正的价值在这里它把“你管好每件事”变成了“你定好规则AI 按规则执行”。6. 自建 Skill 的 6 个坑我从踩坑里总结的检查清单讲了这么多最后回到自建 Skill 这个件事上。很多人看了前面几个 Skill 的示例之后第一反应是“我也要自己写”。我很支持因为最懂你工作流的人只有你自己。但自建 Skill 这件事坑不少。我把踩过的坑浓缩成 6 条你可以当检查清单用。第一个坑description 写得太宽泛或太狭窄。太宽泛会导致 AI 经常误触发什么请求都套这个技能太狭窄会导致换一种说法就不触发。我的建议是写完 description 之后自己念三遍如果改成口语化表达AI 还能不能判断出该不该用判断不了就再改。第二个坑SKILL.md 越长越好。这个想法很危险。AI 的上下文长度有限你拉一篇 5000 字的手册进去真正执行核心任务的空间就被压缩了。我后来把详细参考资料全部拆到references/子目录主文件只保留触发条件、执行步骤、输出模板和不可违背的红线字数控制在 400 行以内。效果比原来好很多。第三个坑要求 AI 遵守的规则本身写得不明确。比如我在早期版本里写过“注意代码质量”这种话等于没写。AI 不知道“质量”在你的语境里指什么。后来我改成可以核验的标准比如“所有新增函数必须包含参数说明和返回值说明”“禁止在业务代码中直接调用console.log”。模型对明确的规则执行能力强得多。第四个坑全局 Skill 和项目 Skill 互相污染。全局目录里的 Skill 在任意项目都会加载所以不要把带有特定项目细节的规则放进去否则在别的项目里使用时模型会拿 A 项目的规范来指导 B 项目的编码。我的习惯是放全局的只有和行业基础做法相关的比如“代码审查必须标严重级别”“文档必须写使用场景”凡是涉及具体技术栈、目录结构、团队规范的一律放项目级。第五个坑写完之后从不迭代。模型本身在更新项目代码也在变Skill 写一次不可能永远有效。我每隔几周会翻一遍高频使用的 Skill问自己一个问题最近几次使用中有没有哪次输出不满意不满意的地方能不能通过调整 Skill 内容来解决如果你发现某些问题反反复复出现那大概率是 Skill 里缺了一条规则。第六个坑直接信任第三方 Skill不读源码。社区里有很多现成 Skills 合集水平参差不齐其中也不乏夹带私货的。有些 Skill 会指示 AI 去执行一些危险操作比如删除文件、向远程地址发送数据。我的建议是任何第三方 Skill拿到手先通读一遍SKILL.md和它引用的脚本确认没有可疑行为再放进来。这条没有例外必须做。我在实际使用过程中还有一个体会自建 Skill 的收益很多时候不是“省了时间”而是“逼你想清楚”。为了把一件事写成可执行的技能你得先把那件事本身理清楚。这个副产品可能比 Skill 本身还值钱。所以别怕写得不好先写一版用起来再改。