★ FEATURED ARTICLE 1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这大概率不是一个应用而是一套能力包。事实也确实如此——它把 AI coding agent 需要具备的各类技能按目录拆成一个个可独立加载的模块配合 skills CLI 做安装、分发和版本管理。换句话说它解决的不是模型够不够聪明而是模型知不知道在你的项目里该怎么干活。这个区分很关键。很多人上手 Claude Code 之后的第一反应是它怎么老是不按我的规范来——命名风格不对、测试不写、提交信息乱、目录结构乱放。问题往往不在模型能力而在于你没有把项目的隐性规则显性化。agent-skills这类技能库的价值就是把这些规则沉淀成 agent 能读、能执行、能复用的结构化文件。它适合谁三类人最该关注一是已经在用 Claude Code、Codex 这类 AI coding agent 做日常开发但总觉得差一口气的工程师二是团队里负责工程规范、想把规范落到工具层的人三是想自己写 skill、做定制化 agent 工作流的进阶玩家。如果你还没装过 Claude Code也没关系这篇会顺带把安装、配置、接入第三方模型的路径讲清楚因为技能库脱离运行环境是跑不起来的。我下面会按先搞懂它是什么 → 再搞懂它怎么跑起来 → 然后搞懂怎么写出好用的 skill → 最后讲踩坑的顺序展开。全程按我实际折腾下来的经验讲不绕弯子。2. agent-skills 到底解决了什么问题2.1 它不是提示词模板而是可执行的能力单元很多人把 skill 理解成一段写好的 prompt这个理解偏了。一个合格的 skill 通常包含三部分触发条件什么时候该用、执行指令具体怎么做、验证标准做完怎么算对。它更像一份写给新同事的 SOP而不是一句帮我写个测试。以 test-driven-development 这个技能为例。它不是告诉你要写测试而是规定了一套流程先写失败的测试 → 跑一遍确认它确实失败 → 写最小实现让它通过 → 重构 → 再跑。每一步都有明确的动作和判定。agent 读到这个 skill 之后行为会从随手补个测试变成严格按红绿重构走。这就是 skill 和 prompt 的本质差别prompt 是意图skill 是流程。意图可以被模型自由发挥流程则约束了发挥的边界。2.2 为什么技能比更大的模型更划算我做过一个对比。同一个重构任务用基础 agent 跑它会改代码但经常漏掉边界情况加载了对应 skill 之后它会主动去检查调用方、补测试、更新文档。两次用的模型完全一样差别只在有没有 skill。这背后的逻辑不难理解。模型的能力是通用的但工程实践是高度场景化的。你不可能指望一个通用模型天然知道你们团队所有 API 变更必须同步更新 changelog这种规矩。与其反复在对话里纠正不如把规矩写进 skill一次写好长期生效。从成本角度看也很划算。写一个 skill 可能花你半小时但它会在之后几十上百次任务里持续起作用。相比之下每次都在 prompt 里重复交代规范既费 token 又容易漏。2.3 技能库的组织方式目录即能力agent-skills这类仓库通常按目录组织每个子目录是一个独立技能里面放一个描述文件一般是 markdown 或带 frontmatter 的 md说明这个技能的用途、触发场景、执行步骤。skills CLI 负责把这些目录安装到 agent 能识别的路径下。这种目录即能力的设计有个好处可组合。你可以只装测试相关的技能也可以把代码审查、提交规范、文档生成一起装上。技能之间通过约定而非硬编码耦合想加就加想删就删不会互相打架。提示装技能之前先想清楚你的痛点是什么。一次性装几十个技能反而会让 agent 在触发时犹豫效果不如精准装几个。3. 把运行环境搭起来Claude Code 安装与配置技能库要跑起来得先有个能加载它的 agent 运行时。目前最主流的选择是 Claude Code。这一节把安装、配置、接入第三方模型的路径讲透因为后面所有实操都依赖这个环境。3.1 安装路径按你的系统选Claude Code 的安装方式随平台不同。macOS 和 Linux 上官方推荐用包管理器或安装脚本Windows 上则通常走 WSL 或者桌面版。我实测下来Ubuntu 和 macOS 的体验最顺Windows 原生环境偶尔会有路径和权限的小问题。安装完成后第一件事是验证版本和可用性claude --version claude doctordoctor这个子命令很实用它会检查你的环境是否满足运行条件包括依赖、权限、配置路径等。如果提示某些区域不可用那是服务可用性层面的限制属于正常现象按提示处理即可。3.2 VS Code 插件让 agent 贴着代码干活纯终端用 Claude Code 没问题但如果你想要选中一段代码直接让它改的体验VS Code 插件更顺手。安装插件后需要在设置里确认几件事CLI 的可执行路径是否正确、工作区信任是否开启、终端集成是否启用。我踩过的一个坑是插件装了但一直提示找不到 CLI。原因是插件默认去 PATH 里找而我的 CLI 装在了一个非标准路径。解决办法是在插件设置里显式指定可执行文件路径。这个细节官方文档里提得不多但实际很常见。配置好之后你可以在编辑器里直接唤起 agent让它读当前文件、当前选区甚至整个工作区。配合 skill它就能按你定义的规范来改代码而不是自由发挥。3.3 接入第三方模型什么时候需要怎么配Claude Code 默认走官方模型。但有些场景下你会想接第三方模型——比如成本考虑、比如想用某个特定能力的模型。这时候就需要一个模型切换层把请求路由到不同后端。配置的核心是两件事一是 API 端点二是模型标识。通常通过环境变量或配置文件指定。以常见的做法为例export ANTHROPIC_BASE_URL你的端点 export ANTHROPIC_API_KEY你的密钥然后在配置里指定模型名。不同模型对工具调用tool use的支持程度不一样这一点很关键——skill 的执行依赖工具调用能力如果模型不支持或者支持得不好skill 就跑不起来。注意接第三方模型时务必确认它支持 function calling / tool use。不支持的话agent 只能聊天没法真正执行文件操作和命令skill 也就成了摆设。3.4 登录与不登录的差别Claude Code 支持登录账号使用也支持用 API key 直接跑。两者的差别主要在配额管理和功能完整度上。登录方式通常有更完整的会话管理和额度视图API key 方式更灵活适合接第三方或做自动化。如果你只是本地折腾、跑跑 skillAPI key 方式足够。如果是团队协作、需要统一管理登录方式更省心。这个选择没有绝对优劣看你的使用场景。4. 用 skills CLI 管理你的技能库环境搭好之后下一步是把agent-skills装进来。这一节讲 CLI 的用法和我实际用下来的心得。4.1 安装与初始化skills CLI 一般通过包管理器分发。装好之后第一步通常是初始化它会在你的配置目录下建好技能存放路径。初始化完成后你可以用命令列出当前已安装的技能、查看某个技能的详情、或者从仓库拉取新技能。我建议初始化之后先跑一次list看看默认带了哪些技能。有些发行版会预置几个基础技能比如代码格式化、提交信息生成这些可以直接用。4.2 安装单个技能 vs 批量安装CLI 通常支持两种模式装单个技能或者装整个仓库。我的经验是分阶段来第一阶段只装你最痛的那个点对应的技能比如测试规范用一两周确认它确实改善了工作流再逐步加代码审查、文档、提交规范等一次性全装的问题在于你分不清是哪个技能在起作用出了问题也不好定位。渐进式安装让你能清楚看到每个技能带来的变化。4.3 技能目录的结构长什么样一个典型的技能目录大概是这样skills/ test-driven-development/ SKILL.md examples/ code-review/ SKILL.mdSKILL.md是核心里面通常有 frontmatter 描述元信息名称、描述、触发条件正文则是具体的执行指令。examples/放一些示例帮助 agent 理解期望的输入输出。理解这个结构很重要因为你要写自己的 skill 时就是照着这个结构来。元信息写得好不好直接决定 agent 能不能在正确的时机触发这个技能。4.4 版本管理与更新技能库会迭代CLI 一般提供更新命令。我的做法是更新前先看 changelog确认没有破坏性变更再更。如果是团队共用最好把技能版本固定下来避免今天能跑明天不能跑的情况。提示把技能库纳入版本控制和代码一起管理。这样团队每个人的 agent 行为是一致的不会出现你那边能跑我这边不行。5. 写出一个真正好用的 skill装别人的技能是入门写自己的技能才是进阶。这一节讲我总结的写法。5.1 触发条件要写得窄而不是宽新手写 skill 最容易犯的错是把触发条件写得太宽。比如写当需要写代码时触发这等于没写因为几乎所有任务都在写代码。结果就是 agent 频繁误触发反而干扰正常流程。好的触发条件应该窄而具体。比如当用户要求新增一个 API 端点时触发或者当检测到测试文件被修改但实现文件未同步修改时触发。窄触发让技能在真正需要的时候才介入。5.2 执行步骤要可验证skill 里的每一步最好都能对应一个可观察的结果。不要说确保代码质量良好而要说运行 lint 命令确认无 error 级别告警。前者无法验证后者跑一下就知道。以 test-driven-development 为例它的步骤应该是根据需求写一个测试运行它确认失败写最小实现运行测试确认通过重构再次运行测试确认仍通过检查覆盖率是否达到约定阈值每一步都有明确的命令和判定标准agent 执行起来不会含糊。5.3 用示例代替长篇解释与其用大段文字解释什么是好的提交信息不如直接给三五个正例和反例。模型对示例的敏感度远高于抽象描述。我在写 skill 时示例部分往往占一半篇幅效果比纯文字说明好得多。5.4 给技能留退出条件有些任务 agent 会陷入循环反复改也改不对。好的 skill 应该定义退出条件比如如果连续三次测试仍失败停止并报告问题不要继续尝试。这能避免 agent 在死胡同里浪费时间和 token。6. 实测中踩过的坑与排查思路这一节讲我实际遇到的问题以及怎么一步步定位的。这些经验在官方文档里基本找不到。6.1 技能装了但 agent 不触发现象技能明明装好了list也能看到但 agent 干活时完全不用它。排查链路先确认技能路径是否在 agent 的扫描范围内。有些 CLI 装到了 A 目录agent 却只扫 B 目录检查SKILL.md的 frontmatter 格式是否正确。YAML 缩进错一个空格整个元信息就解析失败看触发条件是否写得太窄或太宽。太窄永远不触发太宽则被其他技能抢占最后看模型是否支持工具调用。不支持的话技能加载了也没法执行我遇到的那次根因是 frontmatter 里的描述字段用了中文引号解析器不认。换成英文引号就好了。这种问题不看日志根本发现不了。6.2 多个技能互相打架现象装了两个技能后agent 行为变得很奇怪一会儿按 A 的流程走一会儿按 B 的走。根因通常是两个技能的触发条件有重叠。比如一个技能说修改代码时触发另一个说重构时触发而重构本身就是修改代码于是两个都触发指令冲突。解决办法是给触发条件加优先级或者在技能里明确本技能不处理 X 情况交给 Y 技能。技能之间的边界要划清楚。6.3 第三方模型下技能执行不稳定接第三方模型后同样的 skill 有时能跑通有时跑到一半就停了。排查下来多半是模型对工具调用的支持不完整——比如能调用读文件但调用写文件时参数格式不对。这种情况没有万能解。我的做法是先用最简单的 skill 测试模型的工具调用能力确认基础能力没问题再逐步加复杂度。如果某个模型在工具调用上确实弱那就别硬上换一个。6.4 更新技能后行为突变技能库更新后原本好用的流程突然不灵了。这通常是上游改了触发条件或执行步骤。我的应对是更新前先在测试项目里跑一遍确认行为符合预期再推到主项目。团队场景下技能版本要和代码版本一样对待不能随便更。7. 把技能库用出复利我的几条实践原则折腾了这么久我最大的体会是技能库的价值不在装了多少而在沉淀了多少你自己的规范。别人的技能解决通用问题你的技能解决你的问题。第一条原则是从痛点出发不从功能出发。不要因为某个技能看起来很酷就装它要因为你确实被某个问题反复困扰才去写它。痛点驱动的技能使用率最高。第二条是技能要短示例要多。一个技能如果超过两屏agent 读起来就吃力了。把复杂流程拆成多个小技能每个只干一件事组合起来反而更强。第三条是定期清理。用了一段时间后你会发现有些技能从来没触发过有些则频繁误触发。前者删掉后者改触发条件。技能库和代码一样需要维护不然会越来越臃肿。最后分享一个小技巧把你最常用的三五个技能在项目根目录放一个简短的说明文件写清楚每个技能什么时候用。这样不仅 agent 能参考新加入的同事也能快速理解你们的工程规范。技能库从工具变成了团队知识资产这才是它最大的价值。
阅读完成 · 觉得有帮助？
