我们天天跟 Claude Code、Cursor 这类 AI 编程工具打交道最常见的一个状态是什么不是写不出代码而是“教 AI 写代码”。上下文里塞一大段背景说明再补几条“你记住这个项目里数据库命名不要用下划线”之类的口头规矩最后还得强调三遍输出格式。代码本身不难难的是每次开新会话都要把同样的生平简历重新给 AI 念一遍。WorkSkill 解决的就是这个问题。简单说它是一个装了 400 多个现成技能的仓库覆盖代码审查、架构梳理、重构建议、测试生成、技术文档写作这些高频场景。每个技能都是一个结构化的 Markdown 文件相当于给 AI 准备了一份“岗位说明书”。你不用再临时写提示词直接把技能文件丢进 Claude Code 或 Cursor 的配置目录之后要用的时候一句话就能触发。这篇东西我会从为什么要用技能库讲起再拆解 WorkSkill 的技能内部结构、安装步骤、避坑经验最后聊一聊怎么把你自己沉淀下来的工作流也做成新技能。适合现在正在重度使用 AI 编程工具、但对“每次都要重新调教”感到疲倦的开发者。1. 为什么你需要一个“技能库”从反复调教到一次装好1.1 问题的根源AI 没有“肌肉记忆”大模型本身是没有记忆的或者说它的记忆只存在于当前这段话里。你上一个会话告诉它“我们这个项目的错误码规范是第一段是模块编号、第二段是具体错误编号”它记住了但只要开个新会话或者换一个文件上下文它又忘得一干二净。这就是很多人的真实体感AI 写出来的东西时好时坏好不好的区别不取决于模型能力而取决于你有没有把“背景”讲清楚。讲得越细它干活越靠谱懒得讲它就给你一套非常“通用”但完全不符合你项目现状的答案。打个比方这就像一个外包工程师你需要他干活之前先给他讲三天项目背景。技能库做的事情就是把这些背景说明、工作流程、质量要求、输出格式全部写进一套标准文件里。你不再需要反复讲AI 看到技能文件就等于看到了一份完整的“入职手册”。1.2 技能Skill到底是什么一段结构化的“职业说明书”在 Claude Code 和 Cursor 这类工具里技能通常表现为一个 Markdown 文件文件名类似code-review.md、api-design.md存放路径固定工具启动时会自动索引这些文件。当你在对话里提出一个任务比如“帮我过一下这个 PR”AI 会在索引里做匹配发现code-review.md这个技能的描述符合当前意图就会主动把整个文件内容作为指令的一部分加载进来。然后它的一举一动都会受到技能文件约束先检查什么、重点看什么、输出什么格式、有哪些红线不能碰。这和普通的“提示词模板”有本质区别。提示词模板是你每次手动复制粘贴的一段文字而技能是一个有固定格式、能被 AI 自动发现和加载的独立文件。前者依赖你的自觉后者依赖系统的机制。所以一旦技能库建好你基本可以忘掉它AI 每次都会自动按标准工作。这就是 WorkSkill 这类技能库最大的价值——它把“个人口头禅”变成了“团队工作流”。2. WorkSkill 技能库的整体设计400 技能的编排逻辑2.1 技能分类不是 400 个都塞给你而是按场景分组取用我第一次看到 400 这个数字时第一反应是“谁会需要这么多技能”。用了一段时间之后发现真正合理的用法是把它当成一个自选超市按项目类型取用其中的一小部分。WorkSkill 内部大致按这么几类划分代码质量类代码评审、缺陷自查、边界条件补全、性能隐患扫描工程规范类Git 提交信息规范化、依赖升级检查、接口文档生成架构分析类从代码反向梳理模块关系、识别过度设计、评估技术债测试相关类单测生成、测试数据构造、覆盖率分析文档写作类README 生成、变更日志整理、技术方案撰写调试排查类日志分析、报错归因、二分定位建议每一类下面又有多个细分的技能文件。比如说“代码评审”它不是只有一个文件而是区分了“日常自测评审”“提交 PR 前的严格评审”“只查安全问题”这几个版本。这意味着你可以在不同的场景触发不同强度的检查而不是让 AI 每次都走同一套流程。如果你要问 400 个技能会不会让 AI 变笨我要说会如果你把它们一次性全部丢进配置目录的话。所以我的推荐做法永远是“按需启用”每次只把当前项目需要的 10 到 20 个技能放进活跃目录剩下的存到一个备份目录里。2.2 一个技能文件的内部结构从前提到输出格式我特意找了一个做代码审查的技能文件拆开看它的结构非常值得学习。文件开头是 YAML 格式的元信息然后是一大段正文说明。元信息里最关键的两个字段是name和descriptionAI 靠这两个字段来判断“什么时候该使用这个技能”。--- name: pr-review description: 对代码变更做一次系统性审查重点检查边界条件、资源释放和错误处理。适合在提交 PR 前使用。 --- # PR Review 工作流 ## 审查步骤 1. 先读取 diff梳理变更涉及的核心模块。 2. 逐层检查边界条件 - 资源释放 - 错误处理 - 并发安全。 3. 对每个发现的问题给出文件路径、行号、严重程度和修改建议。 ## 输出格式 按以下表格输出 | 严重程度 | 文件 | 行号 | 问题描述 | 建议 |这里最关键的设计在于description写得很克制只简要说清楚“在什么场景下用”而不是把所有审查细节都写进去。因为细节写太多会让 AI 在匹配阶段被多余信息干扰甚至导致它在不该用这个技能的时候误触发。把细节留给正文把场景留在描述里这是一个好技能文件的核心原则。2.3 为什么是 Markdown 而不是普通 Prompt有朋友问过我一个问题这跟我在网上收藏的那些“超级提示词”有什么区别区别很大。提示词是一大段混杂着角色设定、任务说明、输出要求的文本它的结构是非标准的换一个工具就可能失效。而技能文件是结构化数据有固定的头部信息、正文规范、可预期的文件路径。工具可以主动扫描它、索引它并且在合适的时机自动加载它。它不再是一段“你复制给我”的文字而是一个“系统能自己发现的配置”。另外一个很重要的点Markdown 文件可以放进版本控制。团队的技能库可以放在 Git 仓库里技能文件更新了所有人同步一下就全都有了。这就把一个本来存在个人聊天窗口里的经验沉淀成了团队资产。这一点在后面讲版本管理的时候还会展开。3. 一键安装实操把技能装进 Claude Code / Cursor3.1 安装前要做好的准备先明确一下你当前用的工具是什么版本以及配置目录在哪里。以我常用的配置路径为例我这个比较标准的做法是先建一个统一的技能仓库目录把 WorkSkill 克隆下来然后把需要的技能分类拷贝到各自的配置目录里。这里有一个实用的建议不要修改 WorkSkill 的原始文件复制一份到你的专属目录。因为后续升级技能库的时候你直接git pull就能拿到新版本而不会被你本地改过的东西搞出冲突。3.2 导入到 Claude Code一条命令完成Claude Code 支持从本地目录加载技能。我用下来最顺手的做法是把它配置目录指向 WorkSkill 的某个子目录而不是把 400 个文件全部拷过去。# 1. 克隆技能库到本地 git clone work-skill-repo-url ~/work-skill # 2. 创建 Claude Code 的技能目录首次需要 mkdir -p ~/.claude/skills # 3. 把需要的技能类别放进去这里是举例按你实际需要取用 cp -r ~/work-skill/skills/code-review ~/.claude/skills/ cp -r ~/work-skill/skills/testing ~/.claude/skills/装完之后重启 Claude Code让它重新扫描技能目录。然后你在对话里直接说一句“按项目规范帮我做一次 PR 审查”如果看到了我上面提到的表格形式的输出就说明技能已经被正常加载了。顺手说一下技能文件不是越全越好。Claude Code 启动时会对技能目录建立索引文件太多会拖慢启动速度也会在上下文窗口里占用太多空间。我建议一个项目里活跃技能控制在 15 个左右最多不要超过 20 个超出的部分留在备份目录里。3.3 导入到 Cursor利用项目规则与命令目录Cursor 的机制和 Claude Code 不太一样。Cursor 更依赖项目级的规则文件放在.cursor/rules目录下而一次性执行类的工作流可以放到.cursor/commands里。WorkSkill 的文件在导入 Cursor 时需要做一个简单的适配。我试过的最稳方式是这样的把技能文件按“目录映射”的方式放好。# 以项目根目录为基准创建技能目录 mkdir -p .cursor/rules/code-review # 将 WorkSkill 里的技能文件复制进来 cp ~/work-skill/skills/code-review/pr-review.md .cursor/rules/code-review/要注意的是 Cursor 规则文件的自动加载机制很强它会尝试把.cursor/rules下的内容作为项目上下文来理解。所以你在复制文件时要特别留意那些描述太宽泛的技能比如标题叫“代码优化建议”这种它可能会在你写每一行代码的时候都试图干预非常烦人。更好的做法是在 Cursor 里把一些“按需触发”的工作流比如重构、审查、测试生成做成 Command 文件也就是手动敲/来触发。Command 文件放在.cursor/commands/目录下内容就是一段完整的、带有占位符的指令。这样你按下/code-review才会触发它平时完全不会打扰你。3.4 验证技能是否生效装完之后不要急着开干先花一分钟验证一下。方法很简单你在对话里故意说一句接近技能描述但又不完全相同的话看看 AI 是否会自动套用该技能的流程。举一个我在测试时反复用的例子如果装的是 API 设计类的技能我就会问“帮我设计一个用户注销的接口”看它输出里有没有按技能要求包含错误码列表、流量控制方案、兼容性分析这些章节。如果确实有说明技能被正确加载。如果没有多半是技能文件的description写得不够精准或者目录放错位置了。还有一种情况是AI 加载了技能但中途又“忘”了输出到一半开始泛泛发挥。这种情况我见过好多次最后定位到原因基本都是技能文件正文太长、太多无关细节把 AI 的注意力带偏了。解决办法后面会细说。4. 用对方式才高效技能的正确打开方式与避坑指南4.1 组合使用把多个技能串成一条工作流单个技能很好用但真正的效率提升来自组合。拿一次功能开发来说我现在的标准流程已经变成了这样第一步用requirement-analyzer技能拆分需求产出接口设计和数据模型定义第二步用api-design技能审查接口的完整性主动补上边界情况和异常码第三步代码写完后用pr-review做一次全量自测第四步提交前用commit-message技能生成规范化的提交信息第五步合并后用changelog技能更新项目变更日志每一步都在对话里用一句自然语言触发AI 会自动匹配到对应技能。你不需要频繁解释上下文因为它每走一步上一步的产出就已经留在对话里了。整套流程跑下来环节之间几乎没有缝隙。在使用多个技能时有一个细节技能的触发顺序很重要。比如你如果先跑了pr-review再跑requirement-analyzer会觉得输出很别扭因为审查技能会习惯性地指出需求里的问题而不是帮你完善设计。所以我的建议是先跑“建设类”技能需求分析、接口设计、代码生成再跑“质检类”技能代码审查、性能扫描、安全排查顺序反了会很乱。4.2 高频翻车点为什么明明装了技能AI 还是“不听话”我把实际用 WorkSkill 过程中反复踩到的坑整理成一张表基本覆盖了九成以上的“技能失效”问题。现象原因解决办法AI 完全没有按技能流程走description写得过于宽泛AI 没识别出来该用精化技能描述点出具体触发场景技能被“误触发”不该用它时它出来了description覆盖场景过宽在描述里加上“仅当...时使用”输出到一半开始跑偏技能正文过长上下文被其他信息冲淡精简正文删掉冗余的背景描述启动变慢、响应迟缓一次性加载了太多技能文件按项目裁剪控制在 15 个左右同一个项目里多技能互相打架两个技能的职责范围重叠合并同类项保留一个主技能这里我要重点说一下第一个问题。很多时候你从 WorkSkill 里拿了一个技能文件如获至宝地丢进目录里结果发现 AI 就是不理你。那大概率不是因为技能没用而是因为它的description描述的风格和你平时的表达习惯不匹配。举个例子技能描述写的是“perform systematic code review”而你平时对话是中文的“帮我看看代码有没有问题”AI 不一定能建立起这个关联。解决办法也很粗暴把description改成你自己的高频表达比如直接在原描述后面加上一句“当用户说‘帮我看看代码’或者‘过一下代码’时使用”。4.3 日常维护技能库不是装完就完了技能文件跟代码一样需要持续维护。我习惯每两周左右做一次技能使用情况的复盘看看哪些技能一次都没触发过哪些技能每次触发都要手动纠正。从没触发过的不一定没用但大概率是它的描述和实际使用习惯脱节了。每次都要手动纠正的说明技能内容有问题直接改。还有一个很值得做的维护操作把你在对话里重复说过三遍以上的话整理出来写成新的技能文件。我后面会展开讲这个怎么做。这里先给一个判断标准如果你发现自己每次要求 AI “注意输出格式”“按照之前的规矩来”“不要用 XX 写法”那这三句话就已经可以变成技能了。5. 扩展与二次开发把自己的工作流沉淀成新技能5.1 从需求到技能文件三步法用了一段时间 WorkSkill 之后我最大的收获其实不是 400 个现成技能而是明白了“技能”这种机制的底层逻辑。现在我自己写新技能已经完全不费劲了基本上按三步走。第一步写清触发场景。这是最关键的一步我需要精确描述什么情况下 AI 该用这个技能。好的描述通常是这样的“当用户要求对接口响应格式做调整时”。糟糕的描述是这样的“处理接口相关任务”。后者覆盖了太多场景AI 反而不知道该不该用。第二步写死执行步骤。把过程分成可执行的、有顺序的操作步骤。不要写“检查代码质量”这种抽象指令要写“先扫描所有文件中的 TODO 和 FIXME再统计超过 300 行的函数逐个分析可拆分点”。第三步固定输出格式。给 AI 规定好输出模板。表格、清单、特定字段的列表都可以关键在于让 AI 的输出保持稳定方便你直接复制到文档或提交信息里。5.2 动手实践一个“提交信息规范化”技能从头写拿我自己写的一个技能举例。当时的情况是团队提交信息风格不统一有人写fix bug有人写长长的流水账。我直接把规范写成了一个技能文件。--- name: commit-message description: 根据代码变更生成符合团队规范的 Git 提交信息。当用户准备提交代码、要求生成提交信息时使用。 --- # 提交信息规范 根据本次代码变更内容生成一个符合以下规范的提交信息 1. 首行不超过 50 个字符格式为「类型: 简短的描述」。 2. 类型只能是 feat / fix / refactor / docs / test / chore 之一。 3. 正文按以下顺序组织 - 变更背景 - 具体改动 - 影响范围 4. 如果变更包含破坏性改动必须在正文末尾标注「BREAKING CHANGE」并说明原因。整个文件不算正文说明核心就三段。我从写完这个技能到现在已经连续用了一个多月基本没有手动改过提交信息。它自己跑得很稳说明只要步骤足够明确、格式足够具体AI 的执行效果就能控制到一个让人放心的程度。5.3 团队的共享与版本化技能也能进 Git如果你是一个人用技能文件放本地目录就够了。但如果是团队协作我强烈建议你建一个私有仓库把大家认可的技能统一管理起来。这样做的好处有三个更新可追溯、评审可讨论、新人可复用。新成员入职之后以前要花两周慢慢“领悟”的项目潜规则现在直接让他把技能库配置好AI 就会在他写第一行代码之前自动告诉他正确的方式。这不光是效率问题更是保障代码风格和工程质量一致性的手段。我在做团队技能库共享时踩过一次坑在这里提个醒不要直接把 WorkSkill 的原版技能文件扔到团队仓库里一定要先按自己项目的实际情况改写一遍。WorkSkill 覆盖面广但它是面向通用场景设计的里面很多信息放在你的项目里反而是噪音。团队技能库应该精简、定制、贴近自己的技术栈和业务场景而不是追求多。写在最后的一点心得用 WorkSkill 这段时间我最大的感受是 AI 编程工具的真正分水岭不在模型本身而在你怎么组织给它的信息。同样的一个模型一个只会一句“帮我写个 xxx”另一个装着十个精准技能文件产出质量的差距可能比换一个更强的模型还要明显。我现在拿到一个新项目第一件事已经不再是写代码框架而是先花半天时间把项目相关的技能文件建好。后面所有开发工作都是在这个基础上跑越跑越顺。好这篇关于 WorkSkill 的完整讲解就到这里希望对正在折腾 Claude Code 和 Cursor 的你有点帮助。如果你自己写了一些好用的技能文件或者用 WorkSkill 的过程里有独特的踩坑经验欢迎在评论区和大家聊聊说不定你的一句话就能让别人少走很多弯路。