1. 从agent-skills说起为什么这个项目值得你花时间第一次看到agent-skills这个标题我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套插件化的能力说明书让 Claude Code、Cursor、Windsurf 这类 AI 编程助手在特定任务上表现得更像一位有经验的工程师而不是一个只会补全代码的自动机。我接触 AI coding agent 这条线大概是从 Claude Code 刚开放命令行版本那会儿开始的。当时最大的感受是模型本身很强但一到具体项目里就水土不服。比如让它写测试它可能给你写一堆断言稀松的用例让它重构它可能把好好的模块拆得七零八落。问题不在模型智力而在于它不知道你这个项目的规矩。agent-skills这类项目要解决的就是这件事——把规矩和套路沉淀成可复用的技能单元让 agent 每次开工前先读一遍员工手册。这篇文章适合三类人看一是已经在用 Claude Code、Cursor 等工具但觉得输出质量忽高忽低的开发者二是想给自己的团队搭一套 AI 辅助开发规范的技术负责人三是单纯对 agent 工程化感兴趣、想搞清楚skills到底是个什么抽象层的人。我会从设计思路、核心机制、实操落地、踩坑排查几个角度把它拆开讲尽量让你看完能自己动手搭一套。需要先说明一点agent-skills这个标题本身比较宽泛不同团队、不同仓库对它的实现差异很大。下面讲的内容是我基于当前主流 AI coding agent 的通用实践、以及 Claude Code 这类工具的实际使用经验做的合理还原和补全。如果你手上的agent-skills是某个具体仓库核心逻辑大概率是相通的细节上按你的实际文档调整即可。2. 核心设计思路skills 到底在解决什么问题2.1 从提示词工程到技能工程的转变早两年大家聊 AI 辅助编程关键词是 prompt engineering。写一段精心设计的提示词让模型输出更好的代码。但这套东西有个致命问题不可复用、不可组合、不可维护。你为一个项目写的提示词换到另一个项目基本作废团队里十个人写十套提示词质量参差不齐。agent-skills代表的思路是把这件事工程化。一个 skill 通常包含几样东西一段描述什么时候该用我的元信息、一份具体的操作指令、可能还有配套的脚本或模板文件。它更像是一个函数——有明确的输入触发条件有确定的执行逻辑可以被 agent 在合适的时机调用。我自己的体会是这个转变的意义在于把隐性知识显性化。老工程师脑子里那套写测试要先想边界条件重构前先跑一遍回归的经验以前只能靠口口相传现在可以写进 skill 里让 agent 每次都照着做。2.2 为什么是技能而不是规则有人会问那我直接写一份 CLAUDE.md 或者 .cursorrules 不就行了把所有规范堆在一个文件里。可以但会很快失控。我试过一个中等规模项目规范文件写到 800 多行结果 agent 经常选择性失忆——它读了但没完全读进去。原因很简单上下文是有限资源。你把所有规则一股脑塞进去重要的和不重要的混在一起模型注意力被稀释。skills 的设计精髓在于按需加载。平时 agent 只看到一份技能清单每个技能一行描述只有当任务匹配到某个技能的触发条件时才把该技能的完整内容加载进上下文。这就像公司里你不会把员工手册全文背下来但你知道遇到报销问题找财务部需要时再去查具体流程。2.3 一个 skill 的典型结构基于我见过的多种实现一个 skill 通常长这样--- name: test-driven-development description: 当需要为新功能编写测试或修改现有测试时使用。强制先写失败测试再实现。 --- ## 何时使用 - 新增功能模块 - 修复 bug 前先补一个能复现的测试 - 重构前确保有测试覆盖 ## 执行步骤 1. 先写一个会失败的测试明确预期行为 2. 运行测试确认它确实失败红 3. 写最小实现让测试通过绿 4. 重构保持测试通过 5. 重复 ## 注意事项 - 测试失败信息要具体不要写 assert result expected 这种模糊断言 - 一次只加一个测试不要批量写这个结构里description字段最关键——它是 agent 决定要不要用这个技能的唯一依据。写得好不好直接决定技能会不会被正确触发。2.4 技能之间的组合与依赖单个技能解决单点问题但真实开发任务是复合的。比如给一个模块加新功能可能同时涉及写测试TDD 技能、更新文档文档技能、检查类型类型检查技能。好的agent-skills设计会考虑技能编排。常见做法有两种一种是在技能描述里声明依赖agent 加载主技能时自动带上依赖技能另一种是提供一个元技能专门负责根据任务类型调度其他技能。我倾向于后者因为调度逻辑集中在一处改起来方便。3. 核心细节解析skills CLI 与目录结构3.1 skills CLI 的定位热词里出现了skills CLI这基本可以确定agent-skills配套了一个命令行工具。它的职责通常包括初始化技能目录、校验技能格式、列出可用技能、把技能安装到指定 agent 的配置目录。为什么需要 CLI 而不是手动复制文件因为技能需要被多个 agent 共享。你可能同时用 Claude Code 和 Cursor手动维护两份技能文件迟早会不同步。CLI 的价值就是做一层抽象让技能源文件只有一份安装时按目标 agent 的格式转换。一个典型的 CLI 使用流程大概是这样# 初始化技能目录 skills init # 创建一个新技能 skills new test-driven-development # 校验所有技能格式 skills validate # 安装到 Claude Code skills install --target claude-code # 列出已安装技能 skills list具体命令名可能不同但功能面大同小异。我建议你在用之前先跑一遍skills --help把子命令摸清楚别上来就install容易装到奇怪的位置。3.2 目录结构的设计考量技能目录怎么组织直接影响可维护性。我见过比较合理的结构是这样agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── test-template.py │ ├── code-review/ │ │ └── SKILL.md │ └── documentation/ │ └── SKILL.md ├── scripts/ │ └── validate.sh └── skills.config.json每个技能一个独立目录好处是技能可以带附属资源。比如 TDD 技能可能附带一个测试模板文件代码审查技能可能附带一份检查清单。如果所有技能都塞在一个大文件里这些附属资源就没地方放。skills.config.json通常记录全局配置比如默认目标 agent、技能搜索路径、是否启用某个技能等。这个文件建议纳入版本控制团队共享。3.3 SKILL.md 的元信息字段元信息字段是技能能否被正确触发的关键。除了前面提到的name和description常见的还有字段作用是否必填name技能唯一标识建议用 kebab-case是description触发条件描述agent 据此判断是否加载是version技能版本便于追踪变更否tags分类标签便于检索和分组否dependencies依赖的其他技能否enabled是否启用方便临时关闭否description的写法有讲究。我踩过的坑是写得太笼统用于编写代码结果 agent 什么任务都加载它上下文被占满写得太窄用于编写 Python 3.11 的 pytest 测试结果换个语言就不触发。好的描述是场景 动作的组合比如当需要为新功能编写测试或修改现有测试时使用。3.4 触发机制agent 怎么知道该用哪个技能这是很多人好奇的点。主流实现有两种触发方式一种是描述匹配。agent 拿到任务后把任务描述和所有技能的description做语义比对选出最相关的几个加载。这种方式灵活但依赖模型判断偶尔会漏。另一种是显式调用。用户在对话里直接说用 TDD 技能来做这个或者通过斜杠命令/tdd触发。这种方式确定性强但需要用户知道有哪些技能。实际产品里通常是两者结合。我的建议是关键流程用显式调用兜底日常任务靠描述匹配。比如团队规定所有新功能必须走 TDD那就在 CI 或代码审查环节检查而不是指望 agent 每次都自觉。4. 实操落地从零搭一套可用的 skills4.1 环境准备与 Claude Code 接入既然热词里 Claude Code 出现频率极高我就以它为主要目标 agent 来讲。先确认你的环境# 检查 Node.js 版本Claude Code 一般要求 18 node --version # 检查是否已安装 claude --version如果没装按官方文档走一遍安装流程。macOS 和 Ubuntu 的安装方式略有差异macOS 通常用 npm 全局安装Ubuntu 上注意权限问题别用 sudo 装 npm 包容易把目录权限搞乱。装完之后Claude Code 的配置目录一般在~/.claude/下。技能相关的文件通常放在~/.claude/skills/或者项目根目录的.claude/skills/。项目级技能和用户级技能的区别项目级的只在这个项目生效适合项目特有的规范用户级的全局生效适合通用技能。我一般把 TDD、代码审查这类通用技能放用户级把项目特定的架构约定放项目级。4.2 写第一个技能以 TDD 为例我们动手写一个test-driven-development技能。先建目录mkdir -p ~/.claude/skills/test-driven-development然后创建SKILL.md--- name: test-driven-development description: 当需要为新功能编写测试、修复 bug 前补充复现测试、或重构前确保测试覆盖时使用。 version: 1.0.0 tags: [testing, quality] --- ## 核心原则 先写测试再写实现。测试必须先失败再让它通过。 ## 执行步骤 1. 明确要实现的单个行为用一句话描述 2. 写一个测试断言这个行为 3. 运行测试确认失败且失败原因符合预期 4. 写最小实现让测试通过 5. 运行全部测试确认没有破坏其他功能 6. 重构保持测试绿色 7. 回到步骤 1处理下一个行为 ## 测试编写要求 - 一个测试只验证一个行为 - 测试名要描述行为不要写 test1、test2 - 断言要具体失败时能直接看出哪里不对 - 避免在测试里写复杂逻辑测试本身要简单 ## 禁止事项 - 禁止先写实现再补测试 - 禁止一次写多个测试再一起跑 - 禁止为了让测试通过而修改测试断言写完保存。然后在 Claude Code 里试着触发它比如输入帮我给用户登录功能写测试看它是否会加载这个技能并按照 TDD 流程走。4.3 参数与配置的取舍技能里要不要写具体的技术栈参数比如用 pytest用 Jest我的经验是分层处理。通用技能只写方法论不绑定具体工具项目级技能再补充技术栈细节。这样通用技能可以跨项目复用项目级技能负责落地。举个例子通用 TDD 技能说写一个会失败的测试项目级技能补充本项目用 pytest测试文件放在 tests/ 目录命名规则 test_*.py。agent 加载时两个技能叠加既有方法论又有具体约束。4.4 验证技能是否生效写完技能别急着信它生效了。验证方法有几个第一直接问 agent你现在有哪些可用技能看它列出来的清单里有没有你新加的。第二给一个明确匹配的任务观察它的行为是否符合技能描述。比如 TDD 技能生效的话它应该先写测试而不是先写实现。第三看日志。Claude Code 一般有 verbose 模式能看到它加载了哪些技能文件。这个最可靠建议排查问题时优先用。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序建议这样先检查description字段。把技能描述读一遍问自己如果我是 agent看到这个描述会在什么情况下加载它如果答案是几乎任何时候或几乎任何时候都不那就是描述写坏了。再检查文件位置。技能文件是不是放在了 agent 会扫描的目录下目录名和name字段是否一致有些实现要求目录名必须等于技能名不一致就扫不到。然后检查格式。YAML frontmatter 的---有没有写对缩进有没有用 TabYAML 不允许 Tab 缩进这些细节错了解析直接失败技能等于不存在。最后检查是否被禁用。enabled: false或者配置文件里排除了这个技能都会导致不加载。5.2 技能加载了但 agent 不照做这种情况通常是技能内容写得太软。比如写建议先写测试agent 可能觉得这次情况特殊就跳过了。改成必须先写测试未写测试前不得修改实现代码约束力就强很多。另一个原因是技能之间冲突。比如一个技能说先写测试另一个技能说快速原型优先agent 就懵了。解决办法是明确优先级或者在技能描述里写清楚适用边界。5.3 上下文被技能占满技能太多、太长会把上下文挤爆导致 agent 处理实际任务时反而变笨。我的做法是单个技能正文控制在 200 行以内技能总数控制在 20 个以内超过就考虑合并或分层定期清理不用的技能长清单、大模板放到附属文件里技能正文只写需要时读取 templates/xxx5.4 常见问题速查表现象可能原因排查动作技能完全不触发描述不匹配 / 文件位置错 / 格式错检查 description、目录、YAML触发但行为不符内容约束太弱 / 技能冲突加强措辞、明确优先级agent 变笨上下文被占满精简技能、减少数量技能时灵时不灵描述边界模糊收窄触发条件团队间不一致技能未纳入版本控制统一源、用 CLI 分发5.5 几个我踩过的坑第一个坑技能名用中文。有些实现对非 ASCII 字符支持不好导致文件找不到。老老实实用英文 kebab-case。第二个坑在技能里写死路径。比如写测试文件放在 /Users/xxx/project/tests换台机器就废了。用相对路径或者占位符。第三个坑技能描述里堆关键词。以为关键词越多越容易触发结果语义变得模糊反而触发不准。描述要像人话一句话说清楚什么时候用。第四个坑忘了同步。本地改了技能忘了推到团队仓库别人用的还是旧版。用 CLI 的install命令统一分发能缓解这个问题但根本还是靠流程约束。6. 技能工程化的延伸思考6.1 技能与测试驱动开发的结合热词里test-driven-development和agent-skills并列出现不是偶然。TDD 是最适合做成技能的开发实践之一因为它步骤明确、可验证、有强制顺序。agent 最容易出问题的地方就是跳步——不写测试直接写实现或者测试没跑就宣布完成。技能的作用就是把顺序锁死。我实际用下来TDD 技能对 agent 输出质量的提升是最明显的。以前让它写功能它给你一段能跑但没测试的代码现在它会先写测试跑一遍确认失败再写实现。虽然慢一点但返工率大幅下降。6.2 技能的可测试性技能本身也应该被测试。怎么测我的做法是准备一组任务样本每个样本标注期望行为然后跑一遍看 agent 是否按预期加载技能并执行。这有点像给提示词写单元测试听起来怪但确实能提前发现技能描述的问题。样本不用多每个技能配 3 到 5 个就够。关键是覆盖应该触发和不应该触发两类情况。后者容易被忽略但很重要——一个到处乱触发的技能比不触发还烦人。6.3 团队协作中的技能管理一个人用技能和十个人用技能复杂度不是一个量级。团队场景下要考虑技能的所有权。谁负责维护哪个技能没有明确 owner 的技能会迅速腐烂。技能的评审。新技能或技能变更要不要走 code review我建议要至少让一个人看过。技能写错了影响的是整个团队的 agent 行为。技能的版本。技能变更后怎么通知使用者怎么保证大家用的是同一版这需要配套的发布流程。我的建议是把技能当代码管。用 Git 仓库、走 PR 流程、打版本标签、写变更日志。听起来重但技能一旦多起来不这么做必然乱。6.4 技能的未来形态现在大多数技能还是纯文本的 Markdown。往后看我觉得会有几个方向一是技能带可执行逻辑。不只是告诉 agent 怎么做而是直接提供脚本让它调用。比如代码格式化技能直接附一个格式化脚本agent 调脚本而不是自己生成格式化代码。二是技能的组合与继承。基础技能定义通用流程派生技能覆盖特定环节。类似面向对象的继承减少重复。三是技能的自动优化。根据 agent 实际执行效果自动调整技能描述和内容。这个还比较远但方向是明确的。不过这些都是后话。眼下最实在的还是先把手上这几个核心技能写好、用起来、持续迭代。技能工程化这件事写十个不如用好一个。我见过太多人一口气建了二十个技能结果每个都半吊子agent 反而更糊涂。从 TDD 这种高频、明确、收益大的技能开始跑顺了再扩展是我验证过最稳的路径。