1. 为什么装技能这件事值得单独写一篇指南如果你最近在开发者社区里泡着大概率已经被两个词反复刷屏Skills和Agent。前者是给 AI 编程助手加装的能力包后者是这些助手从补全代码进化到自主干活的形态。很多人第一次听到 Skills 的反应是这不就是提示词模板吗但真正用过一轮之后会发现它和提示词是两码事——提示词是你每次都要重复交代的临时指令而 Skills 是写进文件、被工具自动识别、按需加载的持久化能力单元。我自己的经历比较典型。最开始用 Cursor 的时候我把常用的代码规范、项目结构说明、提交信息格式全都塞进一个超长的 rules 文件里结果就是每次对话都要吃掉大量上下文模型还经常选择性失忆。后来接触到 Skills 这套机制把不同场景的能力拆成独立文件按需触发上下文占用直接降下来命中率反而上去了。再后来 Claude Code 也支持了类似的东西配合SKILL.md这种约定式文件整个工作流就顺了。这篇内容想解决三个具体问题第一Skills 到底是什么、和 Agent 是什么关系第二哪 8 类技能是真正值得装的而不是凑数的第三怎么把它们接进 Cursor 和 Claude Code从零跑通全流程。适合已经用过 AI 编程工具、但还没系统整理过自己能力库的开发者也适合刚上手 Claude Code、想搞清楚SKILL.md该怎么写的新手。全文不讲虚的都是我自己踩过坑之后沉淀下来的操作路径。需要先说明一点Skills 这个概念在不同工具里的实现细节不完全一样Cursor 侧更偏向 rules 和自定义命令的组合Claude Code 侧则是明确的SKILL.md目录约定。下面讲的时候我会把两者的差异标清楚避免你照着 A 工具的做法去 B 工具里试然后一脸懵。2. Skills、Agent、Harness 三个词到底在说什么2.1 从补全到执行Agent 到底多了什么传统代码补全的工作模式是你写一半它猜后半句。这个模式下模型是被动的它不关心你的项目结构、不关心你上一步干了什么、更不会主动去读文件。Agent 模式则完全不同——它有一个执行循环接收目标、规划步骤、调用工具读文件、写文件、跑命令、观察结果、再决定下一步。这个循环跑起来模型就从打字员变成了施工队。但 Agent 本身只是个空壳。它能不能干活、干得好不好取决于两样东西工具集和能力描述。工具集决定了它能碰什么能不能读文件、能不能执行 shell能力描述决定了它知道该怎么碰遇到 React 项目该用什么规范、写提交信息该用什么格式。Skills 就是后者——它是写给 Agent 看的操作手册告诉它在特定场景下应该遵循什么流程、注意什么细节。这里有个容易混淆的点很多人以为 Agent 越强越好其实不是。一个没有约束的 Agent 反而危险它可能自作主张改一堆文件、跑一堆命令。Skills 的价值恰恰在于给 Agent 划边界——在什么场景下触发、触发后按什么步骤走、哪些操作必须先确认。这就像给新员工一本岗位手册不是限制他而是让他少犯错。2.2 Harness 和 Agent 的区别一个常被搞混的概念社区里经常有人问 harness 和 agent 有什么区别。简单说Agent 是谁在干活Harness 是干活的环境和约束框架。Harness 负责的是怎么把用户输入喂给模型、怎么解析模型的工具调用请求、怎么把工具执行结果回传、怎么控制循环的终止条件、怎么处理错误和超时。你可以把它理解成 Agent 的运行时。打个比方Agent 是司机Harness 是车。司机决定去哪、怎么开但车决定了司机能踩多深的油门、能转多大的弯、仪表盘上能看到什么信息。同一个司机开不同的车表现可能天差地别。这也是为什么同一个模型在不同工具里表现差异很大——不是模型变了是 harness 的实现不一样。理解这一层之后你就能明白为什么 Skills 的写法要看工具下菜Cursor 的 harness 和 Claude Code 的 harness 对能力描述的加载时机、触发方式、上下文预算都不一样。同一个技能在两个工具里的组织方式需要微调。2.3 SKILL.md 的约定为什么是文件而不是配置Claude Code 选择用SKILL.md这种纯文件约定而不是搞一套 JSON 配置或者数据库这个设计选择很值得说。文件的好处是可版本控制、可 diff、可 review、可分享。你可以把技能库放进 git团队里谁改了哪个技能一目了然你也可以把某个技能单独抽出来发给同事他放到对应目录就能用。SKILL.md的基本结构通常包含三块元信息技能名、描述、触发条件、能力说明这个技能解决什么问题、操作指引具体步骤、注意事项、示例。元信息里的描述特别关键因为 Agent 是靠这段描述来判断当前任务要不要加载这个技能的。描述写得太泛技能会被频繁误触发写得太窄该用的时候又用不上。我自己的经验是描述里最好包含具体的触发关键词和场景比如当用户要求生成数据库迁移脚本时比数据库相关要好得多。这就像给技能装了一个精准的开关而不是一个模糊的感应器。3. 8 类真正值得装的技能以及每类的取舍逻辑3.1 代码规范类把团队的潜规则变成显规则每个团队都有一套没写进文档的代码规范变量命名习惯、目录组织方式、错误处理风格、日志格式。新人靠 code review 慢慢学Agent 则完全不知道。代码规范类技能就是把这些潜规则显式化。这类技能的内容应该包括命名约定camelCase 还是 snake_case、组件名怎么起、文件组织一个目录放多少文件、index 文件要不要写、导入顺序、注释风格。关键是要给正反例光说用驼峰命名没用得给出getUserInfo而不是get_user_info这种具体对照。取舍逻辑这类技能不要写太细。我见过有人把 ESLint 规则逐条抄进技能文件结果上下文爆炸还没人看。正确做法是只写那些lint 工具管不到、但团队确实在意的约定比如业务逻辑不要写在组件里API 调用统一走 service 层这种架构级约束。3.2 项目上下文类让 Agent 秒懂你的代码库新接一个项目人类要花几天熟悉结构Agent 每次对话都是从零开始。项目上下文类技能解决的就是这个问题把项目的地图、关键模块、数据流、依赖关系写清楚让 Agent 一上来就知道这个功能该改哪个文件。内容上建议包含顶层目录结构说明、核心模块职责、主要数据流走向、外部依赖清单、本地开发启动步骤。特别有用的是**常见任务索引**——比如要加一个新 API 端点改这三个文件这种索引能极大提升 Agent 的定位准确率。取舍逻辑这类技能要定期更新否则会误导 Agent。我的做法是把它和 README 放在一起维护改架构的时候顺手更新避免变成僵尸文档。3.3 提交与协作类把 git 流程固化下来提交信息格式、分支命名、PR 描述模板、changelog 生成规则——这些流程性的事情最适合做成技能。因为它们是高频、重复、有固定格式的正好是 Agent 擅长的领域。一个实用的提交类技能应该规定提交信息的结构type、scope、subject、body、type 的取值范围、什么情况算 breaking change、PR 描述要包含哪些部分。写清楚之后你让 Agent 帮你整理提交出来的东西基本不用改。取舍逻辑这类技能要和团队的 CI 校验对齐。如果 CI 里用 commitlint 校验技能里的规则就得和 commitlint 配置一致否则 Agent 生成的提交过不了 CI反而添乱。3.4 测试编写类让 Agent 写出能跑的测试让 Agent 写测试最大的问题是它经常写出看起来对但跑不起来的测试mock 用错、断言写反、异步没处理。测试编写类技能就是把这些坑提前堵上。内容应该包括测试框架和断言库的选择、mock 策略什么时候 mock、mock 到什么粒度、测试文件命名和位置、异步测试的写法、覆盖率要求。最好附上几个完整的测试示例让 Agent 有样学样。取舍逻辑这类技能要区分单元测试和集成测试两者的写法差异很大。如果混在一起写Agent 容易用单元测试的思路写集成测试导致 mock 过度、测了个寂寞。3.5 调试排查类给 Agent 一套排查方法论Agent 遇到报错时常见反应是猜一个改法然后试效率很低。调试排查类技能给它一套方法论先看什么、再看什么、怎么缩小范围、怎么验证假设。这类技能可以写成排查清单的形式第一步看错误堆栈定位到文件和行号第二步检查最近的改动第三步确认环境变量和依赖版本第四步加日志复现。有了这套流程Agent 的排查会系统很多而不是乱试。取舍逻辑这类技能要针对项目特有的坑来写。比如这个项目的缓存层有个已知问题改了配置要重启才生效这种项目专属知识比通用排查方法更有价值。3.6 文档生成类让注释和文档跟上代码代码写完不写文档是通病Agent 可以帮忙但前提是它知道你要什么格式的文档。文档生成类技能规定函数注释的格式JSDoc 还是 docstring、README 的结构、API 文档的生成方式、变更日志的写法。取舍逻辑这类技能要和项目的文档工具链对齐。如果项目用 TypeDoc 生成文档技能里就得规定注释要符合 TypeDoc 的解析规则否则生成的文档是空的。3.7 重构迁移类大改动时的安全网重构和迁移是最容易出事的场景改了一处崩了三处。重构迁移类技能提供一套安全流程先补测试、再小步改、每步验证、保留回滚点。内容上包括重构前的检查清单测试覆盖率够不够、有没有未提交的改动、重构中的原则一次只改一件事、保持行为不变、重构后的验证跑测试、对比输出、检查性能。取舍逻辑这类技能要强调**先测试后重构**的顺序。Agent 有时候会急着改代码技能里必须明确要求它先确认测试覆盖否则重构就是裸奔。3.8 领域知识类把业务逻辑讲给 Agent 听最后一类最容易被忽略但价值很高领域知识。你的业务有特定的术语、规则、边界条件这些不写清楚Agent 写出来的代码逻辑就是错的。比如电商项目里的库存扣减时机优惠券叠加规则订单状态流转这些业务规则必须显式写出来。Agent 不懂业务你告诉它它才懂。取舍逻辑这类技能要用业务语言写不要用技术语言。写下单时先锁库存再扣款锁库存失败直接返回比写调用 inventoryService.lock() 然后 paymentService.charge()更有用因为前者是规则后者是实现实现会变规则相对稳定。4. 接入 Cursor 的完整流程与踩坑记录4.1 Cursor 侧的能力组织方式Cursor 没有 Claude Code 那种严格的SKILL.md目录约定它的能力组织主要靠三样东西Rules项目级和用户级规则、自定义命令可复用的提示词片段、Notepads可引用的上下文片段。要做 Skills 的效果通常是把这三者组合起来用。我的组织方式是项目级 Rules 放代码规范和项目上下文用户级 Rules 放跨项目的通用偏好自定义命令放高频操作比如生成提交信息写测试Notepads 放需要频繁引用的长文档比如 API 规范。这样分工之后每块内容各司其职不会互相挤占上下文。需要提醒的是Cursor 的 Rules 有长度限制塞太多会被截断。所以不要把 8 类技能全塞进 Rules而是按需拆分高频的放 Rules低频的做成自定义命令手动触发。4.2 从零配置一个项目级技能库假设你有一个 React TypeScript 项目要配置一套基础技能库。步骤如下第一步在项目根目录创建.cursor/rules/目录。这是 Cursor 约定的项目规则目录里面的文件会被自动加载。第二步按技能类型拆分文件。我一般拆成这几个code-style.mdc代码规范、project-context.mdc项目上下文、testing.mdc测试规范、git-workflow.mdc提交协作。每个文件用 Cursor 的 mdc 格式头部带元信息--- description: 项目代码规范包括命名、目录组织、导入顺序 globs: [src/**/*.ts, src/**/*.tsx] alwaysApply: false --- # 代码规范 ## 命名约定 - 组件用 PascalCase如 UserProfile - 工具函数用 camelCase如 formatDate - 常量用 UPPER_SNAKE_CASE如 MAX_RETRY_COUNT ...这里的globs字段很关键它决定了这个规则在哪些文件上生效。alwaysApply: false表示不强制加载让 Cursor 按需触发。这个设置能有效控制上下文占用。第三步把高频操作做成自定义命令。在.cursor/commands/目录下创建命令文件比如gen-commit.md# 生成提交信息 根据当前 git diff 生成符合 Conventional Commits 规范的提交信息。 格式type(scope): subject type 取值范围feat, fix, docs, style, refactor, test, chore 要求 - subject 用中文不超过 50 字 - 如果有 breaking change在 body 里说明 - 不要加 emoji之后在 Cursor 里输入/gen-commit就能触发。4.3 实测中遇到的三个坑坑一规则文件互相冲突。我一开始把代码规范和项目上下文写在同一个文件里结果改规范的时候不小心动了上下文导致 Agent 对项目结构的理解出错。后来拆成独立文件各改各的问题消失。教训是一个文件只干一件事。坑二globs 写太宽导致误触发。有次我把测试规范的 globs 写成**/*结果写业务代码的时候 Agent 也在套测试规范生成的代码里莫名其妙多了断言。改成**/*.test.ts之后就正常了。globs 一定要精确。坑三自定义命令的上下文不继承。自定义命令触发时不会自动带上当前打开的文件内容。如果命令需要文件上下文得在命令里显式说明读取当前文件。这个细节文档里没写清楚我试了好几次才搞明白。4.4 Cursor 中文设置与使用习惯顺带说下 Cursor 的中文设置因为很多人第一次用会找不到。在设置里搜索 language把显示语言改成中文即可界面会变成中文。但要注意界面语言和模型输出语言是两回事——界面改成中文模型默认还是用英文回复。要让模型用中文得在 Rules 里明确写所有回复用中文或者在对话里指定。我自己的习惯是界面保持英文因为很多术语中文翻译反而不好找但在用户级 Rules 里加一条回复用中文代码注释用中文变量名用英文。这样既不影响查文档又能让输出符合中文团队的习惯。5. 接入 Claude Code 的完整流程与 SKILL.md 写法5.1 Claude Code 的安装与基础配置Claude Code 的安装方式取决于你的系统。在 macOS 和 Linux 上通常通过包管理器安装在 Ubuntu 上用对应的包管理命令即可。安装完成后第一次运行会引导你完成认证配置。配置的核心是项目级配置和用户级配置的分离。用户级配置放在用户主目录下管跨项目的偏好项目级配置放在项目根目录管这个项目特有的东西。Skills 通常放在项目级的.claude/skills/目录下每个技能一个子目录里面放SKILL.md。需要强调的是Claude Code 的 Skills 加载是按需的它先读所有技能的元信息name 和 description判断当前任务需要哪些技能再把对应技能的完整内容加载进上下文。这个机制决定了元信息写得准不准直接影响到技能能不能被正确触发。5.2 SKILL.md 的结构与写法要点一个标准的SKILL.md长这样--- name: database-migration description: 当用户要求创建或修改数据库迁移脚本时使用。适用于需要新增表、修改字段、添加索引的场景。 --- # 数据库迁移技能 ## 适用场景 - 新增数据表 - 修改现有表结构 - 添加或删除索引 ## 操作步骤 1. 确认迁移工具版本和命名规范 2. 生成迁移文件文件名格式为 YYYYMMDDHHMMSS_description 3. 在 up 方法里写正向迁移down 方法里写回滚 4. 检查是否有数据丢失风险 5. 提醒用户先在测试环境验证 ## 注意事项 - 不要在生产环境直接跑迁移 - 大表加索引要考虑锁表时间 - 删除字段前确认没有代码引用几个写法要点description 要包含触发场景和关键词这是 Agent 判断是否加载的依据操作步骤要具体到可执行不要写合理设计表结构这种废话注意事项要写项目特有的坑通用建议价值不大。5.3 手动安装 GitHub 上的 Skills社区里已经有不少人分享了自己的 Skills 库从 GitHub 上拿下来用是很常见的操作。流程是找到目标仓库clone 或下载把技能目录复制到你的.claude/skills/下然后检查SKILL.md的元信息是否符合你的项目情况。这里有个坑别人的技能不一定适合你的项目。比如一个针对 Python 项目的测试技能拿到 TypeScript 项目里就会误导 Agent。所以复制过来之后一定要通读一遍把不适用的部分删掉或改掉。我一般会先在一个小项目里试确认没问题再放到主力项目里。另一个坑是技能之间的依赖。有些技能假设你已经装了另一个技能或者假设项目里有某个配置文件。复制的时候要检查这些前置条件否则技能触发了但跑不通。5.4 验证技能是否生效的方法装完技能之后怎么确认它真的生效了我的做法是构造一个明确的触发场景然后观察 Agent 的行为。比如装了数据库迁移技能就让它帮我加一个用户表看它是不是按技能里写的步骤走。如果没触发先检查 description 是不是写得太窄或太泛。太窄的话换个说法再试太泛的话Agent 可能加载了但没按预期执行。还可以临时把 description 改得更直白确认机制通了之后再调回正常表述。如果触发了但执行不对检查技能内容本身有没有歧义。Agent 是按字面意思执行的你写合理处理错误它就不知道具体怎么处理。改成捕获异常后记录日志并返回默认值这种明确指令效果会好很多。6. 技能库的长期维护与迭代思路6.1 什么时候该新增一个技能不是所有重复操作都值得做成技能。判断标准是这个操作是否高频、是否有固定流程、是否容易出错。三个都满足才值得做。低频的、一次性的、简单的操作做成技能反而是负担——维护成本比收益还高。我自己的阈值是一个月内重复三次以上、每次都要重新交代细节、且出过至少一次错的操作才会考虑做成技能。按这个标准筛下来真正值得做的技能其实不多但每一个都是精品。6.2 技能过期的信号与更新时机技能会过期这是必然的。项目架构变了、工具升级了、团队规范调整了技能内容就过时了。过期的技能比没有技能更糟因为它会误导 Agent。识别过期的信号Agent 按技能执行后频繁出错、技能里提到的文件或命令已经不存在、团队成员反馈这个技能说的不对。出现这些信号就该更新了。更新时机建议和项目里程碑绑定每次大版本发布、每次架构调整、每次工具链升级都过一遍技能库。我一般会在项目根目录放一个SKILLS_CHANGELOG.md记录每次技能变更的原因和内容方便回溯。6.3 团队协作中的技能共享技能库在团队里共享能放大价值但也会带来一致性问题。我的做法是核心技能进 git个人偏好留在本地。代码规范、项目上下文、提交格式这些团队统一的放进项目仓库的.claude/skills/或.cursor/rules/所有人共享个人的写作风格偏好、常用命令别名这些放在用户级配置里不污染项目。共享技能需要 review 机制。新技能或技能变更走 PR团队里至少一个人看过再合并。这样能避免有人塞进一个误导性的技能影响所有人的 Agent 行为。6.4 从技能到 Agent 工作流的演进技能装到一定数量之后你会发现它们可以组合成工作流。比如接需求 → 写代码 → 写测试 → 生成提交 → 更新文档这一整条链路每个环节对应一个技能串起来就是一个完整的 Agent 工作流。这时候可以考虑把工作流也固化下来做成一个元技能或者编排脚本。Claude Code 里可以用自定义命令串联多个技能Cursor 里可以用自定义命令加 Rules 组合实现。走到这一步Agent 就不只是帮你写代码而是帮你走流程了。不过要提醒一句不要过早追求自动化。技能库还没稳定就急着串工作流一旦某个环节出问题整条链路都崩。我的建议是先把单个技能打磨好用顺了再考虑串联。7. 几个高频问题的直接回答7.1 技能装多了会不会拖慢响应会但影响可控。关键在于技能的加载机制如果工具是全量加载那技能越多上下文越满响应越慢如果是按需加载只有被触发的技能才进上下文影响就小。Claude Code 是按需加载Cursor 的 Rules 可以通过alwaysApply: false控制所以只要组织得当装几十个技能也不会明显拖慢。真正的风险不是速度而是误触发。技能多了之后Agent 判断该用哪个的难度上升可能出现该用的没用、不该用的用了。控制方法是把 description 写精确并且定期清理不用的技能。7.2 技能和提示词工程是什么关系技能是提示词工程的一种工程化形态。传统提示词工程关注怎么把这一次的话说好技能关注怎么把一类任务的标准流程固化下来。前者是临场发挥后者是制度建设。两者不冲突技能里也可以包含提示词技巧比如用 few-shot 示例引导输出格式。7.3 没有 Claude Code 能不能用 Skills能。Skills 的本质是结构化的能力描述文件任何支持自定义规则或提示词片段的工具都能实现类似效果。Cursor 的 Rules、VS Code 配合相关插件的自定义指令、甚至你自己维护一个提示词片段库手动粘贴都是 Skills 思想的变体。工具只是载体核心是把重复的能力沉淀成可复用的文件。7.4 怎么判断一个技能写得好不好三个标准触发准该用的时候能用上不该用的时候不打扰、执行稳按技能走能稳定产出符合预期的结果、维护易内容清晰改起来不费劲。三个都满足就是好技能。如果只能满足一个优先保证触发准因为触发不准的技能等于不存在。8. 我自己的技能库长什么样说了这么多方法论最后晒一下我自己的技能库结构给你一个具体的参考。我的主力项目是一个中型 TypeScript 全栈应用技能库分两层项目级放在仓库里团队共享包括code-style命名和目录规范、project-context模块地图和数据流、api-conventions接口设计规范、testing-guide测试写法、git-workflow提交和分支、db-migration数据库迁移、deploy-checklist发布检查清单。这七个是团队统一的走 PR 维护。用户级放在本地个人用包括writing-style我的文档写作偏好、review-checklist我 review 代码时的关注点、debug-playbook我自己的排查套路。这三个是个人习惯不共享。实际用下来项目级的七个技能覆盖了日常 80% 的场景用户级的三个补足个人偏好。总共十个技能维护成本可控收益明显。如果你刚开始建技能库建议从三个起步代码规范、项目上下文、提交格式。这三个最容易见效也最容易写。用顺了再逐步加别一上来就追求大而全。最后分享一个我踩过的坑不要为了看起来专业而写技能。我一开始写了个特别详细的架构决策记录技能结果半年没用上一次因为架构决策本来就是低频事件。技能库的价值在于精而不在于多每个技能都应该是被真实需求逼出来的而不是拍脑袋想出来的。
