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.tsxSKILL.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. 实操落地从零搭一个可用的 skill4.1 环境准备与安装路径先说 Claude Code 这边。skills 的存放位置通常有两个层级用户级~/.claude/skills/和项目级项目根目录下的.claude/skills/。用户级的技能对你所有项目生效项目级的只对当前仓库生效。我的习惯是通用技能比如 commit message 生成、代码审查放用户级项目特有的比如业务组件规范放项目级并提交到 git。如果你在 Ubuntu 或者 Win11 上装 Claude Code路径基本一致Windows 下是C:\Users\你的用户名\.claude\skills\。热词里ubuntu 安装 claude codeclaude code win11搜索量高说明跨平台用户都不少但 skills 的目录约定是统一的这点不用担心。Cursor 这边机制略有不同。Cursor 本身对 skills 的原生支持还在演进实践中更多是用.cursor/rules/目录下的规则文件或者通过 MCPModel 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命名为 ComponentNameProps。 5. 禁止使用 any未知类型用 unknown 并做类型收窄。 6. 导出使用 named export禁止 default export。 ## 代码模板 参考 assets/component.template.tsx将占位符替换为实际内容。 ## 反例 - 不要写成 export default function Button() {} - 不要在组件内直接写内联样式对象 - 不要省略 Props 类型定义第三步放模板文件assets/component.template.tsximport 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 exportglobs让规则只在src/components/下的文件被操作时生效alwaysApply: false表示不常驻。这就模拟了 skills 的按需加载。Cursor 的 rules 系统在触发精度上不如 Claude Code 的 skills但胜在和编辑器深度集成改代码时体验更顺。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。排查顺序如下现象可能原因排查方法完全不触发目录位置错误确认在~/.claude/skills/或.claude/skills/下完全不触发frontmatter 格式错误检查 YAML 的---是否闭合、缩进是否正确偶尔触发description 太宽泛加入具体触发词和排除条件该触发时不触发description 太窄补充同义场景描述触发但行为不对正文指令模糊改成编号步骤 必须/禁止句式我遇到过一次特别隐蔽的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 都来得实在。