1. agent-skills 到底在解决什么问题第一次看到agent-skills这个词很多人会以为是某个新出的 AI 模型或者又一个套壳工具。实际上它要解决的是一个非常具体、非常痛的问题AI coding agent 每次开新会话都像失忆一样你得反复告诉它项目规范、测试怎么写、提交信息怎么格式化。我最早用 Claude Code 的时候每次让它写代码都要在 prompt 里重复一遍用 pytest 写测试函数命名用 snake_case不要直接改 main 分支。写三五次还行写到第十次的时候我就想这东西难道不能记住吗agent-skills就是干这个的。它本质上是一套可复用的技能定义文件放在项目目录里AI coding agent 启动时自动读取相当于给 agent 装了一本项目员工手册。你写一次之后每次会话它都自动遵守。这个项目适合谁三类人已经在用 Claude Code、Cursor、Windsurf 这类 AI coding agent 的开发者想让 agent 输出更稳定团队里多人共用 AI 辅助编码需要统一代码风格和流程想把自己的工作流沉淀成可复用资产而不是每次靠记忆和复制粘贴关键词里提到的test-driven-development、skills CLI、AI coding agents其实指向同一个核心把开发规范从人口头交代变成文件系统里的结构化定义。我实测下来最大的感受是这东西的价值不在于让 AI 变聪明而在于让 AI 变一致。同一个项目里今天写的代码和下周写的代码风格、测试覆盖、提交习惯能保持统一这才是工程上真正值钱的地方。2. agent-skills 的文件结构与加载机制2.1 一个 skill 文件里到底写了什么agent-skills的核心单位是 skill 文件通常放在项目根目录的.agent/skills/或者.claude/skills/下面不同 agent 工具路径略有差异但逻辑一致。每个 skill 是一个 Markdown 文件带 YAML frontmatter。我拿一个实际在用的 TDD skill 举例--- name: test-driven-development description: 强制在实现功能前先写失败测试 trigger: 当用户要求新增功能或修复 bug 时 --- ## 规则 1. 收到功能需求后先写一个会失败的测试 2. 运行测试确认它确实失败红 3. 写最小实现让测试通过绿 4. 重构保持测试通过 5. 不允许在没有测试的情况下提交实现代码 ## 测试文件命名约定 - 单元测试test_module.py - 集成测试test_module_integration.py - 测试函数名必须描述行为如 test_returns_empty_list_when_no_match这个文件的关键在于trigger字段。它不是每次都加载而是 agent 判断当前任务匹配 trigger 时才激活。这就避免了把所有规则一股脑塞进 context 导致 token 浪费。2.2 加载顺序与优先级这里有个很多人踩过的坑skill 的加载是有优先级的项目级覆盖用户级用户级覆盖全局默认。我一开始把所有 skill 都放在用户目录~/.claude/skills/下结果换项目的时候发现有些规则不适用比如 A 项目用 pytestB 项目用 jest全局 skill 里写死 pytest 就出问题了。正确的做法是分层层级路径适用场景全局~/.claude/skills/个人通用习惯如提交信息格式项目project/.claude/skills/项目特定规范如测试框架、目录结构会话临时 prompt一次性任务不沉淀提示项目级 skill 建议提交到 git这样团队每个人拉下来就自动生效不需要口头同步规范。2.3 为什么用 Markdown 而不是 JSON/YAML我一开始觉得用 JSON 定义规则更工程化后来发现 Markdown 才是对的。原因是skill 最终是要喂给 LLM 的而 LLM 对自然语言 结构化标记的混合格式理解最好。纯 JSON 反而会让模型把注意力放在语法上而不是语义上。而且 Markdown 允许你写解释性文字。比如你可以写为什么这条规则存在agent 理解了意图之后遇到规则没覆盖的边界情况也能做出合理判断。这一点是纯配置格式做不到的。3. 从零搭建一套可用的 skills 库3.1 先别急着写先盘点你重复说了什么我的经验是不要一上来就设计一套完美的 skill 体系。正确做法是先记录一周把你每次对 AI 重复说的话记下来。我当时记了这么几条高频重复用 pytest不要用 unittest提交信息用 conventional commits 格式改代码前先看有没有对应测试不要动 migrations 目录里的历史文件API 返回统一用{code, data, message}结构这五条就是我的第一批 skill。每条对应一个文件内容不超过 50 行。3.2 写 skill 的三个原则原则一一条 skill 只干一件事。我见过有人把测试规范 提交规范 代码风格塞进一个文件结果 trigger 很难写要么全触发要么全不触发。拆开之后每个 skill 的 trigger 都很精准。原则二规则要可验证。写高质量代码这种规则等于没写。要写成函数不超过 50 行每个 public 方法必须有 docstring这种 agent 能自查的。原则三给反例。这是我从实践中总结的最有用的一条。光说要怎么做不够加一句不要怎么做效果翻倍。比如## 正确 def get_user(user_id: int) - User: ... ## 错误不要这样 def get_user(id): # 缺少类型标注参数名过于简略 ...3.3 用 skills CLI 管理版本关键词里提到的skills CLI是配套的命令行工具主要用来列出、启用、禁用 skill。我常用的几个命令# 列出当前生效的所有 skill skills list # 查看某个 skill 的详细内容和来源路径 skills show test-driven-development # 临时禁用某个 skill调试时很有用 skills disable commit-convention # 重新启用 skills enable commit-convention调试 skill 的时候skills show特别有用。因为有时候你以为某个 skill 生效了实际上路径放错了根本没加载。用这个命令能立刻确认。注意不同 agent 工具的 CLI 命令名可能不同有的叫agent skills有的直接集成在工具内部。核心逻辑都是 list/show/enable/disable 这四个动作。4. 把 TDD 真正落地到 agent 工作流里4.1 为什么 TDD 是最值得做成 skill 的在所有 skill 里test-driven-development是投入产出比最高的一个。原因是AI 天然倾向于先写实现再补测试而且补的测试往往是验证实现正确而不是验证需求正确。我踩过的坑让 agent 写一个用户注册功能它先写了实现然后写了个测试测试内容是调用 register 函数返回 200。这个测试毫无意义因为它只是复述了实现的行为没有验证任何业务规则。做成 skill 之后agent 的行为变了。它会先问注册需要满足哪些规则然后针对每条规则写测试def test_register_fails_when_email_already_exists(): ... def test_register_fails_when_password_too_short(): ... def test_register_succeeds_with_valid_input(): ...4.2 TDD skill 的完整配置我把实际在用的配置贴出来你可以直接抄--- name: test-driven-development description: 强制红绿重构循环 trigger: 新增功能、修复 bug、重构代码 --- ## 强制流程 1. 理解需求后先列出所有需要验证的行为 2. 为每个行为写一个测试测试名描述行为而非实现 3. 运行测试确认全部失败 4. 逐个实现每次只让一个测试通过 5. 全部通过后重构重构期间测试必须保持绿色 ## 禁止事项 - 禁止先写实现再补测试 - 禁止测试中 mock 被测函数本身 - 禁止一个测试断言多个不相关的行为 - 禁止跳过确认测试失败这一步 ## 测试命名模板 test_动作_条件_预期结果 示例 - test_login_fails_when_password_wrong - test_cart_total_includes_tax4.3 实测中的意外情况用了两个月我发现两个问题。问题一agent 有时会假装测试失败。它会写一个测试然后说测试失败了现在开始实现但实际上根本没运行测试。解决办法是在 skill 里加一条必须展示测试运行的实际输出。问题二小改动也走完整 TDD 流程太重。改个错别字也要先写测试就很荒谬。所以我在 trigger 里加了限定仅当涉及逻辑变更时触发纯文案、格式、注释修改不触发。这两个调整之后TDD skill 才真正变得可用而不是碍事。5. 多 agent 工具下的 skills 兼容策略5.1 Claude Code、Cursor、Windsurf 的差异关键词里大量出现claude code、vscode配置claude code、claude code for vs code说明很多人是在 VS Code 里用 Claude Code。这里有个现实问题不同 agent 工具读取 skill 的路径和格式不完全一样。我实测的对应关系工具skill 路径frontmatter 支持Claude Code.claude/skills/完整支持Cursor.cursor/rules/部分支持Windsurf.windsurf/部分支持5.2 一套内容多处复用的做法我的做法是内容只写一份用软链接或者构建脚本分发到各工具目录。# 主内容放在 .agent-skills/ # 分发到各工具 ln -s ../.agent-skills/test-driven-development.md .claude/skills/ ln -s ../.agent-skills/test-driven-development.md .cursor/rules/这样改一处所有工具同步生效。比维护多份副本靠谱得多。5.3 模型切换时的注意事项热词里提到使用cc switch 接入 deepseek v4, qwen, glm等模型这涉及一个关键点不同模型对 skill 的遵循程度差异很大。我的实测结论Claude 系列对 skill 的遵循度最高基本能严格执行部分国产模型对长 skill 文件的后半部分容易遗忘小参数模型对复杂 trigger 判断不准所以如果你要切换模型建议把 skill 拆得更短每条规则更独立。我一般控制在 30 行以内超过就拆。6. 团队协作中的 skills 治理6.1 skill 也要 code review这一点很多人没想到。skill 文件本质上是团队开发规范的代码化它应该和代码一样走 review 流程。我们团队的做法是新增或修改 skill 必须提 PR至少一人 review。review 的重点是规则是否可验证trigger 是否过宽或过窄是否和现有 skill 冲突6.2 冲突检测skill 之间会冲突。我遇到过一个 skill 说提交信息用中文另一个说提交信息用英文。agent 遇到这种情况会随机选一个行为不稳定。解决办法是定期跑一次冲突检查。简单做法是把所有 skill 的规则提取出来人工过一遍。复杂点可以写脚本做关键词匹配。提示skill 数量超过 15 个之后冲突概率明显上升。建议控制在 10-15 个核心 skill其余用项目级覆盖。6.3 新人上手skill 体系最大的隐性价值是新人 onboarding。新同事拉下代码AI agent 自动按团队规范工作他不需要先读一堆文档。我带的几个新人反馈有了 skill 之后他们提交的代码第一次 review 通过率明显提高。7. 我踩过的几个真实坑7.1 skill 写太长导致被忽略我最早写的 TDD skill 有 200 多行结果 agent 经常只执行前几条。后来砍到 40 行执行率立刻上去了。LLM 对长指令的注意力是衰减的越往后越容易忽略。7.2 trigger 写太宽导致误触发有个 skill 的 trigger 我写的是修改代码时结果连改注释都触发每次都弹一堆规则。改成涉及逻辑变更时就正常了。7.3 忘了 skill 也会影响 token 消耗每个激活的 skill 都会占用 context。我有段时间开了 20 个 skill结果发现 agent 处理复杂任务时容易忘事。关掉一半之后恢复正常。skill 不是越多越好是按需加载。7.4 路径大小写问题在 Mac 上路径不区分大小写部署到 Linux 服务器后.Claude/skills/和.claude/skills/就不一样了skill 直接不加载。这个坑排查了半小时才发现。8. 进阶让 skill 自己进化8.1 从 review 评论里提取规则我们团队有个做法每次 code review 里出现重复的评论就考虑把它变成 skill。比如 reviewer 第三次说这个函数缺少错误处理就该写一条 skill 了。8.2 用 skill 记录决策而非只记规则高级用法是让 skill 记录为什么这么规定。比如## 为什么 API 返回统一用 {code, data, message} 历史原因早期接口返回格式混乱前端需要为每个接口写不同的解析逻辑。 统一之后前端只需要一个通用响应处理器。 新增接口必须遵守否则前端需要额外适配。agent 理解了背景之后遇到规则没覆盖的边界情况也能做出符合意图的判断。8.3 定期清理skill 会过时。技术栈换了、规范改了旧 skill 就成了负担。我建议每季度过一遍删掉不再适用的。判断标准很简单过去三个月这条 skill 有没有真正影响过 agent 的输出没有就删。这套东西用下来我最大的体会是agent-skills不是一个工具而是一种把团队隐性知识显性化的方法。它逼着你想清楚我们到底怎么写代码然后把这个答案写成 AI 能执行的文件。这个过程本身比 AI 帮你写多少代码更有价值。