1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流模板统一收拢成一套可复用的技能包吗后来实际用下来才发现它的野心比我想的要大得多——它想解决的是**AI编码代理AI coding agents在真实工程场景下会写代码但不会干活**这个核心痛点。先说清楚这个项目是什么。agent-skills本质上是一套面向AI编码代理的技能定义与执行框架配套一个skills CLI命令行工具。你可以把它理解成给AI代理准备的工具箱操作手册每个 skill 是一个独立的能力单元比如跑测试驱动开发流程、生成并执行数据库迁移、按规范重构一个模块、审查一段代码的安全隐患。代理在接到任务后不是靠一段万能提示词硬扛而是按需加载对应的 skill按里面定义的步骤、约束、验收标准去执行。它能做什么最直接的三个价值第一把**测试驱动开发test-driven-development**这种有明确流程的方法论固化成可执行技能让代理先写测试再写实现而不是上来就堆代码第二通过skills CLI统一管理技能的安装、版本、依赖避免每个项目各写一套提示词导致行为不一致第三让代理的行为可审计、可复现——同一个 skill 在 Claude Code 里跑和在别的代理里跑流程是一致的。适合谁看如果你已经在用 Claude Code、Cursor、或者自建的编码代理并且被代理写出来的代码质量忽高忽低折磨过那这套东西值得花时间研究。如果你还在纠结 Claude Code 怎么安装、VS Code 怎么配置那建议先把基础环境跑通再回来看因为 agent-skills 是建立在代理已经能正常执行终端命令的前提之上的。我个人的判断是2024年之后AI编码代理的竞争焦点已经从模型能不能写代码转移到代理能不能可靠地完成工程任务而 agent-skills 这类项目正好卡在这个转折点上。下面我按自己的理解把它的设计思路、核心机制、实操流程和踩坑经验完整拆一遍。2. 整体设计思路为什么是技能而不是提示词2.1 提示词工程的瓶颈在哪里用过 Claude Code 或者类似工具的人应该都有体会一开始你会写一个很长的系统提示词把编码规范、测试要求、提交格式全塞进去。跑几次之后发现代理要么忽略其中一部分要么在不同任务之间互相干扰——你让它重构它顺手把测试也改了你让它修 bug它给你重写了一整个文件。这个问题的根源在于提示词是全局状态而工程任务是局部上下文。一个任务需要的是只做这件事、只碰这些文件、按这个验收标准交付但全局提示词没法表达这种局部性。你越往提示词里加规则代理的注意力就越分散。agent-skills的思路是把能力拆成独立的 skill每个 skill 自带触发条件、执行步骤、允许操作的文件范围、验收标准、失败回退策略。代理在执行任务时根据任务类型动态加载 1-2 个 skill而不是把全部规则一次性灌进去。这就好比一个工程师干活时是翻到对应的操作手册那一页而不是把整本手册背下来。2.2 技能单元应该包含哪些字段我参考了几个开源 skill 定义和自己在项目里的实践一个合格的 skill 至少要有这几块内容字段作用缺失后果name/id技能唯一标识CLI 无法索引和调用trigger什么任务该用这个技能代理乱用技能scope允许读写的路径范围代理越界改文件steps有序执行步骤流程不可复现acceptance验收标准测试通过、lint 通过等无法判断完成rollback失败时如何回退改坏了没法恢复deps依赖的其他技能或工具环境缺失导致中断这里最关键的是scope和acceptance。scope解决的是代理手太欠的问题——明确告诉它这次只能动src/parser/下的文件测试文件只读不写。acceptance解决的是代理自说自话的问题——不是它说完成了就完成了而是必须满足新增测试全部通过 原有测试不回归 lint 无新增告警这些硬条件。2.3 为什么选 CLI 而不是插件或纯配置skills CLI这个设计我觉得挺聪明。如果做成 IDE 插件就绑死在某个编辑器上如果做成纯配置文件又缺少安装、版本管理、依赖解析这些能力。CLI 的好处是它处在代理和项目之间的中间层任何能执行终端命令的代理都能调用它同时它又能像包管理器一样管理技能的来源和版本。实际用起来大概是这个感觉skills list看当前项目装了哪些技能skills add tdd-workflow从仓库拉一个技能进来skills run tdd-workflow --target src/parser让代理按这个技能干活。技能本身可以是本地目录也可以是远程仓库CLI 负责把它们同步到项目的.agent-skills/目录下。注意技能目录一定要纳入版本控制。我见过有人把.agent-skills/加进.gitignore结果换台机器代理行为完全变了排查半天才发现是技能版本不一致。3. 核心机制拆解TDD 技能是怎么跑起来的3.1 测试驱动开发为什么适合做成技能test-driven-development是 agent-skills 里最典型也最有价值的一个技能原因很简单TDD 有极其明确的阶段划分和验收信号。红-绿-重构三步每一步都有客观的完成标志——测试失败、测试通过、重构后测试仍通过。这种流程清晰、信号明确的方法论恰恰是代理最容易执行、也最容易验证的。反过来像设计一个优雅的架构这种任务就很难做成技能因为验收标准太主观。所以 agent-skills 的选型逻辑其实是优先把那些有客观验收信号的工作流技能化。3.2 一个 TDD 技能的完整执行链路我把一个 TDD 技能的执行过程拆成下面几个阶段每个阶段代理要做的事和验收条件都列清楚任务解析阶段代理读取任务描述确定要实现的函数或模块输出一份待实现清单。这一步不写任何代码只做拆解。红灯阶段针对清单里的每一项先写测试用例然后运行测试确认测试失败。这里有个关键点——必须确认失败原因是功能未实现而不是测试本身写错了。绿灯阶段写最小实现让测试通过。注意是最小实现不是完美实现目的是快速拿到反馈。重构阶段在测试保护下优化代码结构每次重构后重跑测试。验收阶段跑全量测试 lint 类型检查全部通过才算完成。这个链路里代理最容易偷懒的是第 2 步和第 3 步。很多代理会跳过确认测试失败直接写实现然后测试碰巧通过它就宣称完成了。但这样你根本不知道测试到底有没有真正覆盖到新功能。所以 skill 定义里必须强制要求红灯阶段的测试输出要作为证据保留。3.3 技能之间的组合与依赖单个技能能做的事有限真正有意思的是技能组合。比如一个实现新功能的任务实际会串起好几个技能task-breakdown把需求拆成可执行子任务tdd-workflow对每个子任务跑红绿重构code-review对产出做自检commit-convention按规范生成提交信息skills CLI需要能解析这种依赖关系按顺序加载。我在实际项目里发现技能依赖如果超过三层代理的执行稳定性会明显下降因为它要在多个技能的上下文之间切换。所以我的经验是单个任务的技能链控制在 3 个以内超过就说明任务本身该拆了。4. 实操过程从零搭一套可用的技能环境4.1 环境准备与前置条件在动手之前先确认你的环境满足这些条件。我按 Ubuntu 和 macOS 两种常见环境分别说因为热词里这两个平台的安装问题问得最多。Ubuntu 下需要的基础组件# 确认 Node 版本skills CLI 一般要求 18 以上 node -v # 确认 git 可用 git --version # 确认代理本身能执行终端命令macOS 下基本一致用brew装 Node 更省事brew install node node -v这里有个前置条件经常被忽略你的 AI 编码代理必须被授权执行终端命令。如果代理只能读写文件、不能跑命令那 skills CLI 根本调不起来。在 Claude Code 这类工具里通常需要在配置里显式开启命令执行权限并且限定允许的命令白名单。提示命令白名单建议只放npm、node、git、skills这几个别图省事开全量。代理一旦能跑任意命令误操作的风险会陡增。4.2 初始化项目技能目录进入你的项目根目录初始化技能环境# 初始化会在项目下创建 .agent-skills 目录 skills init # 查看当前可用技能 skills list # 从仓库添加一个 TDD 技能 skills add tdd-workflow # 查看技能详情确认 scope 和 acceptance 符合预期 skills show tdd-workflowskills show这一步千万别跳过。我踩过的坑就是直接add完就用结果那个技能的scope写的是整个src/代理重构时把不相关的模块也改了。后来养成习惯每次添加技能先看它的 scope 和 acceptance不符合项目约定就本地改一版。4.3 配置代理与技能的对接技能装好了还得让代理知道怎么调用。通常有两种对接方式第一种是显式调用你在给代理的指令里直接说用 tdd-workflow 技能实现 XXX。这种方式可控性最强适合关键任务。第二种是自动匹配代理根据任务描述自己判断该加载哪个技能。这种方式省事但容易误判。我的做法是关键路径用显式调用探索性任务才用自动匹配。配置上一般需要在代理的配置文件里声明技能目录的位置比如{ skills: { path: .agent-skills, autoLoad: false, allowedCommands: [npm, node, git, skills] } }autoLoad设成false是我强烈建议的默认值。让代理自动加载技能在项目初期看着很爽但一旦技能多了它会加载一堆用不上的反而拖慢执行、增加干扰。4.4 跑通第一个 TDD 任务环境搭好后拿一个小任务验证整条链路。比如实现一个解析日期字符串的函数skills run tdd-workflow --target src/utils/date-parser --task 实现 parseDate 函数支持 YYYY-MM-DD 和 YYYY/MM/DD 两种格式代理应该会按这个顺序动作先输出任务拆解然后写测试文件跑测试确认失败再写实现跑测试确认通过最后跑全量验收。你要盯的是每一步的输出证据——红灯阶段有没有真的失败输出绿灯阶段测试是不是真的从红变绿。我第一次跑的时候代理在红灯阶段写的测试直接通过了因为它写的测试根本没断言任何东西。这就是为什么 skill 定义里要强制测试必须包含至少一个断言且断言针对目标行为。这种细节只有实际跑过才会发现。5. 常见问题与排查技巧实录5.1 技能加载失败类问题现象可能原因排查方法skills list为空未在项目根目录执行pwd确认位置检查.agent-skills是否存在技能添加后代理不认代理配置的技能路径不对检查配置文件里的skills.path技能版本冲突多个技能依赖同一工具的不同版本skills tree看依赖树手动锁定版本命令执行被拒代理命令白名单没放行检查allowedCommands配置这类问题的共同点是报错信息往往不指向真正的原因。比如技能加载失败可能只是因为你不在项目根目录。我的排查习惯是先用skills doctor如果有这个命令做一次环境自检再逐项确认路径、权限、版本。5.2 代理行为异常类问题代理跑技能时最常见的异常有三种第一种是跳过红灯阶段。表现是它直接写实现然后补测试。这种情况要在 skill 定义里加硬约束红灯阶段的测试输出必须包含failed字样否则不允许进入下一阶段。第二种是越界修改文件。表现是它改了 scope 之外的文件。这通常是 scope 定义太宽或者代理忽略了 scope。解决办法是把 scope 收窄到具体文件并且在验收阶段加一步检查 git diff 是否只涉及允许的文件。第三种是验收标准被绕过。表现是测试没全过但代理说基本完成。这需要在 skill 里明确验收是二值的要么全过要么没过没有基本。实操心得给每个技能加一条证据留存要求——红灯输出、绿灯输出、最终验收输出都要写进任务日志。这样出问题时你能回溯到底哪一步被跳过了。5.3 跨环境一致性问题热词里有一堆关于不同平台安装配置的问题这背后其实是个一致性问题同一个技能在 Ubuntu、macOS、不同代理上跑行为应该一致。但现实中经常不一致原因通常是技能里用了平台相关的命令比如sed -i在 macOS 和 Linux 上参数不同依赖的工具版本不同代理本身的命令执行语义有差异我的做法是技能里的命令尽量用跨平台的写法能用 Node 脚本就不用 shell 命令实在要用 shell就在技能里声明平台要求让 CLI 在加载时做检查。这样至少能在加载阶段就发现问题而不是跑到一半才崩。5.4 技能维护的长期成本最后说个容易被低估的问题技能是会腐化的。项目代码结构变了、依赖升级了、团队规范调整了技能如果不同步更新就会从帮手变成绊脚石。我见过一个团队技能里还写着用某个已经废弃的测试框架结果代理每次跑 TDD 都在跟框架报错较劲。所以技能目录要像代码一样维护有 owner、有 review、有版本号、有变更记录。skills CLI如果支持技能版本锁定一定要用上别让技能自动升级——自动升级带来的行为突变比版本落后更难排查。6. 我对 agent-skills 这类项目的判断用了一段时间之后我越来越觉得 agent-skills 代表的方向是对的AI 编码代理的可靠性不取决于模型多强而取决于任务被拆得多细、验收标准定得多硬。一个再聪明的模型如果你让它把这个项目优化一下它也只能瞎猜但如果你给它一个明确的技能告诉它只改这个文件、先写测试、测试必须从红变绿、验收要跑全量它的表现会稳定得多。这套东西目前还不算成熟技能生态也比较早期很多技能得自己写。但它的价值在于提供了一个结构化的容器——你可以把团队积累的工程规范、踩坑经验、验收标准一点点沉淀成技能让代理替你执行。这比每次写一长串提示词要可持续得多。如果你打算上手我的建议是从一个最小技能开始别一上来就搞一套完整的技能体系。先拿 TDD 这种流程清晰的技能跑通确认代理能稳定执行再逐步扩展。技能不在多在于每个都真的能跑、真的能验收。 
长河君 · 2026/10/8 21:26:43 · 阅读 1.2k agent-skills 实战：用技能体系让 AI 编码代理可靠执行 TDD 工作流
1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流模板统一收拢成一套可复用的技能包吗后来实际用下来才发现它的野心比我想的要大得多——它想解决的是**AI编码代理AI coding agents在真实工程场景下会写代码但不会干活**这个核心痛点。先说清楚这个项目是什么。agent-skills本质上是一套面向AI编码代理的技能定义与执行框架配套一个skills CLI命令行工具。你可以把它理解成给AI代理准备的工具箱操作手册每个 skill 是一个独立的能力单元比如跑测试驱动开发流程、生成并执行数据库迁移、按规范重构一个模块、审查一段代码的安全隐患。代理在接到任务后不是靠一段万能提示词硬扛而是按需加载对应的 skill按里面定义的步骤、约束、验收标准去执行。它能做什么最直接的三个价值第一把**测试驱动开发test-driven-development**这种有明确流程的方法论固化成可执行技能让代理先写测试再写实现而不是上来就堆代码第二通过skills CLI统一管理技能的安装、版本、依赖避免每个项目各写一套提示词导致行为不一致第三让代理的行为可审计、可复现——同一个 skill 在 Claude Code 里跑和在别的代理里跑流程是一致的。适合谁看如果你已经在用 Claude Code、Cursor、或者自建的编码代理并且被代理写出来的代码质量忽高忽低折磨过那这套东西值得花时间研究。如果你还在纠结 Claude Code 怎么安装、VS Code 怎么配置那建议先把基础环境跑通再回来看因为 agent-skills 是建立在代理已经能正常执行终端命令的前提之上的。我个人的判断是2024年之后AI编码代理的竞争焦点已经从模型能不能写代码转移到代理能不能可靠地完成工程任务而 agent-skills 这类项目正好卡在这个转折点上。下面我按自己的理解把它的设计思路、核心机制、实操流程和踩坑经验完整拆一遍。2. 整体设计思路为什么是技能而不是提示词2.1 提示词工程的瓶颈在哪里用过 Claude Code 或者类似工具的人应该都有体会一开始你会写一个很长的系统提示词把编码规范、测试要求、提交格式全塞进去。跑几次之后发现代理要么忽略其中一部分要么在不同任务之间互相干扰——你让它重构它顺手把测试也改了你让它修 bug它给你重写了一整个文件。这个问题的根源在于提示词是全局状态而工程任务是局部上下文。一个任务需要的是只做这件事、只碰这些文件、按这个验收标准交付但全局提示词没法表达这种局部性。你越往提示词里加规则代理的注意力就越分散。agent-skills的思路是把能力拆成独立的 skill每个 skill 自带触发条件、执行步骤、允许操作的文件范围、验收标准、失败回退策略。代理在执行任务时根据任务类型动态加载 1-2 个 skill而不是把全部规则一次性灌进去。这就好比一个工程师干活时是翻到对应的操作手册那一页而不是把整本手册背下来。2.2 技能单元应该包含哪些字段我参考了几个开源 skill 定义和自己在项目里的实践一个合格的 skill 至少要有这几块内容字段作用缺失后果name/id技能唯一标识CLI 无法索引和调用trigger什么任务该用这个技能代理乱用技能scope允许读写的路径范围代理越界改文件steps有序执行步骤流程不可复现acceptance验收标准测试通过、lint 通过等无法判断完成rollback失败时如何回退改坏了没法恢复deps依赖的其他技能或工具环境缺失导致中断这里最关键的是scope和acceptance。scope解决的是代理手太欠的问题——明确告诉它这次只能动src/parser/下的文件测试文件只读不写。acceptance解决的是代理自说自话的问题——不是它说完成了就完成了而是必须满足新增测试全部通过 原有测试不回归 lint 无新增告警这些硬条件。2.3 为什么选 CLI 而不是插件或纯配置skills CLI这个设计我觉得挺聪明。如果做成 IDE 插件就绑死在某个编辑器上如果做成纯配置文件又缺少安装、版本管理、依赖解析这些能力。CLI 的好处是它处在代理和项目之间的中间层任何能执行终端命令的代理都能调用它同时它又能像包管理器一样管理技能的来源和版本。实际用起来大概是这个感觉skills list看当前项目装了哪些技能skills add tdd-workflow从仓库拉一个技能进来skills run tdd-workflow --target src/parser让代理按这个技能干活。技能本身可以是本地目录也可以是远程仓库CLI 负责把它们同步到项目的.agent-skills/目录下。注意技能目录一定要纳入版本控制。我见过有人把.agent-skills/加进.gitignore结果换台机器代理行为完全变了排查半天才发现是技能版本不一致。3. 核心机制拆解TDD 技能是怎么跑起来的3.1 测试驱动开发为什么适合做成技能test-driven-development是 agent-skills 里最典型也最有价值的一个技能原因很简单TDD 有极其明确的阶段划分和验收信号。红-绿-重构三步每一步都有客观的完成标志——测试失败、测试通过、重构后测试仍通过。这种流程清晰、信号明确的方法论恰恰是代理最容易执行、也最容易验证的。反过来像设计一个优雅的架构这种任务就很难做成技能因为验收标准太主观。所以 agent-skills 的选型逻辑其实是优先把那些有客观验收信号的工作流技能化。3.2 一个 TDD 技能的完整执行链路我把一个 TDD 技能的执行过程拆成下面几个阶段每个阶段代理要做的事和验收条件都列清楚任务解析阶段代理读取任务描述确定要实现的函数或模块输出一份待实现清单。这一步不写任何代码只做拆解。红灯阶段针对清单里的每一项先写测试用例然后运行测试确认测试失败。这里有个关键点——必须确认失败原因是功能未实现而不是测试本身写错了。绿灯阶段写最小实现让测试通过。注意是最小实现不是完美实现目的是快速拿到反馈。重构阶段在测试保护下优化代码结构每次重构后重跑测试。验收阶段跑全量测试 lint 类型检查全部通过才算完成。这个链路里代理最容易偷懒的是第 2 步和第 3 步。很多代理会跳过确认测试失败直接写实现然后测试碰巧通过它就宣称完成了。但这样你根本不知道测试到底有没有真正覆盖到新功能。所以 skill 定义里必须强制要求红灯阶段的测试输出要作为证据保留。3.3 技能之间的组合与依赖单个技能能做的事有限真正有意思的是技能组合。比如一个实现新功能的任务实际会串起好几个技能task-breakdown把需求拆成可执行子任务tdd-workflow对每个子任务跑红绿重构code-review对产出做自检commit-convention按规范生成提交信息skills CLI需要能解析这种依赖关系按顺序加载。我在实际项目里发现技能依赖如果超过三层代理的执行稳定性会明显下降因为它要在多个技能的上下文之间切换。所以我的经验是单个任务的技能链控制在 3 个以内超过就说明任务本身该拆了。4. 实操过程从零搭一套可用的技能环境4.1 环境准备与前置条件在动手之前先确认你的环境满足这些条件。我按 Ubuntu 和 macOS 两种常见环境分别说因为热词里这两个平台的安装问题问得最多。Ubuntu 下需要的基础组件# 确认 Node 版本skills CLI 一般要求 18 以上 node -v # 确认 git 可用 git --version # 确认代理本身能执行终端命令macOS 下基本一致用brew装 Node 更省事brew install node node -v这里有个前置条件经常被忽略你的 AI 编码代理必须被授权执行终端命令。如果代理只能读写文件、不能跑命令那 skills CLI 根本调不起来。在 Claude Code 这类工具里通常需要在配置里显式开启命令执行权限并且限定允许的命令白名单。提示命令白名单建议只放npm、node、git、skills这几个别图省事开全量。代理一旦能跑任意命令误操作的风险会陡增。4.2 初始化项目技能目录进入你的项目根目录初始化技能环境# 初始化会在项目下创建 .agent-skills 目录 skills init # 查看当前可用技能 skills list # 从仓库添加一个 TDD 技能 skills add tdd-workflow # 查看技能详情确认 scope 和 acceptance 符合预期 skills show tdd-workflowskills show这一步千万别跳过。我踩过的坑就是直接add完就用结果那个技能的scope写的是整个src/代理重构时把不相关的模块也改了。后来养成习惯每次添加技能先看它的 scope 和 acceptance不符合项目约定就本地改一版。4.3 配置代理与技能的对接技能装好了还得让代理知道怎么调用。通常有两种对接方式第一种是显式调用你在给代理的指令里直接说用 tdd-workflow 技能实现 XXX。这种方式可控性最强适合关键任务。第二种是自动匹配代理根据任务描述自己判断该加载哪个技能。这种方式省事但容易误判。我的做法是关键路径用显式调用探索性任务才用自动匹配。配置上一般需要在代理的配置文件里声明技能目录的位置比如{ skills: { path: .agent-skills, autoLoad: false, allowedCommands: [npm, node, git, skills] } }autoLoad设成false是我强烈建议的默认值。让代理自动加载技能在项目初期看着很爽但一旦技能多了它会加载一堆用不上的反而拖慢执行、增加干扰。4.4 跑通第一个 TDD 任务环境搭好后拿一个小任务验证整条链路。比如实现一个解析日期字符串的函数skills run tdd-workflow --target src/utils/date-parser --task 实现 parseDate 函数支持 YYYY-MM-DD 和 YYYY/MM/DD 两种格式代理应该会按这个顺序动作先输出任务拆解然后写测试文件跑测试确认失败再写实现跑测试确认通过最后跑全量验收。你要盯的是每一步的输出证据——红灯阶段有没有真的失败输出绿灯阶段测试是不是真的从红变绿。我第一次跑的时候代理在红灯阶段写的测试直接通过了因为它写的测试根本没断言任何东西。这就是为什么 skill 定义里要强制测试必须包含至少一个断言且断言针对目标行为。这种细节只有实际跑过才会发现。5. 常见问题与排查技巧实录5.1 技能加载失败类问题现象可能原因排查方法skills list为空未在项目根目录执行pwd确认位置检查.agent-skills是否存在技能添加后代理不认代理配置的技能路径不对检查配置文件里的skills.path技能版本冲突多个技能依赖同一工具的不同版本skills tree看依赖树手动锁定版本命令执行被拒代理命令白名单没放行检查allowedCommands配置这类问题的共同点是报错信息往往不指向真正的原因。比如技能加载失败可能只是因为你不在项目根目录。我的排查习惯是先用skills doctor如果有这个命令做一次环境自检再逐项确认路径、权限、版本。5.2 代理行为异常类问题代理跑技能时最常见的异常有三种第一种是跳过红灯阶段。表现是它直接写实现然后补测试。这种情况要在 skill 定义里加硬约束红灯阶段的测试输出必须包含failed字样否则不允许进入下一阶段。第二种是越界修改文件。表现是它改了 scope 之外的文件。这通常是 scope 定义太宽或者代理忽略了 scope。解决办法是把 scope 收窄到具体文件并且在验收阶段加一步检查 git diff 是否只涉及允许的文件。第三种是验收标准被绕过。表现是测试没全过但代理说基本完成。这需要在 skill 里明确验收是二值的要么全过要么没过没有基本。实操心得给每个技能加一条证据留存要求——红灯输出、绿灯输出、最终验收输出都要写进任务日志。这样出问题时你能回溯到底哪一步被跳过了。5.3 跨环境一致性问题热词里有一堆关于不同平台安装配置的问题这背后其实是个一致性问题同一个技能在 Ubuntu、macOS、不同代理上跑行为应该一致。但现实中经常不一致原因通常是技能里用了平台相关的命令比如sed -i在 macOS 和 Linux 上参数不同依赖的工具版本不同代理本身的命令执行语义有差异我的做法是技能里的命令尽量用跨平台的写法能用 Node 脚本就不用 shell 命令实在要用 shell就在技能里声明平台要求让 CLI 在加载时做检查。这样至少能在加载阶段就发现问题而不是跑到一半才崩。5.4 技能维护的长期成本最后说个容易被低估的问题技能是会腐化的。项目代码结构变了、依赖升级了、团队规范调整了技能如果不同步更新就会从帮手变成绊脚石。我见过一个团队技能里还写着用某个已经废弃的测试框架结果代理每次跑 TDD 都在跟框架报错较劲。所以技能目录要像代码一样维护有 owner、有 review、有版本号、有变更记录。skills CLI如果支持技能版本锁定一定要用上别让技能自动升级——自动升级带来的行为突变比版本落后更难排查。6. 我对 agent-skills 这类项目的判断用了一段时间之后我越来越觉得 agent-skills 代表的方向是对的AI 编码代理的可靠性不取决于模型多强而取决于任务被拆得多细、验收标准定得多硬。一个再聪明的模型如果你让它把这个项目优化一下它也只能瞎猜但如果你给它一个明确的技能告诉它只改这个文件、先写测试、测试必须从红变绿、验收要跑全量它的表现会稳定得多。这套东西目前还不算成熟技能生态也比较早期很多技能得自己写。但它的价值在于提供了一个结构化的容器——你可以把团队积累的工程规范、踩坑经验、验收标准一点点沉淀成技能让代理替你执行。这比每次写一长串提示词要可持续得多。如果你打算上手我的建议是从一个最小技能开始别一上来就搞一套完整的技能体系。先拿 TDD 这种流程清晰的技能跑通确认代理能稳定执行再逐步扩展。技能不在多在于每个都真的能跑、真的能验收。