1. 从 agent-skills 说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agents 装“技能包”的机制。你可以把它理解成模型本身是大脑但大脑不负责记住你团队所有的规范、脚本、检查清单和踩坑经验agent-skills干的事就是把这些“可复用的做事方法”抽出来做成一个个独立的技能单元让 agent 在需要的时候按需加载。这件事为什么现在特别值得聊因为过去一年我用 Claude Code、以及各种接入第三方模型的 coding agent 做项目最大的痛点从来不是“模型不会写代码”而是它每次都像第一天上班不知道我们仓库的目录约定不知道测试怎么跑不知道提交前要过哪几道检查甚至不知道我们内部那个构建脚本叫什么名字。你每次都得在 prompt 里重新交代一遍交代得还不全。agent-skills这类思路解决的正是这个“重复交代”的问题。它适合谁看三类人最该关注。第一类是已经在用 Claude Code 或类似 AI coding agent 做日常开发的人你会立刻感受到技能复用带来的效率差第二类是团队里负责工程规范、CI、脚手架的人你可以把团队规范沉淀成技能让 agent 自动遵守第三类是对 test-driven-development 这类工程实践有执念的人因为技能机制天生适合把 TDD 这种“流程性纪律”固化下来而不是靠人自觉。我先把结论放前面agent-skills不是一个孤立的工具它是一种把“隐性工程经验”显性化、模块化、可被 agent 调用的组织方式。理解了这一层后面无论是 skills CLI 的用法、还是它和 Claude Code 的配合你都能自己推导出来。2. agent-skills 的核心设计思路拆解2.1 为什么是“技能”而不是“更长的 prompt”很多人第一反应是我直接把所有规范写进一个巨大的 system prompt 不就行了我试过结论是不行而且越用越糟。原因有三个。第一上下文是有成本的。你把构建规范、测试规范、代码风格、部署流程全塞进一个 prompt每次对话都要背着这几千 token模型注意力被稀释真正跟当前任务相关的信息反而被淹没。第二规范是会变的。今天改了测试命令明天换了 lint 规则你不可能每次都去改那个巨型 prompt。第三不同任务需要不同技能。写新功能和修 bug 需要的上下文完全不同一刀切必然浪费。agent-skills的设计思路本质上是按需加载 关注点分离。每个技能是一个自包含的单元有自己的名字、描述、触发条件和具体内容。Agent 在面对一个任务时先判断“我需要哪些技能”再把对应的技能内容拉进上下文。这跟人干活是一样的你不会把公司所有 SOP 背下来而是遇到具体问题时去翻对应的那本手册。提示判断一个东西该不该做成技能标准很简单——它是否会被反复使用且内容相对稳定。一次性的临时指令不值得做成技能。2.2 技能单元里到底装什么一个设计良好的技能通常包含这么几块信息我按重要性排名称与描述这是给 agent 做“技能检索”用的。描述要写清楚“什么时候该用我”而不是“我是什么”。比如“当需要为新功能编写测试时使用”就比“测试相关技能”好得多。触发条件什么情况下激活。可以是关键词也可以是任务类型判断。具体指令真正要注入上下文的内容可能是步骤、规范、示例代码。依赖与前置这个技能是否需要其他技能先加载或者需要某些工具就位。验证方式怎么确认技能被正确执行了这一步很多人会漏。我特别想强调描述这一块。因为 agent 选择技能靠的是语义匹配描述写得含糊技能就永远不会被正确触发。这跟给函数起名是一个道理handleData这种名字没人知道该什么时候调。2.3 和 test-driven-development 的天然契合热词里出现了test-driven-development这不是巧合。TDD 是一种强流程纪律先写失败的测试再写实现让它通过最后重构。这套流程人执行起来都会偷懒更别说 agent 了——模型天然倾向于“先把功能写完测试回头补”这恰恰是 TDD 的反面。把 TDD 做成一个技能价值在于流程被固化成了 agent 必须遵循的指令序列。当任务被识别为“实现新功能”时TDD 技能被激活agent 就会按“红-绿-重构”的顺序走而不是自由发挥。我在实际项目里验证过同样的模型加载了 TDD 技能之后产出的代码测试覆盖率明显更稳定因为它不再有“跳过测试”这个选项。这就是技能机制最迷人的地方它把工程纪律从“靠自觉”变成了“靠机制”。3. skills CLI 与 Claude Code 的配合实操3.1 环境准备与安装路径选择先说环境。Claude Code 目前主流的安装方式分几类官方安装脚本、包管理器安装、以及 VS Code 插件形式。不同系统路径不一样我按我实际折腾过的顺序说。macOS 上最省事的是用官方脚本或 Homebrew 类的方式装装完在终端里能直接敲claude就说明成了。Ubuntu 上我建议先确认 Node 环境版本够新很多安装失败其实是 Node 版本太老导致的。Windows 用户如果走 VS Code 插件路线注意插件和 CLI 是两套东西插件负责界面集成底层能力还是靠 CLI。关于“claude code 安装”“claude code 下载”“mac 安装 claude code”“ubuntu 安装 claude code”这些高频搜索我的经验是优先看官方文档链接给出的当前推荐方式因为安装方式迭代很快网上半年前的教程经常已经过时。装完之后第一件事是验证版本claude --version能正常输出就说明基础环境没问题。注意安装过程中如果遇到“当前地区不可用”之类的提示属于账号与服务可用性范畴本文不展开也不建议在这上面花太多精力把注意力放回工程本身。3.2 skills CLI 的基本工作流skills CLI是管理技能的命令行入口核心就几个动作列出、安装、启用、禁用、更新。我把它类比成包管理器只不过管理的是“技能”而不是“依赖包”。典型流程是这样# 查看当前可用的技能 skills list # 安装某个技能 skills install skill-name # 查看已安装技能 skills installed # 启用/禁用 skills enable skill-name skills disable skill-name实际用下来最容易踩的坑是技能装了但没启用然后纳闷为什么 agent 不按技能走。所以每次装完我都会习惯性skills installed确认一遍状态。另一个坑是技能版本和 agent 版本不匹配尤其是 agent 升级之后老技能可能引用了已经改名的命令这时候要么更新技能要么临时禁用。3.3 在 Claude Code 里让技能真正生效装好技能只是第一步关键是让 Claude Code 在合适的时机调用它。这里有几个实操要点。第一技能描述要能被任务语义命中。如果你发现某个技能死活不触发八成是描述写得太抽象。我的做法是把描述改写成“当用户要求 X 时使用”用最直白的任务语言。第二善用显式调用。有些 agent 支持你直接点名技能比如在对话里说“用 TDD 技能来做这个功能”。这比指望它自动匹配可靠得多尤其是在技能刚装好、你还不确定触发逻辑的时候。第三控制同时激活的技能数量。我试过一次性启用七八个技能结果上下文被塞满模型反而抓不住重点。经验值是同一任务下激活 2 到 3 个核心技能比较舒服比如“TDD 代码风格 提交规范”。关于“claude code 如何直接执行终端命令”这个高频问题其实和技能机制是互补的技能告诉 agent该做什么、按什么顺序做而终端执行能力让它真的能跑起来。两者结合agent 才能从“给建议”变成“真干活”。4. 把团队规范沉淀成技能一个完整案例4.1 从零设计一个“新功能开发”技能我拿一个真实场景走一遍。假设我们团队规定任何新功能必须走 TDD测试文件放在tests/下命名用test_模块名.py实现前先跑一次全量测试确认基线是绿的。这个规范如果只写在文档里agent 不会看。做成技能内容大概是这样组织的名称new-feature-tdd描述当需要实现一个新功能或新模块时使用指令正文先运行全量测试确认当前基线通过在tests/下创建test_模块名.py写一个会失败的测试运行该测试确认它确实失败红写最小实现让测试通过绿重构保持测试通过重复直到功能完成你看这套东西没有任何“黑科技”就是把团队纪律翻译成 agent 能执行的步骤。但效果立竿见影因为agent 不再需要猜你的流程。4.2 技能之间的组合与依赖单个技能威力有限组合起来才可怕。我常用的组合是场景激活的技能组合开发新功能new-feature-tdd code-style commit-convention修 bugbug-repro regression-test commit-convention重构refactor-safety test-coverage-check代码审查review-checklist security-scan这里有个设计原则技能要尽量正交避免功能重叠。如果两个技能都在讲代码风格agent 会收到矛盾指令。我踩过这个坑后来把风格规范统一收敛到一个技能里其他技能只引用不重复。依赖关系也要理清。比如regression-test技能可能依赖test-runner技能先就位。这种依赖最好在技能定义里显式声明而不是靠 agent 自己悟。4.3 版本管理与团队共享技能一旦被团队用起来就变成了需要版本管理的资产。我的做法是把技能目录纳入 Git跟代码一起走 PR 流程。改技能要 review因为一个错误的技能指令会污染所有人的 agent 行为。共享方面skills CLI通常支持从本地目录或远程源安装。团队内部可以维护一个私有技能仓库新人入职第一件事就是skills install拉一套团队技能立刻就能按团队规范干活。这比写一份没人看的 onboarding 文档有效得多。提示技能仓库的 README 要写清楚每个技能的适用场景和最近变更否则半年后没人记得某个技能为什么存在。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查动作技能完全不触发未启用skills installed看状态偶尔触发描述语义模糊改写描述为任务语言触发但行为不对技能内容有误检查指令正文多个技能冲突功能重叠合并或拆分技能升级后失效版本不匹配更新技能或回退 agent我的经验是八成问题出在描述。因为触发靠语义匹配描述就是技能的“接口”。接口设计不好实现再对也没用。5.2 上下文被技能撑爆技能装多了上下文会膨胀。解决办法有两个一是按任务动态启用不要全局常开二是精简技能内容把“背景介绍”这类废话删掉只留可执行指令。我见过有人把整篇 wiki 塞进技能结果 agent 每次都要读一遍纯属浪费。5.3 第三方模型接入时的技能兼容性热词里提到用 cc switch 接入 deepseek、qwen、glm 等模型以及“claude code harness 可以不登录用其他模型吗”这类问题。这里的关键点是技能机制本身是模型无关的它注入的是上下文不依赖特定模型。但不同模型对指令的遵循程度不一样同一个技能在 A 模型上执行得很规矩在 B 模型上可能就跳步。我的应对策略是技能指令写得越结构化、越像清单跨模型稳定性越好。用编号步骤、明确的判断条件比大段自然语言描述可靠得多。另外接入第三方模型时先拿一个简单技能做验证确认触发和执行都正常再上复杂技能。5.4 几个我踩过的坑坑一技能里写了绝对路径换台机器就失效。改成相对路径或环境变量。坑二技能依赖某个 CLI 工具但没在技能里说明agent 执行时报错。把依赖写进技能前置条件。坑三技能更新后没通知团队别人还在用老版本行为不一致。用 Git 管理 变更日志解决。坑四把“一次性任务”也做成技能结果技能库越来越臃肿。记住前面说的标准反复使用且内容稳定才值得做成技能。6. 我对 agent-skills 这类机制的真实体会用了一段时间之后我最大的感受是AI coding agent 的上限越来越不取决于模型本身而取决于你给它搭的“工作环境”。模型能力是公共的但你的技能库是私有的、是团队经验的结晶。同样一个 Claude Code装了精心设计的技能和裸奔产出质量差得不是一点半点。另一个体会是技能机制逼着团队把隐性知识显性化。以前很多规范只存在于老员工脑子里现在要写成技能就必须说清楚、写明白。这个过程本身就是一次团队工程能力的梳理。我甚至觉得就算哪天不用 agent 了这套技能文档对新人也是极好的培训材料。最后分享一个小技巧从最小的技能开始。别一上来就设计一套庞大的技能体系先做一个“提交规范”或者“测试命令”这种小技能跑通整个流程感受到效果之后再逐步扩展。技能库是长出来的不是设计出来的。