1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我的直觉是这大概率不是一个“工具”而是一套给 AI coding agent 用的能力包。后来翻了一圈资料基本印证了这个判断——它本质上是一个围绕skills CLI构建的、面向AI coding agents的技能集合与调度层核心目标是把“让 AI 写代码”这件事从“随口一问”变成“按流程、按规范、可复用”的工程化动作。说白了它解决的是这么几个痛点你手上有 Claude Code、有各种支持 agent 的编辑器、有本地模型或第三方 API但每次让 AI 干活都得重新描述需求、重新定规矩、重新盯质量。agent-skills想做的就是把这些“规矩”沉淀成可调用的技能让 agent 在需要的时候自己加载、自己执行、自己验证。它适合谁适合已经在用 Claude Code 或类似 AI coding agent、并且开始觉得“光靠聊天不够用”的开发者也适合那些想把test-driven-development这类工程实践塞进 AI 工作流的人。我自己的判断是这个项目真正的价值不在“技能数量”而在“技能怎么被组织、怎么被触发、怎么和 CLI 配合”。下面我就按我实际折腾下来的顺序把整体设计、核心细节、实操过程和踩坑记录拆开讲。2. 整体设计与思路拆解为什么是 skills CLI agent 的组合2.1 核心思路把“提示词”升级成“可执行技能”传统用 AI coding agent 的方式基本是“对话驱动”你描述需求它生成代码你再检查。问题在于需求描述本身不稳定今天说“写个测试”明天说“补个单测”agent 理解出来的东西可能完全不一样。agent-skills的思路是把这些重复出现的动作抽象成skill——一个 skill 里包含触发条件、执行步骤、验证标准甚至依赖的其他 skill。而skills CLI就是这套体系的入口。它负责技能的安装、列举、调用和版本管理。你可以把它理解成“给 agent 用的包管理器”agent 不需要知道技能内部怎么实现只需要知道“我现在该调用哪个 skill”。这种分层的好处很明显——技能可以独立迭代agent 的提示词可以保持精简两者解耦。我试过把同一个需求分别用“纯对话”和“skill 调用”两种方式跑后者在一致性上明显更稳。尤其是涉及test-driven-development这种有固定节奏的流程时skill 能把“先写测试、再写实现、最后重构”这个顺序固化下来agent 不会因为上下文变长就忘了先写测试。2.2 方案选型为什么不是插件而是 CLI 技能目录很多人会问为什么不直接做成编辑器插件我的理解是插件绑定编辑器而 CLI 绑定工作流。Claude Code 本身就有终端执行能力skills CLI 以命令行形式存在意味着它可以在本地终端、CI 环境、甚至远程开发机里用同一套逻辑。技能目录则是纯文件结构方便版本控制和团队共享。另一个考量是模型无关性。热词里提到“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”说明大家并不想被单一模型锁死。skills CLI 如果设计成模型无关那技能本身就不依赖某个特定模型的输出格式换模型时只需要调整调用层。这一点在实际使用中很关键——我换过不同模型跑同一套 skill只要 skill 的输入输出约定清楚切换成本很低。2.3 避免的问题技能膨胀与触发混乱任何技能体系做大了都会遇到两个问题一是技能太多agent 不知道该用哪个二是技能之间依赖复杂调用链一长就失控。agent-skills在结构上应该是通过命名空间和分类来缓解这个问题。我自己的经验是技能数量控制在“一个工作流 5 到 8 个”比较合适再多就需要更明确的触发词和优先级。提示如果你打算自己往agent-skills里加技能先问自己一句——这个动作会不会在三个以上项目里重复出现如果不会就别急着做成 skill先留在提示词里。3. 核心细节解析与实操要点技能结构、CLI 命令与 TDD 落地3.1 一个 skill 到底包含什么虽然具体文件格式可能因版本而异但按常见实践一个 skill 至少包含这几块元信息名称、描述、触发条件、执行步骤有序的操作列表、验证标准怎么算完成、依赖声明需要哪些工具或其他 skill。我见过比较成熟的写法是把执行步骤写成类似伪代码的流程每一步都明确输入和输出。这里有个细节容易被忽略触发条件要写得“窄”一点。比如“当用户要求写测试时触发”就太宽容易在无关场景被调用写成“当用户要求为新增函数补充单元测试且项目使用 pytest 时触发”就精准得多。我踩过的坑就是触发词太泛结果 agent 在改配置的时候也去调测试 skill白白浪费一轮。3.2 skills CLI 的常用操作与参数逻辑CLI 的核心命令一般围绕list、install、run、update这几个动作。以我实际用下来的习惯流程是这样的先用list看当前有哪些技能可用确认版本然后用install把需要的技能拉到本地技能目录执行时通过run skill-name触发必要时带上参数。参数设计上我建议重点关注两类一类是上下文参数比如项目路径、目标文件另一类是行为参数比如“只生成不执行”“执行但跳过验证”。这两类分开之后同一个 skill 可以在不同严格程度下复用。比如在本地开发时用宽松模式快速迭代在提交前用严格模式跑完整验证。# 列举当前可用技能 skills list # 安装指定技能到本地技能目录 skills install test-driven-development # 运行技能指定项目路径与严格模式 skills run test-driven-development --path ./src --strict上面这段命令是示意性的具体子命令名称请以你本地 CLI 的--help输出为准。我的习惯是先把--help完整看一遍把常用参数记下来比遇到问题再查快得多。3.3 把 test-driven-development 做成 skill 的关键点TDD 本身流程固定红、绿、重构。但要让 agent 严格执行需要在 skill 里把每一步的“完成信号”定义清楚。红阶段测试必须失败且失败原因是因为功能未实现而不是语法错误绿阶段实现代码让测试通过且不引入新失败重构阶段测试仍然全绿代码结构改善。我实际配置时加了一条额外规则每个阶段结束后agent 必须输出当前测试运行结果摘要。这样即使中间某一步跑偏也能从日志里快速定位。另一个经验是TDD skill 最好和“代码审查 skill”解耦否则一次调用做太多事失败时很难判断是测试写错了还是审查规则太严。注意TDD skill 在首次运行时如果项目里还没有测试框架应该先触发“环境准备”类 skill而不是直接让 agent 硬写测试文件。顺序错了后面全是补丁。4. 实操过程与核心环节实现从安装到跑通一条完整链路4.1 环境准备Claude Code 与 skills CLI 的安装顺序按热词里的关注点很多人卡在安装环节。我的建议顺序是先装好 Claude Code或你用的其他 AI coding agent确认它能正常在终端执行命令再装 skills CLI并确保 CLI 的可执行路径在PATH里。Ubuntu 和 macOS 上的差异主要在包管理器和路径配置Windows 下如果用 WSL基本可以按 Ubuntu 的方式走。安装完成后先跑一个最小验证让 agent 执行一条简单命令比如列出当前目录确认终端执行链路是通的。这一步不过后面所有 skill 调用都会失败。我见过有人跳过这步结果 skill 装好了但 agent 根本调不动排查半天才发现是权限问题。4.2 技能目录初始化与第一个 skill 的加载技能目录一般放在项目根目录下的隐藏文件夹或者用户主目录下的全局配置目录。我的做法是项目级技能放项目里通用技能放全局通过 CLI 的查找顺序来覆盖。初始化时先建目录结构再放入第一个 skill 文件然后用list确认能被识别。加载第一个 skill 时建议选最简单的比如“生成函数注释”或“格式化代码”。目的是验证整条链路CLI 能找到 skill、agent 能读取 skill、执行结果能返回。这个最小闭环跑通之后再上 TDD 这种复杂 skill心里有底。4.3 完整跑一次 TDD 流程的记录我拿一个实际的小需求试过给一个已有的工具函数增加边界处理。流程是这样的先调用 TDD skillagent 读取 skill 定义后第一步生成针对边界条件的测试用例运行测试确认失败然后生成实现代码再运行测试确认通过最后做一次小重构去掉重复判断。整个过程里我干预了两次一次是测试用例覆盖不够我补充了一条一次是重构阶段 agent 想改公共接口我制止了。这说明 skill 能固化流程但不能替代人的判断。我的体会是把 skill 当成“流程脚手架”而不是“全自动流水线”心态会稳很多。# 示意运行 TDD skill 并输出详细日志 skills run test-driven-development --path ./src/utils --verbose # 查看最近一次 skill 执行记录 skills log --last 14.4 与第三方模型配合时的调整点热词里提到接入 deepseek、qwen、glm 等模型我实际换过其中一两个。切换模型后最明显的变化是输出格式稳定性。有的模型更愿意按步骤走有的模型喜欢一次性给一大段。这时候 skill 里的“验证标准”就很重要——不管模型怎么输出只要验证不通过就要求重试或修正。我的调整策略是在 skill 里增加一个“输出格式检查”步骤要求 agent 在关键节点输出结构化摘要。这样即使换模型也能通过格式检查快速判断是否跑偏。另外不同模型对长上下文的表现不同技能步骤尽量拆短避免一次给太多指令。5. 常见问题与排查技巧实录踩过的坑和速查表5.1 技能不触发或触发错误最常见的问题是 skill 没被调用或者在不该调用的时候被调用。排查顺序先看触发条件是否写得太宽或太窄再看 CLI 的技能查找路径是否正确最后看 agent 的提示词里有没有覆盖 skill 的调用逻辑。我遇到过一次是技能目录权限不对CLI 读不到文件但错误提示很隐晦后来用list --debug才看出来。5.2 执行中断与超时长流程 skill 容易在中间步骤超时尤其是涉及多次测试运行的时候。我的处理办法是把大 skill 拆成小 skill每个小 skill 只做一件事通过 CLI 串联。这样单步超时不会导致整个流程重来。另外给测试类步骤设置合理的超时时间别用默认值硬扛。5.3 模型切换后的行为差异换模型后如果发现 skill 执行结果不稳定先别急着改 skill先跑几次同样的输入看是偶发还是必现。偶发的话可能是模型采样问题必现的话再检查 skill 里的指令是否依赖了某个模型的特定输出习惯。我的经验是把 skill 里的自然语言指令写得尽量“模型中立”少用“像之前那样”这种依赖上下文的表述。问题现象可能原因排查动作解决方向skill 完全不触发触发条件不匹配或路径错误用list --debug检查加载修正触发词或路径执行到一半停止单步超时或权限不足查看执行日志最后一步拆 skill 或调整超时换模型后结果乱输出格式不稳定对比多次运行结果增加格式检查步骤测试一直失败环境未准备或依赖缺失手动跑一次测试命令先补环境准备 skill5.4 独家避坑技巧第一个技巧给每个 skill 加一个“干跑模式”只输出计划不执行用来快速验证触发和步骤是否正确。第二个技巧技能版本用语义化版本号管理改触发条件算小版本改执行步骤算大版本方便回滚。第三个技巧把 skill 的执行日志统一收集到一个目录出问题时按时间排序看比翻终端历史快得多。提示如果你在团队里推广agent-skills先从一个人用顺了再推广别一上来就要求所有人改工作流。工具的价值需要场景验证强推容易反弹。6. 技能扩展与长期维护让这套东西真正用得住6.1 什么时候该新增 skill我的判断标准是“重复三次以上且步骤稳定”。如果某个操作你已经在三个项目里手动做过而且每次步骤基本一样那就值得做成 skill。反之如果步骤每次都要根据情况调整那更适合留在提示词里或者做成半自动的检查清单。新增 skill 时先写验证标准再写执行步骤。这个顺序很重要——先想清楚“怎么算做完”再去设计“怎么做”能避免 skill 越写越臃肿。我见过不少 skill 失败是因为验证标准模糊agent 觉得做完了人觉得没做完。6.2 技能之间的依赖管理技能依赖尽量保持单向避免循环依赖。如果 A 依赖 BB 又依赖 A调用链会变得不可预测。我的做法是把公共步骤抽成基础 skill上层 skill 只做组合。比如“环境准备”是基础 skill“TDD”依赖它“代码审查”也依赖它但基础 skill 不依赖任何上层 skill。6.3 与 Claude Code 工作流的结合点Claude Code 本身有终端执行能力skills CLI 可以作为它的一个“外部工具”来调用。结合点主要有三个一是用 skill 来约束 Claude Code 的执行顺序二是用 skill 的验证标准来做质量门禁三是用 skill 日志来做过程追溯。我实际用下来最有用的是第二点——在提交代码前跑一遍审查类 skill能挡掉不少低级问题。6.4 后续可以扩展的方向从agent-skills这个结构出发后面可以往几个方向走一是增加更多领域 skill比如数据库迁移、API 契约测试二是做 skill 的市场或共享机制让团队之间能交换三是把 skill 执行结果接入 CI做成自动门禁。不过这些都是后话先把核心的 TDD 和代码审查跑顺比什么都实在。我个人在实际操作中的体会是agent-skills这类项目的价值不在于它自带多少技能而在于它提供了一种“把工程规范翻译成 agent 能执行的动作”的思路。你完全可以从一个最小的 skill 开始慢慢积累等哪天发现 agent 干活越来越像团队里那个靠谱的同事这套东西就算用到位了。