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% 的场景，用户级的三个补足个人偏好。总共十个技能，维护成本可控，收益明显。如果你刚开始建技能库，建议从三个起步：代码规范、项目上下文、提交格式。这三个最容易见效，也最容易写。用顺了再逐步加，别一上来就追求大而全。
最后分享一个我踩过的坑：不要为了"看起来专业"而写技能。我一开始写了个特别详细的"架构决策记录"技能，结果半年没用上一次，因为架构决策本来就是低频事件。技能库的价值在于精而不在于多，每个技能都应该是被真实需求逼出来的，而不是拍脑袋想出来的。
