1. 从每次都要重新教AI说起agent-skills到底在解决什么如果你最近半年深度用过 Claude Code、Cursor 这类 AI coding agent大概率经历过一种很具体的疲惫明明上周才跟它讲过这个项目的 API 返回体统一用{code, data, message}三层结构这周开个新会话它又给你写了个裸的return data。你不得不把同样的规范、同样的目录约定、同样的提交信息格式一遍又一遍地贴进对话里。这不是模型不够聪明而是会话之间没有记忆能力没有沉淀。agent-skills这个项目本质上就是在回答一个问题能不能把我希望 AI 怎么干活这件事从一次性的对话提示变成可复用、可版本管理、可被 agent 自动加载的技能包它的核心形态是一套围绕 skills 的组织方式和 CLI 工具链让开发者把项目规范、领域知识、操作流程写成结构化的 skill 文件AI coding agent 在需要的时候自动读取并遵循。关键词里的skills CLI、claude code skills 安装说的就是这套东西的落地方式。它适合谁三类人最该关注。第一类是已经在用 Claude Code 或 Cursor 做日常开发但每次都要重复交代背景的工程师第二类是团队里想把编码规范、review 标准固化下来让 AI 输出更可控的技术负责人第三类是刚接触 AI coding agent、还在摸索怎么让它听话的新手——因为 skill 机制恰恰是把玄学提示词变成工程化配置的最短路径。我自己的判断是提示词工程正在从个人技巧走向团队资产。你写一段好的 prompt只有你自己用你写一个 skill整个团队、所有会话、所有 agent 都能复用。这个差别用过一段时间之后感受会非常明显。下面我会把 agent-skills 的机制、安装、编写、踩坑、和 Cursor/Claude Code 的配合方式按我实际折腾下来的顺序讲清楚。2. skill 的加载机制为什么它比贴一大段提示词更靠谱2.1 渐进式披露agent 不是一次性读完所有内容很多人第一次接触 skill会误以为它就是把 system prompt 拆成文件。其实关键差异在加载时机。传统做法是你把一大堆规范塞进对话开头模型每轮都要带着这坨上下文跑token 烧得快而且长上下文里模型对中间部分的注意力会衰减——这就是所谓的lost in the middle。skill 的设计思路是渐进式披露progressive disclosureagent 启动时只加载每个 skill 的元信息名称、描述、触发条件这部分非常短只有当当前任务真的匹配到某个 skill 时才把它的完整内容读进来。打个比方这就像你办公室里有一整面工具墙你不需要每天上班先把所有工具的使用手册背一遍而是知道墙上第三格是电钻真要用的时候再去拿。这个机制带来的直接好处有两个。一是上下文预算省下来了你可以挂几十个 skill 而不炸上下文二是匹配精度更高因为 agent 是在理解任务之后才决定调哪个 skill而不是被一堆无关规范干扰。2.2 skill 的目录结构与元信息字段一个标准的 skill 通常是一个独立目录核心是一个带 frontmatter 的 Markdown 文件。结构大致长这样.claude/skills/ api-convention/ SKILL.md commit-style/ SKILL.md db-migration/ SKILL.md每个SKILL.md顶部的 frontmatter 是灵魂一般包含这几个字段--- name: api-convention description: 当需要编写或修改后端 API 接口时使用规定统一的返回体结构与错误码规范 ---这里有两个坑我必须提前说。第一description不是写给人看的简介是写给 agent 看的触发条件。很多人写成这个 skill 介绍了 API 规范结果 agent 根本不知道什么时候该用它。正确写法是描述什么场景下触发比如当需要新增接口、修改返回结构、定义错误码时使用。第二name要短且唯一别用中文、别带空格否则 CLI 加载时容易出问题。frontmatter 下面的正文才是真正的规范内容。它可以包含代码示例、检查清单、反例对照格式随意但建议控制在几百行以内——太长了即使被加载也会稀释注意力。2.3 触发匹配的底层逻辑与常见误判agent 判断要不要用某个 skill靠的是把当前任务描述和所有 skill 的description做语义匹配。这意味着你的 description 写得越贴近真实任务的语言命中率越高。我实测下来如果 description 里包含用户可能说的原话比如加个接口改返回格式命中率会明显好于纯书面语。反过来误判也常见。典型情况是 description 写得太宽泛比如处理所有代码相关任务结果 agent 在任何场景都想加载它反而干扰了真正该用的 skill。我的经验是一个 skill 只解决一类事description 里明确写出不适用的边界。比如仅用于后端接口不涉及前端组件这样能显著降低误触发。3. 从零装好 skills CLI环境、路径与验证3.1 安装前的环境确认skills CLI 的安装本身不复杂但前置环境没弄对后面会一直报错。先确认三件事Node.js 版本建议 18 LTS 及以上。低于 16 的版本在解析某些依赖时会直接失败。用node -v确认。包管理器npm、pnpm、yarn 都行但团队里最好统一否则 lock 文件会打架。我个人偏好 pnpm装得快、磁盘占用小。目标 agent 的配置目录Claude Code 一般读项目根目录下的.claude/skills/Cursor 的规则体系略有不同后面单独讲。先搞清楚你的 agent 从哪读 skill再决定装到哪。提示如果你在 Windows 上折腾路径分隔符和权限问题会比 macOS/Linux 多一些。建议在 WSL 里操作能省掉大量莫名其妙的报错。3.2 安装命令与全局/项目级的选择安装方式通常有两种全局安装和项目级安装。全局安装让你在任何目录都能用 CLI 命令项目级安装则把 skill 跟着仓库走方便团队共享。# 全局安装 CLI 工具 npm install -g skills-cli-package # 或者在项目里作为开发依赖 pnpm add -D skills-cli-package装完之后第一件事是验证skills --version skills listskills list会列出当前能识别到的所有 skill。如果输出为空说明它没找到 skill 目录这时候要检查你的工作目录对不对或者配置里指定的路径是否正确。3.3 目录放错位置是最高频的翻车点我见过最多的新手问题就是 skill 写好了但 agent 死活不加载。九成情况是目录放错了。这里有个容易混淆的点CLI 工具扫描的路径和 agent 运行时读取的路径可能不是同一个。稳妥的做法是以 agent 官方文档里写的路径为准。对 Claude Code 来说项目级 skill 放.claude/skills/用户级放~/.claude/skills/。放好之后重启 agent 会话不是重开终端是重开会话让它重新扫描。验证 skill 是否真的被加载有个笨但有效的办法在对话里直接问 agent你现在有哪些可用的 skill它一般会列出来。如果没列出来就是没加载成功别急着怀疑 skill 内容写得不好。4. 手写第一个 skill把接口规范变成可复用资产4.1 选一个高频、边界清晰的场景切入第一个 skill 别贪大。选一个你每天都在重复交代、且规则明确的场景。我推荐从API 返回体规范或Git 提交信息格式入手因为这两类规则边界清晰、容易验证效果。以 API 规范为例先想清楚你要约束什么返回体的字段结构、成功和失败的区分方式、错误码的命名规则、分页字段的统一叫法。把这些写成清单就是 skill 的正文。4.2 写 description 的正确姿势前面强调过description 决定触发。给你一个我实际在用的写法对比写法内容效果错误示范介绍后端 API 的返回规范agent 不知道何时触发命中率低正确示范当新增接口、修改接口返回结构、定义错误码或分页字段时使用场景明确命中率高差别就在于前者描述这是什么后者描述什么时候用。这个思路可以套用到所有 skill 上。4.3 正文写法清单 正反例 检查项正文我建议用三段式规则清单、正例、反例。模型对对比特别敏感给它看一个错误示范比讲十句抽象规则都管用。## 返回体结构 所有接口统一返回 - code: 业务状态码0 表示成功非 0 表示失败 - data: 业务数据失败时为 null - message: 提示信息成功时可为空字符串 ## 正例 { code: 0, data: { id: 1 }, message: } ## 反例禁止 直接返回裸数据{ id: 1 } 用 HTTP 状态码代替业务码200 表示成功、500 表示失败最后加一个提交前自查清单让 agent 在生成代码后自己核对一遍。这一步能明显减少低级错误。4.4 用真实任务验证 skill 是否生效写完别急着庆祝拿一个真实任务测。比如让 agent新增一个查询用户列表的接口然后看它返回的结构是否符合你的规范。如果不符合先别改 skill 正文先检查它到底有没有加载这个 skill——很多时候是没触发而不是内容不对。验证通过后你会发现一个很爽的变化新会话里不用再交代背景了。这就是 skill 相对 prompt 的核心价值。5. 在 Claude Code 与 Cursor 里让 skill 真正跑起来5.1 Claude Code 的 skill 加载与权限配合Claude Code 对 skill 的支持相对直接把 skill 放进约定目录重开会话即可。但有个细节值得注意skill 只是告诉它怎么做不改变它的权限边界。也就是说skill 里写了可以自动执行数据库迁移不代表它真的有权限跑那条命令——权限是另一套机制管的。所以如果你希望某些操作能自动执行得在权限配置里单独放开而不是指望 skill 帮你绕过确认。这两件事分开理解能少走很多弯路。5.2 Cursor 的规则体系与 skill 的对应关系Cursor 的规则Rules机制和 skill 思路相通但组织方式不同。Cursor 更强调项目规则和用户规则的分层通常放在.cursor/rules/下用.mdc文件描述。它同样支持按场景触发逻辑上和 skill 的 description 匹配是一回事。如果你同时用 Claude Code 和 Cursor一个务实的做法是把核心规范写成一份 Markdown两边各自用适配的格式引用。别维护两套内容否则改了一边忘了另一边迟早出乱子。5.3 多 agent 协作时 skill 的复用策略现在很多人不止用一个 agent可能 Claude Code 写后端、Cursor 写前端、还有别的工具做 review。这时候 skill 的复用就很重要。我的建议是把 skill 当成项目文档的一部分纳入版本控制放在仓库里谁用哪个 agent 谁自己去适配加载路径。这样规范只有一份不会因为工具切换而漂移。场景推荐做法单人单 agentskill 放项目目录随仓库走单人多 agent一份内容多份适配配置团队协作skill 进仓库review 时一并检查跨项目复用抽成独立包用 CLI 分发6. 踩过的坑skill 不生效、误触发、内容漂移6.1 skill 写了但 agent 视而不见这是最高频的问题。排查链路我总结成一条线先确认目录对不对再确认会话有没有重启再确认 description 有没有写触发场景最后才怀疑内容。绝大多数情况卡在前两步。我遇到过有人把 skill 放在skills/而不是.claude/skills/差了那个点agent 就是找不到。6.2 description 太宽导致到处乱触发反过来description 写太宽也会出问题。有个朋友写了个代码质量规范的 skilldescription 是处理所有代码任务结果 agent 写个 CSS 都要加载它把上下文挤得满满当当真正该用的前端 skill 反而没触发。skill 的粒度要细一个 skill 一件事这是铁律。6.3 规范更新了但 skill 没同步skill 进了仓库之后很容易变成写完就忘的僵尸文件。规范改了、接口结构调整了skill 还停留在旧版本agent 照着旧规范生成代码反而比不用还糟。我的做法是把 skill 的更新纳入 code review 流程改接口的时候顺手看一眼相关 skill 要不要改。这跟维护文档是一个道理只是对象换成了 AI。6.4 把 skill 当成万能提示词堆砌最后一个坑最隐蔽有人把 skill 当成许愿池什么都往里塞一个文件几百行从编码规范到部署流程到团队文化全写进去。结果 agent 加载了也抓不住重点。skill 要短、要聚焦、要可执行。宁可拆成五个小 skill也别写一个巨型 skill。7. 我实际用下来的一些体会折腾 agent-skills 这段时间最大的感受是它把提示词这件事从手艺变成了工程。以前调 prompt 靠感觉现在写 skill 靠的是场景拆解 边界定义 正反例对照这套方法论其实和写技术文档、写测试用例是相通的。另一个体会是别指望一次写对。我第一个 skill 改了四五版才稳定前几版要么触发不准要么内容太啰嗦。这很正常skill 本身也是要迭代的。你可以先写个粗糙版本用起来遇到不生效就调 description遇到输出不对就补正反例慢慢就顺了。还有个小技巧给 skill 加一个最后更新日期和适用版本的注释。团队里人多的时候这能帮你快速判断某个 skill 是不是过期了省得踩到旧规范的坑。这个习惯我是从维护 API 文档那儿搬过来的用在 skill 上一样好使。如果你现在还在每次开新会话都重新交代背景真的建议花半小时写第一个 skill。那种AI 终于记住我们项目怎么干活了的感觉值得你试一次。