1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套把 AI coding agent 当新员工来培养的技能体系。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——agent-skills、AI coding agents、skills CLI、Claude Code、test-driven-development。这几个词串起来指向一个很具体的场景给编码类 AI agent 装上一套可复用、可组合、可版本管理的技能包让它在真实工程里少犯低级错误。为什么我这么判断因为单纯堆提示词的时代已经过去了。你给 Claude Code 或者别的 coding agent 写一段超长 system prompt它确实能记住一些规则但一旦任务变复杂、上下文变长规则就开始漂移——该跑测试的时候不跑该读文件的时候瞎猜该问清楚需求的时候自作主张。agent-skills这类项目的核心价值就是把这些行为约束从一段易失的提示词变成一个个独立、可加载、可测试的技能单元。这篇文章适合三类人看一是已经在用 Claude Code、Cursor、各类 CLI agent 做日常开发但总觉得它不够听话的工程师二是想给自己团队搭一套 AI 编码规范、让多人协作时 agent 行为一致的 tech lead三是纯粹好奇skills CLI 到底是个什么东西、值不值得投入时间的观望者。我会从技能包的设计逻辑讲起一路讲到怎么落地、怎么避坑尽量把我在实际折腾这类工具时踩过的坑都摊开说。需要先说明一点agent-skills的具体实现细节公开资料里并没有一份权威到可以照抄的文档所以下面涉及目录结构、CLI 命令、加载机制的部分都是基于这类工具在工程实践中最常见的做法做的合理还原。你真正上手时以你拿到的那个版本的实际行为为准但设计思路和避坑经验是通用的。2. 为什么技能比提示词更适合 coding agent2.1 提示词膨胀的必然结局只要你认真用过一段时间的 coding agent就会发现一个规律你写的规则越多它遵守得越差。这不是模型变笨了而是注意力机制的现实——上下文里塞进三千字的你必须……你绝对不能……真正关键的那三五条反而被稀释了。我见过有人给 agent 写了整整两屏的行为准则结果它连改完代码要跑测试这种最基本的事都忘。更麻烦的是维护成本。提示词是一整块文本你想改其中一条规则得在几千字里找到那句话改完还得担心有没有破坏别的逻辑。团队里几个人共用一套提示词谁改了什么、为什么改完全没有记录。这跟把业务逻辑全写在一个函数里是同一种病。2.2 技能包把行为拆成了模块agent-skills这类项目的思路本质上是软件工程里关注点分离的老办法。一个技能就是一个独立单元比如写测试读代码库结构提交前自检处理报错。每个技能有自己的触发条件、执行步骤、验收标准。agent 在遇到对应场景时只加载相关的那一个技能而不是把全部规则一股脑塞进上下文。这样做的好处很直接上下文更干净处理测试任务时只加载测试相关技能不掺杂部署、文档那些无关规则。可独立迭代某个技能不好用单独改它不影响其他技能。可测试技能本身可以被验证——给定一个场景agent 加载这个技能后行为是否符合预期。可组合复杂任务可以由多个技能串起来像搭积木。我个人的体会是这套思路最值钱的地方在于它把调教 agent从玄学变成了工程。以前你只能凭感觉说这个提示词好像好一点现在你可以说这个技能在 X 场景下通过率从 60% 提到了 90%。2.3 和 test-driven-development 的天然契合热搜词里出现了test-driven-development这不是巧合。TDD 的核心是先写测试再写实现测试通过才算完成。这套流程对 agent 来说简直是量身定做——因为测试给了 agent 一个明确的、可自动验证的成功标准。没有测试的时候agent 改完代码只能自己觉得改好了然后你人工去验。有了测试agent 可以自己跑、自己看结果、自己迭代。agent-skills里如果有一个TDD 工作流技能它要做的就是强制 agent 走这个循环先根据需求写失败测试 → 写最小实现让测试通过 → 重构 → 再跑一遍。这个技能一旦稳定agent 的产出质量会有质的提升因为它不再依赖自我感觉而是依赖客观的绿灯。3. 一个技能包通常长什么样3.1 目录结构的最小共识虽然各家实现不同但这类技能系统在目录组织上往往有相似的骨架。下面是我见过最合理、也最容易被 agent 正确加载的一种结构agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md # 技能主文件触发条件、步骤、验收 │ │ ├── examples/ # 正例反例给 agent 参考 │ │ └── tests/ # 技能自身的验证用例 │ ├── codebase-navigation/ │ │ ├── SKILL.md │ │ └── ... │ └── pre-commit-check/ │ ├── SKILL.md │ └── ... ├── registry.json # 技能索引CLI 靠它发现技能 └── README.md关键在SKILL.md。它通常包含几块内容何时触发什么场景下该用这个技能、怎么做分步骤的操作指引、怎么算做完验收标准、别做什么常见错误。这四块缺一不可尤其是最后一块——agent 最容易犯的错往往不是不知道该做什么而是做了不该做的。3.2 SKILL.md 里到底写什么我拿提交前自检这个技能举例给你看一个我实际用过的写法骨架# Skill: pre-commit-check ## 触发条件 当用户要求提交代码或 agent 准备执行 git commit 时。 ## 执行步骤 1. 运行项目配置的 lint 命令确认无报错 2. 运行单元测试确认全部通过 3. 检查是否有调试代码残留console.log、print、debugger 4. 检查是否有未处理的 TODO 被误提交 5. 生成简洁的 commit message说明改了什么、为什么改 ## 验收标准 - lint 与测试均通过 - 无调试残留 - commit message 不含updatefix bug这类无信息量描述 ## 禁止事项 - 禁止在测试失败时强行提交 - 禁止跳过 lint 直接 commit - 禁止把多个不相关改动塞进一个 commit你看这个文件本身没有任何魔法它就是一份写得很清楚的 SOP。但正因为写得清楚agent 加载后行为就稳定。技能的质量本质上取决于你写 SOP 的功力——这跟带新人是一个道理你交代得越具体新人越不容易跑偏。3.3 registry.json 的作用registry.json是技能索引CLI 靠它知道有哪些技能可用、每个技能在哪、依赖什么。一个典型的条目大概长这样{ name: tdd-workflow, path: skills/tdd-workflow, triggers: [write test, implement feature, fix bug], requires: [codebase-navigation], version: 1.2.0 }triggers决定什么时候加载这个技能requires声明依赖关系。依赖这块特别重要——比如 TDD 技能依赖代码库导航技能因为写测试前得先知道项目结构、测试框架、已有测试放哪。如果依赖没声明清楚agent 可能在完全不了解项目的情况下就开始写测试写出来的东西根本跑不起来。4. skills CLI 的典型用法与实操4.1 安装与初始化这类 CLI 工具通常通过包管理器分发。以最常见的 Node 生态为例安装命令大概是npm install -g agent-skills-cli # 或者用 npx 免安装直接跑 npx agent-skills-cli initinit会在当前项目下生成一个技能目录骨架和默认配置。我建议不要直接用它生成的默认技能而是先看看默认技能写了什么理解结构后再按自己项目的情况改。默认技能往往是通用模板直接用在你的项目里大概率水土不服。初始化后通常还需要在 agent 的配置文件里注册这个技能目录。比如 Claude Code 这类工具会有一个项目级的配置文件你需要告诉它去这个目录找技能。具体字段名各版本不同但逻辑都是声明技能源路径。4.2 列出、加载、验证技能日常最常用的三条命令我按使用频率排# 列出当前可用的所有技能 agent-skills list # 查看某个技能的详细内容 agent-skills show tdd-workflow # 验证技能格式是否正确、依赖是否满足 agent-skills validatevalidate这条命令我要重点说。技能文件写错格式是最高频的翻车点——比如 YAML 头写错缩进、触发条件写成空数组、依赖的技能名拼错。这些错误不会让 agent 立刻崩溃而是让技能静默失效你以为加载了其实没有。养成改完技能就跑一次validate的习惯能省掉大量为什么它不听话的困惑。4.3 把技能接进 Claude Code 的实际流程假设你用的是 Claude Code想让它在你的项目里用上这套技能典型流程是这样的在项目根目录跑agent-skills init生成技能目录编辑项目里的 agent 配置文件把技能目录路径加进去跑agent-skills validate确认无误启动 Claude Code用agent-skills list确认它能识别到技能给一个真实任务观察 agent 是否按技能步骤执行第 5 步是关键验证。我一般会故意给一个改完代码不跑测试的任务看 agent 会不会主动触发 TDD 或自检技能。如果它没触发说明触发条件写得不够准得回去改SKILL.md里的触发描述。提示不同版本的 agent 工具对技能加载的时机不一样。有的在会话开始时一次性加载全部技能索引有的按需动态加载。如果你发现技能改了但 agent 行为没变先重启会话再检查是不是缓存了旧索引。5. 设计技能时最容易踩的五个坑5.1 触发条件写得太宽或太窄这是最普遍的问题。写太宽比如触发条件写当用户提到代码时那 agent 几乎每个任务都会加载这个技能上下文又被塞满了等于白拆。写太窄比如当用户明确说请用 TDD 方式时那它基本永远不会触发因为没人会这么说话。我的经验是触发条件要贴着动作写而不是贴着话题写。写测试修 bug提交代码是动作代码测试是话题。动作触发准话题触发滥。5.2 步骤写得像口号不像操作反面例子确保代码质量。 这种话对 agent 毫无指导意义。正面例子运行npm test若失败则读取失败用例的断言信息定位到对应源文件修改后重新运行直到全部通过。 区别在于后者每一步都是可执行、可验证的。我判断一个技能步骤写得好不好有个土办法把它念给一个刚入职的实习生听他能不能照着做。如果实习生听完还是一脸茫然agent 大概率也茫然。5.3 忽略依赖关系前面提过技能之间是有依赖的。写测试依赖了解项目结构做重构依赖测试覆盖提交依赖 lint 和测试。如果依赖没声明agent 可能在没有前置信息的情况下硬上结果就是瞎猜。依赖声明不只是给 CLI 看的更是给 agent 看的——它知道我得先做 A 才能做 B。5.4 技能之间规则打架这个坑很隐蔽。比如快速修复技能说优先最小改动代码质量技能说发现坏味道就重构。两个技能同时加载时agent 就懵了到底改还是不改解决办法是给技能分优先级或者在技能里明确当与 X 技能冲突时以本技能为准。规则冲突是 agent 行为不稳定的重要来源值得专门花时间排查。5.5 从不更新技能项目在变技术栈在变技能却还是半年前写的。比如项目从 Jest 换成了 Vitest技能里还写着npm run jestagent 一跑就报错。我建议把技能目录纳入代码评审范围每次技术栈变更时同步检查相关技能。技能是活的文档不是一次性写完就扔的。6. 让技能真正提升产出质量的两个关键6.1 用测试验证技能而不是靠感觉既然热搜词里有 TDD那技能本身也该被测试。具体怎么做给每个技能准备一组场景用例输入一个任务描述期望 agent 加载该技能并产出符合验收标准的结果。跑一遍看通过率。比如提交前自检技能你可以准备三个用例一个正常提交、一个测试失败的提交、一个带调试残留的提交。期望结果是第一个通过后两个被拦下。如果 agent 在第二个用例里还是提交了说明技能的禁止事项没起作用得加强。这套做法听起来重但它是把调教 agent从玄学变成工程的唯一路径。没有验证你永远不知道改动是变好了还是变坏了。6.2 从真实翻车案例反推技能最好的技能不是凭空设计出来的是从真实事故里长出来的。我自己的做法是每次 agent 干了一件蠢事就记下来然后问自己如果当时有个技能它该怎么写才能拦住这件事。攒够几条就提炼成一个新技能。举个例子有次 agent 在重构时把某个函数的边界条件改错了测试没覆盖到直接提交了。事后我加了一个重构安全网技能要求重构前先确认目标代码有测试覆盖没有就先补测试再重构。这个技能后来拦住了好几次类似问题。技能库应该像事故档案一样生长而不是一次性设计完。你踩的坑越多技能库越值钱。7. 关于模型选择与接入的一点现实观察热搜词里有一堆关于 Claude Code 安装、配置、接入第三方模型的内容说明很多人关心的其实是我能不能不登录官方、用别的模型跑这套东西。这个问题我没法给你一个统一答案因为不同工具的授权策略和技术实现差异很大而且随时在变。但从工程角度有几点是通用的技能是模型无关的资产。SKILL.md写的是行为规范换哪个模型都能用。所以哪怕你以后换了底层模型技能库不用重写这是它相对提示词的一大优势。不同模型对技能的遵守度不同。同一个技能强模型可能执行得很稳弱模型可能只执行一半。所以技能设计要留冗余关键步骤最好有如果没做到就重试的兜底。接入方式影响稳定性。通过官方渠道、第三方 API、本地部署延迟和上下文窗口都可能不同进而影响技能加载和执行的稳定性。这块建议以你实际环境的实测为准别照搬别人的配置。我个人的态度是先把技能库建起来模型选择是后面的事。技能库是你能控制的资产模型是会变的变量。把可控的部分做扎实换模型时迁移成本才低。8. 我实际用下来的一些体会折腾这套东西大半年有几个感受挺深。第一技能不是越多越好。我一开始兴奋地写了十几个技能结果 agent 加载时互相干扰行为反而更乱。后来砍到五六个核心技能每个都打磨到稳定效果明显更好。技能库要精不要多。第二写技能最花时间的不是写是改。第一版技能几乎都不好用得根据 agent 的实际表现反复调触发条件和步骤描述。这个过程很像调 prompt但因为有结构、有验证比调 prompt 有章法得多。第三团队协作时技能库的价值会放大。一个人用技能库是个人效率工具一个团队用它就成了AI 编码规范的载体。新人入职不用口头交代一堆规矩把技能库给他agent 自然就按规范干活了。这种一致性是零散提示词永远给不了的。最后分享一个小技巧给每个技能写一句一句话说明放在SKILL.md最顶部。这句话不参与 agent 执行纯粹给人看。当技能多起来你翻目录时靠这句话就能快速回忆每个技能是干嘛的维护成本会低很多。这个习惯我是从写代码注释里学来的用在技能库上一样好使。 
长河君 · 2026/10/8 11:20:48 · 阅读 1.2k agent-skills：为AI coding agent构建可复用技能包
1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套把 AI coding agent 当新员工来培养的技能体系。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——agent-skills、AI coding agents、skills CLI、Claude Code、test-driven-development。这几个词串起来指向一个很具体的场景给编码类 AI agent 装上一套可复用、可组合、可版本管理的技能包让它在真实工程里少犯低级错误。为什么我这么判断因为单纯堆提示词的时代已经过去了。你给 Claude Code 或者别的 coding agent 写一段超长 system prompt它确实能记住一些规则但一旦任务变复杂、上下文变长规则就开始漂移——该跑测试的时候不跑该读文件的时候瞎猜该问清楚需求的时候自作主张。agent-skills这类项目的核心价值就是把这些行为约束从一段易失的提示词变成一个个独立、可加载、可测试的技能单元。这篇文章适合三类人看一是已经在用 Claude Code、Cursor、各类 CLI agent 做日常开发但总觉得它不够听话的工程师二是想给自己团队搭一套 AI 编码规范、让多人协作时 agent 行为一致的 tech lead三是纯粹好奇skills CLI 到底是个什么东西、值不值得投入时间的观望者。我会从技能包的设计逻辑讲起一路讲到怎么落地、怎么避坑尽量把我在实际折腾这类工具时踩过的坑都摊开说。需要先说明一点agent-skills的具体实现细节公开资料里并没有一份权威到可以照抄的文档所以下面涉及目录结构、CLI 命令、加载机制的部分都是基于这类工具在工程实践中最常见的做法做的合理还原。你真正上手时以你拿到的那个版本的实际行为为准但设计思路和避坑经验是通用的。2. 为什么技能比提示词更适合 coding agent2.1 提示词膨胀的必然结局只要你认真用过一段时间的 coding agent就会发现一个规律你写的规则越多它遵守得越差。这不是模型变笨了而是注意力机制的现实——上下文里塞进三千字的你必须……你绝对不能……真正关键的那三五条反而被稀释了。我见过有人给 agent 写了整整两屏的行为准则结果它连改完代码要跑测试这种最基本的事都忘。更麻烦的是维护成本。提示词是一整块文本你想改其中一条规则得在几千字里找到那句话改完还得担心有没有破坏别的逻辑。团队里几个人共用一套提示词谁改了什么、为什么改完全没有记录。这跟把业务逻辑全写在一个函数里是同一种病。2.2 技能包把行为拆成了模块agent-skills这类项目的思路本质上是软件工程里关注点分离的老办法。一个技能就是一个独立单元比如写测试读代码库结构提交前自检处理报错。每个技能有自己的触发条件、执行步骤、验收标准。agent 在遇到对应场景时只加载相关的那一个技能而不是把全部规则一股脑塞进上下文。这样做的好处很直接上下文更干净处理测试任务时只加载测试相关技能不掺杂部署、文档那些无关规则。可独立迭代某个技能不好用单独改它不影响其他技能。可测试技能本身可以被验证——给定一个场景agent 加载这个技能后行为是否符合预期。可组合复杂任务可以由多个技能串起来像搭积木。我个人的体会是这套思路最值钱的地方在于它把调教 agent从玄学变成了工程。以前你只能凭感觉说这个提示词好像好一点现在你可以说这个技能在 X 场景下通过率从 60% 提到了 90%。2.3 和 test-driven-development 的天然契合热搜词里出现了test-driven-development这不是巧合。TDD 的核心是先写测试再写实现测试通过才算完成。这套流程对 agent 来说简直是量身定做——因为测试给了 agent 一个明确的、可自动验证的成功标准。没有测试的时候agent 改完代码只能自己觉得改好了然后你人工去验。有了测试agent 可以自己跑、自己看结果、自己迭代。agent-skills里如果有一个TDD 工作流技能它要做的就是强制 agent 走这个循环先根据需求写失败测试 → 写最小实现让测试通过 → 重构 → 再跑一遍。这个技能一旦稳定agent 的产出质量会有质的提升因为它不再依赖自我感觉而是依赖客观的绿灯。3. 一个技能包通常长什么样3.1 目录结构的最小共识虽然各家实现不同但这类技能系统在目录组织上往往有相似的骨架。下面是我见过最合理、也最容易被 agent 正确加载的一种结构agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md # 技能主文件触发条件、步骤、验收 │ │ ├── examples/ # 正例反例给 agent 参考 │ │ └── tests/ # 技能自身的验证用例 │ ├── codebase-navigation/ │ │ ├── SKILL.md │ │ └── ... │ └── pre-commit-check/ │ ├── SKILL.md │ └── ... ├── registry.json # 技能索引CLI 靠它发现技能 └── README.md关键在SKILL.md。它通常包含几块内容何时触发什么场景下该用这个技能、怎么做分步骤的操作指引、怎么算做完验收标准、别做什么常见错误。这四块缺一不可尤其是最后一块——agent 最容易犯的错往往不是不知道该做什么而是做了不该做的。3.2 SKILL.md 里到底写什么我拿提交前自检这个技能举例给你看一个我实际用过的写法骨架# Skill: pre-commit-check ## 触发条件 当用户要求提交代码或 agent 准备执行 git commit 时。 ## 执行步骤 1. 运行项目配置的 lint 命令确认无报错 2. 运行单元测试确认全部通过 3. 检查是否有调试代码残留console.log、print、debugger 4. 检查是否有未处理的 TODO 被误提交 5. 生成简洁的 commit message说明改了什么、为什么改 ## 验收标准 - lint 与测试均通过 - 无调试残留 - commit message 不含updatefix bug这类无信息量描述 ## 禁止事项 - 禁止在测试失败时强行提交 - 禁止跳过 lint 直接 commit - 禁止把多个不相关改动塞进一个 commit你看这个文件本身没有任何魔法它就是一份写得很清楚的 SOP。但正因为写得清楚agent 加载后行为就稳定。技能的质量本质上取决于你写 SOP 的功力——这跟带新人是一个道理你交代得越具体新人越不容易跑偏。3.3 registry.json 的作用registry.json是技能索引CLI 靠它知道有哪些技能可用、每个技能在哪、依赖什么。一个典型的条目大概长这样{ name: tdd-workflow, path: skills/tdd-workflow, triggers: [write test, implement feature, fix bug], requires: [codebase-navigation], version: 1.2.0 }triggers决定什么时候加载这个技能requires声明依赖关系。依赖这块特别重要——比如 TDD 技能依赖代码库导航技能因为写测试前得先知道项目结构、测试框架、已有测试放哪。如果依赖没声明清楚agent 可能在完全不了解项目的情况下就开始写测试写出来的东西根本跑不起来。4. skills CLI 的典型用法与实操4.1 安装与初始化这类 CLI 工具通常通过包管理器分发。以最常见的 Node 生态为例安装命令大概是npm install -g agent-skills-cli # 或者用 npx 免安装直接跑 npx agent-skills-cli initinit会在当前项目下生成一个技能目录骨架和默认配置。我建议不要直接用它生成的默认技能而是先看看默认技能写了什么理解结构后再按自己项目的情况改。默认技能往往是通用模板直接用在你的项目里大概率水土不服。初始化后通常还需要在 agent 的配置文件里注册这个技能目录。比如 Claude Code 这类工具会有一个项目级的配置文件你需要告诉它去这个目录找技能。具体字段名各版本不同但逻辑都是声明技能源路径。4.2 列出、加载、验证技能日常最常用的三条命令我按使用频率排# 列出当前可用的所有技能 agent-skills list # 查看某个技能的详细内容 agent-skills show tdd-workflow # 验证技能格式是否正确、依赖是否满足 agent-skills validatevalidate这条命令我要重点说。技能文件写错格式是最高频的翻车点——比如 YAML 头写错缩进、触发条件写成空数组、依赖的技能名拼错。这些错误不会让 agent 立刻崩溃而是让技能静默失效你以为加载了其实没有。养成改完技能就跑一次validate的习惯能省掉大量为什么它不听话的困惑。4.3 把技能接进 Claude Code 的实际流程假设你用的是 Claude Code想让它在你的项目里用上这套技能典型流程是这样的在项目根目录跑agent-skills init生成技能目录编辑项目里的 agent 配置文件把技能目录路径加进去跑agent-skills validate确认无误启动 Claude Code用agent-skills list确认它能识别到技能给一个真实任务观察 agent 是否按技能步骤执行第 5 步是关键验证。我一般会故意给一个改完代码不跑测试的任务看 agent 会不会主动触发 TDD 或自检技能。如果它没触发说明触发条件写得不够准得回去改SKILL.md里的触发描述。提示不同版本的 agent 工具对技能加载的时机不一样。有的在会话开始时一次性加载全部技能索引有的按需动态加载。如果你发现技能改了但 agent 行为没变先重启会话再检查是不是缓存了旧索引。5. 设计技能时最容易踩的五个坑5.1 触发条件写得太宽或太窄这是最普遍的问题。写太宽比如触发条件写当用户提到代码时那 agent 几乎每个任务都会加载这个技能上下文又被塞满了等于白拆。写太窄比如当用户明确说请用 TDD 方式时那它基本永远不会触发因为没人会这么说话。我的经验是触发条件要贴着动作写而不是贴着话题写。写测试修 bug提交代码是动作代码测试是话题。动作触发准话题触发滥。5.2 步骤写得像口号不像操作反面例子确保代码质量。 这种话对 agent 毫无指导意义。正面例子运行npm test若失败则读取失败用例的断言信息定位到对应源文件修改后重新运行直到全部通过。 区别在于后者每一步都是可执行、可验证的。我判断一个技能步骤写得好不好有个土办法把它念给一个刚入职的实习生听他能不能照着做。如果实习生听完还是一脸茫然agent 大概率也茫然。5.3 忽略依赖关系前面提过技能之间是有依赖的。写测试依赖了解项目结构做重构依赖测试覆盖提交依赖 lint 和测试。如果依赖没声明agent 可能在没有前置信息的情况下硬上结果就是瞎猜。依赖声明不只是给 CLI 看的更是给 agent 看的——它知道我得先做 A 才能做 B。5.4 技能之间规则打架这个坑很隐蔽。比如快速修复技能说优先最小改动代码质量技能说发现坏味道就重构。两个技能同时加载时agent 就懵了到底改还是不改解决办法是给技能分优先级或者在技能里明确当与 X 技能冲突时以本技能为准。规则冲突是 agent 行为不稳定的重要来源值得专门花时间排查。5.5 从不更新技能项目在变技术栈在变技能却还是半年前写的。比如项目从 Jest 换成了 Vitest技能里还写着npm run jestagent 一跑就报错。我建议把技能目录纳入代码评审范围每次技术栈变更时同步检查相关技能。技能是活的文档不是一次性写完就扔的。6. 让技能真正提升产出质量的两个关键6.1 用测试验证技能而不是靠感觉既然热搜词里有 TDD那技能本身也该被测试。具体怎么做给每个技能准备一组场景用例输入一个任务描述期望 agent 加载该技能并产出符合验收标准的结果。跑一遍看通过率。比如提交前自检技能你可以准备三个用例一个正常提交、一个测试失败的提交、一个带调试残留的提交。期望结果是第一个通过后两个被拦下。如果 agent 在第二个用例里还是提交了说明技能的禁止事项没起作用得加强。这套做法听起来重但它是把调教 agent从玄学变成工程的唯一路径。没有验证你永远不知道改动是变好了还是变坏了。6.2 从真实翻车案例反推技能最好的技能不是凭空设计出来的是从真实事故里长出来的。我自己的做法是每次 agent 干了一件蠢事就记下来然后问自己如果当时有个技能它该怎么写才能拦住这件事。攒够几条就提炼成一个新技能。举个例子有次 agent 在重构时把某个函数的边界条件改错了测试没覆盖到直接提交了。事后我加了一个重构安全网技能要求重构前先确认目标代码有测试覆盖没有就先补测试再重构。这个技能后来拦住了好几次类似问题。技能库应该像事故档案一样生长而不是一次性设计完。你踩的坑越多技能库越值钱。7. 关于模型选择与接入的一点现实观察热搜词里有一堆关于 Claude Code 安装、配置、接入第三方模型的内容说明很多人关心的其实是我能不能不登录官方、用别的模型跑这套东西。这个问题我没法给你一个统一答案因为不同工具的授权策略和技术实现差异很大而且随时在变。但从工程角度有几点是通用的技能是模型无关的资产。SKILL.md写的是行为规范换哪个模型都能用。所以哪怕你以后换了底层模型技能库不用重写这是它相对提示词的一大优势。不同模型对技能的遵守度不同。同一个技能强模型可能执行得很稳弱模型可能只执行一半。所以技能设计要留冗余关键步骤最好有如果没做到就重试的兜底。接入方式影响稳定性。通过官方渠道、第三方 API、本地部署延迟和上下文窗口都可能不同进而影响技能加载和执行的稳定性。这块建议以你实际环境的实测为准别照搬别人的配置。我个人的态度是先把技能库建起来模型选择是后面的事。技能库是你能控制的资产模型是会变的变量。把可控的部分做扎实换模型时迁移成本才低。8. 我实际用下来的一些体会折腾这套东西大半年有几个感受挺深。第一技能不是越多越好。我一开始兴奋地写了十几个技能结果 agent 加载时互相干扰行为反而更乱。后来砍到五六个核心技能每个都打磨到稳定效果明显更好。技能库要精不要多。第二写技能最花时间的不是写是改。第一版技能几乎都不好用得根据 agent 的实际表现反复调触发条件和步骤描述。这个过程很像调 prompt但因为有结构、有验证比调 prompt 有章法得多。第三团队协作时技能库的价值会放大。一个人用技能库是个人效率工具一个团队用它就成了AI 编码规范的载体。新人入职不用口头交代一堆规矩把技能库给他agent 自然就按规范干活了。这种一致性是零散提示词永远给不了的。最后分享一个小技巧给每个技能写一句一句话说明放在SKILL.md最顶部。这句话不参与 agent 执行纯粹给人看。当技能多起来你翻目录时靠这句话就能快速回忆每个技能是干嘛的维护成本会低很多。这个习惯我是从写代码注释里学来的用在技能库上一样好使。