agent-skills 实战：让 Claude Code 与 Cursor 真正好用的技能机制

1. 从"装完就吃灰"说起：agent-skills 到底解决了什么问题

如果你最近半年在折腾 AI coding agents，大概率经历过这个循环：兴冲冲装好 Claude Code 或者 Cursor，敲了几个 prompt，觉得"也就那样"，然后它就安静地躺在终端里吃灰了。问题往往不在模型本身，而在于——你没有一个稳定的、可复用的能力层，让 agent 真正理解你的项目、你的规范、你的工作流。

agent-skills这个项目，本质上就是给 AI coding agents 装上一套"技能包"的机制。它不是一个模型，也不是一个 IDE，而是一层可插拔的能力描述与调用规范。你可以把它理解成给 agent 写的"岗位说明书 + 操作手册"：告诉它在这个项目里，遇到什么任务该调用什么能力、按什么顺序、遵守什么约束。

我最初接触这个概念是在 Claude Code 的 skills 机制里。当时我的痛点是：每次让 agent 帮我写一个符合团队规范的 React 组件，都要在 prompt 里重复粘贴一遍"用函数组件、用 TypeScript、样式用 CSS Modules、不要用 any、导出用 named export……"。重复十次之后我就想，这些东西为什么不能固化下来？agent-skills就是回答这个问题的。

它适合谁？三类人最该关注：一是已经在用 Claude Code / Cursor 但效率没起来的开发者；二是团队里想把 AI 编码规范统一的技术负责人；三是想给 agent 扩展自定义能力的进阶玩家。哪怕你只是刚装完 Claude Code 的小白，理解 skills 的机制也能让你少走很多弯路——因为热词里高频出现的"claude code skills 安装""claude code 配置""cursor 使用教程"，背后其实都是同一个问题：怎么让 agent 从"能用"变成"好用"。

下面我会从设计思路、核心机制、实操落地、踩坑排查四个层面，把 agent-skills 这套东西拆开讲透。内容会结合 Claude Code 和 Cursor 两个主流载体的实际使用场景，尽量做到你照着就能复现。

2. 核心设计思路：为什么是"技能"而不是"提示词"

2.1 提示词工程的瓶颈在哪里

大部分人用 AI coding agent 的方式，是在对话里现写 prompt。这在单次任务里没问题，但一旦进入真实项目，三个瓶颈立刻暴露。

第一是上下文漂移。你在一个长会话里聊了三十轮，前面定的规范到后面就被模型"忘了"，因为它对上下文的注意力是衰减的。第二是不可复用。你调好的一段 prompt，换一个项目、换一个同事，就得重新调。第三是无法组合。一个复杂任务往往需要"先读代码结构、再写实现、再跑测试、再改文档"，这些步骤如果全靠自然语言描述，agent 很容易漏步骤或者顺序错乱。

agent-skills的设计出发点，就是把这三种东西从"临时对话"里抽出来，变成文件系统里的结构化资产。

2.2 技能的本质：一份带触发条件的操作契约

一个 skill 通常包含三部分信息：元数据（什么时候用）、指令正文（怎么做）、可选资源（脚本、模板、参考文件）。元数据里最关键的是name和description——description 写得好不好，直接决定 agent 能不能在正确的时机自动加载这个 skill。

这里有个很多人忽略的设计哲学：skill 不是"更长的 prompt"，而是按需加载的上下文。Claude Code 的机制是，它先扫描所有可用 skill 的元数据（这部分很轻量），当判断当前任务匹配某个 skill 的 description 时，才把完整的指令正文读进上下文。这个设计非常聪明——它让 agent 可以拥有几十上百个技能，而不会一次性撑爆上下文窗口。

对比一下 Cursor 的.cursorrules或者 Rules for AI：那些是常驻上下文，每次对话都全量加载。项目小的时候没问题，规则一多就会挤占宝贵的 token，还容易让模型抓不住重点。skills 的按需加载机制，本质上是把"上下文预算"当成稀缺资源来管理。

2.3 为什么这个抽象层级选得准

我见过不少团队尝试用"自定义 GPTs""系统提示词模板"来做类似的事，但效果都不如 skills。原因在于抽象层级。

系统提示词是全局的、静态的，改一次影响所有对话；而 skill 是局部的、可组合的，一个任务可以触发多个 skill，也可以一个都不触发。这种粒度刚好匹配真实开发场景——写代码和写文档需要的"技能"完全不同，没必要强行塞进同一个提示词里。

另一个关键点是文件系统即接口。skill 就是磁盘上的一个文件夹，里面有SKILL.md和若干资源文件。这意味着你可以用 git 管理它、可以 code review、可以分享给同事、可以版本化。这比在某个 SaaS 后台里配置提示词要"工程化"得多。热词里"claude code skills 安装"之所以被频繁搜索，就是因为大家发现这东西是可以像依赖一样安装和分发的。

3. 核心机制拆解：一个 skill 长什么样

3.1 目录结构与 SKILL.md 的字段含义

一个标准的 skill 目录大概是这样：

my-skill/ ├── SKILL.md # 必需，技能定义主体 ├── scripts/ # 可选，可执行脚本 │ └── validate.py ├── references/ # 可选，参考文档 │ └── api-spec.md └── assets/ # 可选，模板、静态资源 └── component.template.tsx

SKILL.md的头部是 YAML frontmatter，至少包含两个字段：

--- name: react-component-generator description: 当需要创建新的 React 函数组件时使用。适用于需要符合团队规范（TypeScript + CSS Modules + named export）的组件生成场景。 ---

name是唯一标识，建议用 kebab-case。description是触发开关，写法有讲究，后面单独讲。

frontmatter 下面是 Markdown 正文，也就是 agent 真正会读到的指令。这里可以写步骤、约束、示例、反例。我的经验是，正文要写得像给一个聪明但完全不了解你项目的新同事的交接文档——具体、有例子、有边界。

3.2 description 的写法决定触发准确率

这是整个 skill 机制里最容易被低估的部分。description 不是给人看的简介，而是给模型判断"要不要加载"的依据。写得太宽泛，比如"帮助写代码"，会导致 skill 被频繁误触发；写得太窄，比如"生成 Button 组件"，又会导致该用的时候用不上。

我的写法模板是：触发场景 + 适用对象 + 关键约束。举个例子：

• 差的写法：description: 生成 React 组件
• 好的写法：description: 当用户要求创建、新增或生成 React 函数组件时使用。适用于 TypeScript 项目，输出需符合 CSS Modules 样式方案与 named export 导出规范。不适用于类组件或 Vue 组件。

注意最后那句"不适用于"——显式排除能显著降低误触发。模型对否定信息的理解比我们想象的好，前提是你得写出来。

3.3 渐进式披露：让 skill 可以很"厚"

skills 机制支持渐进式披露（progressive disclosure）。意思是，SKILL.md正文可以只写核心流程，把详细的 API 文档、长示例、数据表放到references/目录里，然后在正文里用相对路径引用。agent 只有在真正需要时才会去读那些文件。

这个设计对复杂技能特别有用。比如我做过一个"数据库迁移"的 skill，正文只写了迁移的五个步骤和检查点，具体的字段类型映射表、历史迁移案例放在 references 里。这样日常触发时上下文占用很小，遇到疑难情况 agent 又能自己去查详细资料。

3.4 脚本与资源的调用方式

scripts/目录里的脚本，agent 可以通过执行命令来调用。这里有个安全考量：不是所有 agent 都允许任意执行脚本，Claude Code 会走权限确认流程（热词里"claude code 权限"就是这个）。我的建议是，脚本尽量写成幂等、无副作用、有明确输入输出的形式，比如校验类、格式化类、代码生成类，避免写会改数据库、删文件这种危险操作。

assets/里的模板文件，agent 可以直接读取内容然后填充。比如组件模板里放{{ComponentName}}这样的占位符，agent 读进来替换即可。这比让模型凭空生成要稳定得多，尤其是团队有固定代码风格的时候。

4. 实操落地：从零搭一个可用的 skill

4.1 环境准备与安装路径

先说 Claude Code 这边。skills 的存放位置通常有两个层级：用户级（~/.claude/skills/）和项目级（项目根目录下的.claude/skills/）。用户级的技能对你所有项目生效，项目级的只对当前仓库生效。我的习惯是：通用技能（比如 commit message 生成、代码审查）放用户级，项目特有的（比如业务组件规范）放项目级并提交到 git。

如果你在 Ubuntu 或者 Win11 上装 Claude Code，路径基本一致，Windows 下是C:\Users\你的用户名\.claude\skills\。热词里"ubuntu 安装 claude code""claude code win11"搜索量高，说明跨平台用户都不少，但 skills 的目录约定是统一的，这点不用担心。

Cursor 这边机制略有不同。Cursor 本身对 skills 的原生支持还在演进，实践中更多是用.cursor/rules/目录下的规则文件，或者通过 MCP（Model Context Protocol）把外部能力接进来。如果你在 Cursor 里想复刻 skills 的按需加载效果，可以用 rules 的 glob 匹配机制——让规则只在特定文件类型或目录下生效，达到类似"条件触发"的目的。

4.2 手把手写第一个 skill

我们做一个最实用的：符合团队规范的 React 组件生成器。

第一步，建目录：

mkdir -p ~/.claude/skills/react-component-generator/assets

第二步，写SKILL.md：

--- name: react-component-generator description: 当用户要求创建、新增或生成 React 函数组件时使用。适用于 TypeScript 项目，输出需符合 CSS Modules 样式方案与 named export 导出规范。不适用于类组件、Vue 组件或纯逻辑 hook。 --- # React 组件生成规范 ## 生成步骤 1. 确认组件名称，使用 PascalCase。 2. 在 `src/components/<ComponentName>/` 下创建三个文件： - `index.tsx`：组件实现 - `styles.module.css`：样式 - `index.ts`：统一导出 3. 组件必须使用函数式写法，禁止 class 组件。 4. Props 必须定义独立的 `interface`，命名为 `<ComponentName>Props`。 5. 禁止使用 `any`，未知类型用 `unknown` 并做类型收窄。 6. 导出使用 named export，禁止 default export。 ## 代码模板 参考 `assets/component.template.tsx`，将占位符替换为实际内容。 ## 反例 - 不要写成 `export default function Button() {}` - 不要在组件内直接写内联样式对象 - 不要省略 Props 类型定义

第三步，放模板文件assets/component.template.tsx：

import styles from './styles.module.css'; export interface {{ComponentName}}Props { // TODO: 定义 props } export function {{ComponentName}}({}: {{ComponentName}}Props) { return ( <div className={styles.container}> {/* TODO: 实现 */} </div> ); }

第四步，验证。重启 Claude Code 会话，输入"帮我创建一个 UserCard 组件"，观察它是否自动加载了这个 skill、是否按模板生成。如果没触发，八成是 description 写得不够明确，回去改。

4.3 参数与约束的写法技巧

写 skill 正文时，有几个我踩过坑总结出来的技巧。

用编号步骤而不是段落描述。模型对有序列表的执行遵循度明显高于散文。一个任务如果有固定流程，就老老实实写成 1、2、3。

约束要写成"必须/禁止"而不是"建议"。我早期写"建议使用 named export"，结果模型一半时候用 default。改成"禁止 default export"之后，遵守率接近 100%。

给反例比给正例更有效。正例模型容易过度模仿导致僵化，反例则能精准划出边界。上面那个 skill 里我特意写了三条反例，实测下来比写十条正例管用。

控制单个 skill 的职责。一个 skill 只干一件事。我见过有人把"生成组件 + 写测试 + 更新文档"塞进一个 skill，结果模型经常只做第一步就以为完成了。拆成三个 skill，用 description 区分触发条件，反而更稳。

4.4 在 Cursor 里的等效实践

Cursor 用户别急着走。虽然机制不同，但思路可以平移。在.cursor/rules/下建一个react-component.mdc：

--- description: React 组件生成规范 globs: src/components/**/*.tsx alwaysApply: false --- 生成 React 组件时： 1. 使用函数式组件 2. Props 定义独立 interface 3. 禁止 any 4. 使用 named export

globs让规则只在src/components/下的文件被操作时生效，alwaysApply: false表示不常驻。这就模拟了 skills 的按需加载。Cursor 的 rules 系统在触发精度上不如 Claude Code 的 skills，但胜在和编辑器深度集成，改代码时体验更顺。

5. 常见问题与排查技巧实录

5.1 skill 不触发怎么办

这是最高频的问题。排查顺序如下：

我遇到过一次特别隐蔽的：skill 目录名带了空格，导致加载失败但没有任何报错。所以目录名和 name 字段都用 kebab-case，别用空格和中文。

5.2 多个 skill 冲突怎么处理

当两个 skill 的 description 都匹配当前任务时，模型可能同时加载，导致指令打架。解决办法有两个：一是在 description 里写清互斥关系，比如"当 A 场景时使用，B 场景请用 xxx-skill"；二是合并成一个带分支的 skill，在正文里用"如果……则……否则……"来分流。

我的经验是，宁可合并也不要让两个 skill 职责重叠。skills 数量不是越多越好，清晰比丰富重要。

5.3 权限与安全边界

Claude Code 执行脚本时会弹权限确认，这是好事，别图省事关掉。热词里"claude code 权限"被搜这么多次，说明很多人被这个卡过。我的建议是：把常用脚本的权限规则写进项目配置，但永远不要给删除、覆盖、网络请求类操作开白名单。skill 再方便，也不能让它有能力悄悄改你的生产环境。

另外，从外部安装别人分享的 skill 时，一定要先读一遍 SKILL.md 和所有脚本。skill 本质上是能影响 agent 行为的代码，来源不明的 skill 和来源不明的 npm 包一样危险。

5.4 调试 skill 的实用手法

我常用的一个笨办法但很有效：在 skill 正文开头加一行<!-- DEBUG: skill loaded -->，然后让 agent 复述它读到的指令。如果它能说出这行注释，说明加载成功；如果行为不对，就能定位是加载问题还是指令理解问题。

还有一个技巧是临时把 description 改得极度具体，比如直接写"当用户输入'生成组件'四个字时使用"，先确认触发链路通了，再逐步放宽 description 到正常水平。这比一上来就调一个模糊的 description 要高效得多。

6. 进阶玩法：把 skills 变成团队资产

6.1 版本化与分发

skill 是文件，所以天然适合 git 管理。我的做法是建一个内部仓库team-agent-skills，每个 skill 一个目录，用 tag 标记版本。新同事入职，clone 下来软链到~/.claude/skills/就能用。这比写一份"AI 使用规范文档"要落地得多——文档没人看，skill 是 agent 直接执行的。

分发时注意一点：skill 里不要硬编码个人路径和密钥。我见过有人把 API key 写进 skill 的脚本里然后提交到仓库，这是重大事故。用环境变量，并且在 SKILL.md 里说明需要哪些环境变量。

6.2 与 MCP 的配合

MCP 解决的是"agent 能调用什么外部工具"，skills 解决的是"agent 在什么场景下怎么用这些工具"。两者是互补的。比如你有一个查数据库的 MCP server，再配一个"数据排查"的 skill，告诉 agent 排查数据问题时先查哪张表、按什么顺序、结果怎么呈现。这样 agent 的能力就从"能连数据库"升级到"会排查数据问题"。

6.3 持续迭代的节奏

skills 不是写完就完事的。我的习惯是每次发现 agent 做错了某件事，就问自己：这是偶发还是系统性问题？如果是系统性的，就回去改对应的 skill。几个月下来，我的 skill 库基本覆盖了日常 80% 的重复性任务，agent 的"靠谱程度"肉眼可见地提升。

这里有个心态要调整：别指望一次写出完美 skill。第一版能触发、能跑通就行，然后在真实使用中不断打补丁。我那个 React 组件 skill 改了不下十版，每版都是被实际踩坑逼出来的。

6.4 一个容易被忽略的细节：skill 的命名

最后分享一个小技巧。skill 的name字段虽然不直接参与触发判断，但会出现在 agent 的自我描述和日志里。用动词开头的命名，比如generate-react-component、review-pull-request、migrate-database-schema，比名词命名（react-component）更容易让 agent 在推理时建立"任务-技能"的映射。这个细节很小，但在我自己的使用中确实能感觉到触发准确率的差异。

如果你现在终端里还躺着一个装完没怎么用的 Claude Code，我建议你今天就挑一个最烦的重复任务，花二十分钟写成一个 skill。那种"agent 终于懂我了"的感觉，比调一百次 prompt 都来得实在。