1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你最近半年深度用过 Claude Code、Cursor 这类 AI coding agent大概率经历过这样一种循环新开一个会话agent 对你的项目结构、代码规范、提交习惯一无所知你得重新贴一遍上下文重新解释我们团队用 pnpm 不用 npm测试文件放在__tests__而不是test提交信息要遵循 Conventional Commits。解释完这一轮会话用着用着上下文爆了再开一个又得从头来一遍。这个循环的本质问题是agent 的能力是通用的但你的项目是具体的。通用能力靠模型本身具体知识得靠你喂。而喂这件事如果每次都靠手动粘贴那 agent 带来的效率提升会被反复的重复劳动吃掉一大半。agent-skills这个项目要解决的就是把这层项目专属知识从一次性对话里抽出来变成可复用、可版本管理、可被 agent 自动加载的技能包。你可以把它理解成给 AI coding agent 装的一套岗位说明书 操作手册——agent 在动手之前先读一遍你写好的技能定义知道这个项目里什么该做、什么不该做、按什么顺序做。它适合谁三类人最该关注。第一类是已经在用 Claude Code 或 Cursor 做日常开发、但还在靠每次手动交代的开发者第二类是想把团队规范固化下来、让多个成员用同一套 agent 行为的团队负责人第三类是刚接触 AI coding agent、还没建立起自己工作流的新手——从 skills 入手比从零摸索提示词要省事得多。需要先说清楚一点agent-skills本身不是一个模型也不是一个 IDE 插件它更像是一套约定和工具链围绕技能skill这个单位来组织 agent 的行为。下面我会从它的核心概念讲起一路讲到怎么落地、怎么避坑。2. 拆开 agent-skills 的核心概念skill 到底是什么2.1 skill 不是提示词模板而是带触发条件的知识单元很多人第一反应会把 skill 等同于一段写好的提示词。这个理解偏了。普通的提示词模板是你贴进去它才生效而 skill 的关键特征是带触发条件——agent 在特定场景下会自己去查、自己去用。一个 skill 通常包含三部分信息什么时候用触发描述、用了之后做什么操作指令、做的时候参考什么附带的脚本、模板、参考资料。触发描述是灵魂它决定了 agent 能不能在正确的时机想起这个 skill。写得好的触发描述会让 agent 在遇到用户要求提交代码时自动去查提交规范 skill写得差的agent 根本不知道有这么个东西存在。这里有个反直觉的点skill 的价值不在于写得多全而在于触发得准。我见过有人把整个项目的编码规范塞进一个 skill结果 agent 每次加载都要吃掉大量上下文反而拖慢了响应、挤占了真正需要推理的空间。正确的做法是按场景拆分——提交规范一个、测试写法一个、API 设计约定一个各自独立触发。2.2 渐进式加载为什么 skill 不会一次性撑爆上下文这是 agent-skills 设计里最值得琢磨的一点。如果所有 skill 在会话开始时就全部加载进上下文那和把整个 wiki 贴进去没区别上下文窗口很快就不够用了。实际机制是渐进式披露progressive disclosure会话开始时agent 只加载每个 skill 的元信息——也就是名字和触发描述这部分很轻量几十个 skill 加起来也就几百个 token。当 agent 判断当前任务命中了某个 skill 的触发条件才去读取那个 skill 的完整内容。用完即走不常驻。这个设计带来的直接好处是你可以放心地积累几十个 skill而不用担心上下文被撑爆。代价是触发描述必须写得足够精准否则 agent 判断不出来该不该加载。这就像图书馆的索引卡——卡片本身很短但必须准确指向对应的书索引写错了书再好也找不到。2.3 skill 和 MCP、和普通工具调用的区别刚接触的人容易把 skill 和 MCPModel Context Protocol搞混。两者不是一回事也不冲突。MCP 解决的是agent 能连到什么外部能力——比如连数据库、连文件系统、连某个 API。它是能力接入层。而 skill 解决的是agent 在特定场景下该怎么做——它是行为知识层。一个 skill 里完全可以指导 agent 去调用某个 MCP 工具但 skill 本身不提供工具。打个比方MCP 是给 agent 配的工具箱skill 是告诉 agent修水管的时候先关总阀、再拆接头的操作手册。工具箱再全没有手册agent 也可能上来就拆接头喷一身水。理解了这三层关系后面讲落地就顺了。3. 目录结构与文件组织skill 在磁盘上长什么样3.1 一个 skill 的最小结构skill 在文件系统里通常以目录形式存在一个 skill 一个目录。最小结构长这样skills/ commit-convention/ SKILL.mdSKILL.md是核心文件里面用 frontmatter 写元信息正文写操作指令。一个典型的SKILL.md开头是这样的--- name: commit-convention description: 当用户要求提交代码、生成 commit message、或执行 git commit 时使用。定义本项目的提交信息格式规范。 --- # 提交信息规范 本项目遵循 Conventional Commits 规范格式为 type(scope): subject type 取值feat / fix / docs / style / refactor / test / chore ...description字段就是前面说的触发描述它决定了 agent 什么时候会加载这个 skill。这个字段值得反复打磨后面第 5 节会专门讲怎么写。3.2 带附属资源的 skill 怎么组织当 skill 需要附带脚本、模板、参考文档时目录会扩展成skills/ api-design/ SKILL.md templates/ rest-endpoint.md graphql-query.md scripts/ validate-schema.sh references/ error-code-table.md这里有个重要的组织原则SKILL.md 正文里只写什么时候读哪个附属文件不要把附属文件的内容抄进来。附属文件是懒加载的——agent 只有在 SKILL.md 里被明确指引时才会去读。这样即使一个 skill 附带了几十页参考资料也不会在加载 skill 的瞬间全部灌进上下文。我自己的习惯是把附属资源分成三类templates/放可直接套用的模板scripts/放可执行的校验或生成脚本references/放查阅性质的表格和清单。分类清楚之后SKILL.md 里的指引也更好写——生成 REST 接口时读 templates/rest-endpoint.md比参考相关模板要明确得多。3.3 多 skill 项目的目录约定当 skill 数量上到十几个目录组织就开始影响可维护性了。常见的做法是按领域分组skills/ coding/ commit-convention/ test-writing/ error-handling/ review/ pr-review-checklist/ security-scan/ docs/ changelog-format/ api-doc-template/分组本身不影响 agent 的加载逻辑agent 是按 description 匹配的不是按目录层级但影响人的维护效率。分组之后找某个 skill 改起来快也方便判断这个领域我是不是覆盖全了。注意不同工具对 skill 目录的默认扫描路径不一样。Claude Code 和 Cursor 各有自己的约定位置落地前先确认你的工具从哪个目录读 skill别写完发现根本没被扫描到。这一点在第 6 节会展开。4. 触发机制深挖agent 是怎么想起某个 skill 的4.1 匹配发生在哪一步理解触发时机才能理解为什么有些 skill 死活不生效。整个流程大致是用户发出请求 → agent 拿到请求和当前上下文 → agent 对照已加载的 skill 元信息列表判断哪些 skill 相关 → 加载命中的 skill 完整内容 → 结合 skill 指令执行任务。关键在第三步判断相关性这一步是模型做的不是规则引擎做的。这意味着触发不是精确的字符串匹配而是语义判断。好处是灵活——用户说帮我存一下代码和commit 一下都能命中提交规范 skill坏处是不确定——description 写得含糊模型可能判断不出来。4.2 为什么你的 skill 没被触发这是实操中最高频的问题。我总结下来skill 不触发基本逃不出这几个原因现象根因修法完全不触发description 太抽象没写具体场景把用于代码提交改成当用户要求提交代码、生成 commit message 时使用偶尔触发触发词覆盖不全补上同义表达如提交commit存档保存进度触发太频繁description 范围过宽收窄场景避免用于所有编码任务这种写法触发了但没用对SKILL.md 正文指令不清晰把操作步骤写成有序列表明确输入输出我踩过最典型的一个坑早期写了个 skilldescription 写的是帮助处理数据库相关任务。结果 agent 几乎从不加载它——因为数据库相关任务太宽泛模型判断不出具体什么时候该用。后来改成当需要编写 SQL 查询、设计表结构、或排查慢查询时使用命中率立刻上来了。4.3 触发描述和正文指令的分工一个常见的误区是把该写在正文里的操作细节塞进 description。description 的职责只有一个让 agent 判断现在该不该加载我。它不该承担教学职责。正确的分工是description 回答什么时候用正文回答怎么用。description 里出现具体命令、代码片段、详细步骤都是错位的——那些属于正文。description 越短越聚焦触发判断越准。5. 写一个高质量 skill 的实操路径5.1 从重复三次以上的事开始不要一上来就规划我要写二十个 skill。最务实的起点是回顾你最近一周和 agent 的对话找出你重复交代过三次以上的事情。那件事就是你的第一个 skill。这个筛选标准很有效因为它同时满足两个条件一是高频值得固化二是你已经手动做过很多遍知道正确的做法是什么写起来不会空。反过来那些你只做过一次、还没摸清门道的任务先别急着写成 skill——写出来大概率是错的还会误导 agent。5.2 正文指令的写法像给新人写交接文档SKILL.md 正文的读者是 agent但写法应该参照给一个聪明但完全不了解你项目的新人写交接文档。几个要点先给结论再给细节。开头一句话说清这个 skill 管什么别铺垫。步骤用有序列表。agent 对有序步骤的执行准确率明显高于散文式描述。给正例也给反例。提交信息写成fix: 修复登录bug是正例不要写成修复了一下是反例。反例能有效防止 agent 自由发挥。明确边界。写清楚这个 skill 不负责什么避免 agent 越界。举个我实际在用的例子测试写法 skill 的正文片段# 测试文件写法 ## 步骤 1. 测试文件放在与被测文件同级的 __tests__ 目录下 2. 文件名格式为 被测文件名.test.ts 3. 使用 vitest不用 jest 4. 每个 describe 块对应一个导出函数 ## 正例 __tests__/formatDate.test.ts ## 反例 test/formatDate.spec.js 目录错、后缀错、框架错这种写法 agent 执行起来几乎不会跑偏。5.3 用真实任务验证而不是看起来对skill 写完别急着收工。拿三个真实任务去跑一个应该触发它的、一个不该触发它的、一个边界模糊的。看 agent 的实际行为是否符合预期。我自己的验证清单是这样的明确该触发的任务agent 是否加载了 skill 并按指令执行明确不该触发的任务agent 是否克制住了没乱加载边界任务agent 的判断是否和你的直觉一致不一致的话是 description 的问题还是你预期的问题第三项最有价值。很多时候你会发现不是 skill 写错了而是你自己都没想清楚这件事到底该不该走这个流程。这种时候改 skill 之前先改自己的认知。5.4 迭代节奏小步改别大重写skill 的维护和代码一样忌讳大重写。每次只改一个点——要么调 description要么补一条正文指令要么加一个反例——然后立刻验证。一次改太多出问题了你都不知道是哪处改动导致的。我一般会给每个 skill 在正文末尾留一个变更记录小节简单记一下每次改了什么、为什么改。这个习惯在 skill 数量多了之后特别有用能避免这个 skill 为什么长这样的困惑。6. 在 Claude Code 和 Cursor 里落地路径、配置与差异6.1 Claude Code 的 skill 加载位置Claude Code 对 skill 的支持是通过约定目录实现的。项目级的 skill 通常放在项目根目录下的特定文件夹里会话启动时自动扫描。具体路径以你所用版本的文档为准——这类工具的目录约定迭代较快写死一个路径容易过时。落地时的关键动作是确认扫描路径 → 把 skill 目录放进去 → 新开会话验证是否被识别。验证方法很简单直接问 agent你现在有哪些可用的 skill看它列出来的清单里有没有你刚放的。提示项目级 skill 和用户级 skill 是两回事。项目级的跟着仓库走团队成员拉下来就有用户级的只在你本机生效。团队协作场景优先用项目级个人习惯类的用用户级。6.2 Cursor 场景下的注意事项Cursor 的 skill 机制和 Claude Code 不完全一样它更依赖 rules 体系和上下文注入。在 Cursor 里落地 agent-skills 的思路通常是把 skill 的内容转成 Cursor 能识别的规则文件或者通过项目内的约定文件让 agent 读取。这里有个实操差异值得注意Cursor 的规则触发更偏向文件路径和 glob 匹配而 Claude Code 的 skill 触发更偏向语义判断。这意味着同一套 skill 内容在两个工具里可能需要不同的触发描述写法。在 Cursor 里你可能需要明确写当编辑src/api/**下的文件时应用此规则而在 Claude Code 里语义化的当设计 API 接口时使用就够了。6.3 两个工具的能力对照维度Claude CodeCursor触发方式语义判断为主路径/glob 匹配为主加载粒度按 skill 整体加载按规则文件加载附属资源支持懒加载附属文件依赖上下文引用团队共享项目级目录随仓库走规则文件随仓库走适合场景复杂流程、多步骤任务文件类型相关的规范约束这张表不是绝对的两个工具都在快速迭代。但它能帮你判断同一份知识在哪个工具里用什么形式表达最有效。我的经验是流程性的知识先做什么后做什么在 Claude Code 里表达更自然约束性的知识这类文件必须怎么写在 Cursor 里表达更直接。6.4 跨工具复用的一份内容两份表达如果你同时用两个工具不必维护两套完全独立的内容。做法是核心知识写一份触发层各写各的。比如API 设计规范这份知识正文内容两个工具共用但 Claude Code 那边配一个语义化的 descriptionCursor 那边配一个 glob 规则指向src/api/**。知识不重复触发各适配。7. 踩坑实录那些让我返工的细节7.1 description 写成了功能说明书我最早写 skill 时description 写的是这个 skill 提供了代码格式化的能力包括缩进、换行、命名规范等。结果 agent 几乎不触发它。问题在于这句话描述的是skill 有什么功能而不是什么时候该用它。模型需要的是场景信号不是功能清单。改成当用户要求格式化代码、统一命名风格、或调整缩进时使用之后触发率立刻正常了。这个坑的本质是站在使用者的场景角度写而不是站在作者的介绍角度写。7.2 一个 skill 塞了太多不相关的内容有段时间我图省事把代码规范 提交规范 测试规范全塞进一个 skill。结果是agent 每次因为提交任务加载这个 skill却顺带读进了一大堆代码规范和测试规范上下文被无谓占用而且执行提交任务时还可能被无关指令干扰。拆成三个独立 skill 之后不仅上下文省了每个 skill 的指令也更聚焦、执行更准。skill 的粒度应该按触发场景来切而不是按知识领域来切。同一个领域里如果触发场景不同就该拆开。7.3 附属文件路径写成了绝对路径skill 里的附属文件引用一定要用相对于 skill 目录的路径别用绝对路径。绝对路径在你本机跑得通团队成员拉下来就全断了。这个坑很蠢但真的常见——尤其是从本机调试直接复制粘贴的时候。7.4 忘了处理skill 之间的冲突当两个 skill 对同一件事给出不同指令时agent 会困惑。比如一个 skill 说测试文件放__tests__另一个旧 skill 说测试文件放test。这种冲突不会报错但会导致 agent 行为不稳定。我的做法是定期做一次skill 审计把所有 skill 的正文过一遍看有没有互相矛盾的指令。有冲突就合并或废弃旧的。skill 数量上到二十个以上这个审计就很有必要了。7.5 把 skill 当成了一次性写完就完事skill 是活的。项目规范变了、工具版本升级了、团队习惯了改了skill 都得跟着改。我见过团队把 skill 写完就扔在那半年后新人拉下来用发现里面的规范早就和实际代码对不上了反而误导 agent。建议把 skill 的维护纳入常规流程——比如每次代码规范变更时顺手检查相关 skill 要不要更新。这和在改代码时顺手更新文档是一个道理。8. 从个人用到团队用skill 的协作与演进8.1 把 skill 纳入版本管理skill 是项目知识的一部分应该和代码一起进版本库。这样带来的好处很直接新人拉下仓库就自带一套 agent 行为规范不用口口相传skill 的每次变更都有记录能追溯为什么这条规范是这样。目录上我建议把 skill 放在项目根目录下一个显眼的位置并在 README 里说明它的作用和维护方式。别藏在某个深层目录里否则没人会想起来维护它。8.2 团队协作中的分工skill 的维护不该是某一个人的事。比较顺的分工是每个领域的负责人维护自己领域的 skill。写 API 的人维护 API 设计 skill管发布的人维护 changelog skill。这样 skill 的内容质量有保障也不会全压在一个人身上。配套的机制是变更评审skill 的修改走和代码一样的评审流程。这听起来有点重但能有效防止某人随手改了一条规范结果全团队的 agent 行为都变了这种事故。8.3 什么时候该废弃一个 skillskill 不是越多越好。当出现这些信号时就该考虑废弃或合并触发率极低说明场景不成立、内容和其他 skill 大量重叠说明该合并、规范已经过时且没人维护说明是负担。废弃时别直接删先在正文里标记 deprecated 并说明替代方案观察一段时间再清理。这样能给还在依赖它的成员一个过渡期。8.4 一个团队落地的真实节奏如果让我给一个团队规划落地节奏大概是这样第一周每个人梳理自己重复交代最多的事各写一到两个 skill第二周团队一起过一遍合并重复的、拆开过大的第三周把 skill 纳入版本库和评审流程之后就是持续迭代。别追求一步到位。skill 体系是长出来的不是设计出来的。先跑起来再优化。9. 我个人的几条经验用 agent-skills 这套东西大半年最深的体会是它的价值不在让 agent 更聪明而在让 agent 更懂你。模型能力是公共的但项目知识是私有的skill 就是把私有知识固化下来的载体。几条具体的经验。第一从痛点出发别从体系出发。先解决那个让你最烦的重复劳动别一上来就想着建一套完整的 skill 体系。第二description 值得花一半的时间打磨。触发不准正文写得再好也白搭。第三定期审计别让 skill 腐烂。过时的 skill 比没有 skill 更糟因为它会主动误导 agent。最后一个技巧如果你不确定某个 skill 该不该拆就问自己这两部分内容会不会在同一个任务里同时用到。会就放一起不会就拆开。这个判断标准简单但很准。
