1. agent-skills 到底在解决什么问题第一次看到agent-skills这个词很多人会以为是某个新出的 AI 模型或者某个大厂的开源框架。实际上它更接近一个能力包的概念——把 AI coding agent 在真实项目里反复要用到的技能做成可复用、可组合、可版本管理的模块。你可以把它理解成给 AI 编程助手准备的工具箱里面装的不是锤子扳手而是怎么读代码库怎么跑测试怎么改配置怎么提交变更这类具体动作的封装。我接触这个概念是从 Claude Code 开始的。Claude Code 本身是一个跑在终端里的 AI 编程代理它能读文件、执行命令、改代码但默认状态下它对你的项目一无所知。你得告诉它项目结构是什么、测试怎么跑、代码风格是什么。每次开新会话都要重复一遍非常烦。agent-skills要解决的就是这个重复劳动的问题——把项目相关的知识和操作流程固化下来让 agent 每次启动就能直接进入状态。关键词里提到的skills CLI、test-driven-development、AI coding agents其实指向同一个方向让 AI 代理的行为变得可预测、可复用、可协作。这不是某个单一工具的功能而是一套工作方式的转变。适合谁来了解如果你已经在用 Claude Code、Cursor、Copilot 这类工具写代码但总觉得每次都要重新教它那这套东西就是给你准备的。如果你还没开始用 AI 编程代理那先理解它的价值再决定要不要投入时间。我自己的判断是agent-skills这类东西的价值不在于技术多复杂而在于它把人机协作的默契变成了可以沉淀的资产。以前这种默契只存在于老员工的脑子里现在可以写成 skill 文件让 AI 和新人都能直接调用。2. 从 Claude Code 的默认行为看 skills 的必要性2.1 默认状态下 agent 的失忆问题Claude Code 启动时它会读取当前目录的文件列表然后等你给指令。你让它修一下登录的 bug它会先问登录代码在哪个文件。你告诉它在src/auth/login.ts它读完文件改完然后你让它跑测试它又问测试命令是什么。这一轮下来你花了大量时间在解释上下文上而不是在解决问题上。这个问题的根源在于agent 的上下文窗口是有限的而项目的隐性知识是无限的。哪些文件重要、哪些命令常用、哪些坑不能踩这些信息不在代码里而在人的经验里。agent-skills的做法是把这些经验写成结构化的文件放在项目里agent 启动时自动加载。这样它就不用每次问你了。我实测下来一个配置良好的 skill 文件能让 agent 的首次响应准确率提升非常明显。以前它可能会改错文件、跑错命令现在它知道这个项目的测试用pnpm test:unit不要用npm test因为 skill 文件里写清楚了。2.2 skills 和普通 prompt 的区别有人会问那我直接在对话里把项目信息告诉它不就行了为什么要单独搞一套 skills区别在于三个层面。第一是持久化对话里的信息会话结束就没了skill 文件一直在。第二是结构化对话里的信息是零散的skill 文件有固定的格式agent 解析起来更可靠。第三是可组合你可以有多个 skill分别负责不同场景agent 根据任务自动选择加载哪个。举个例子你可以有一个testing.md的 skill专门讲这个项目的测试策略一个deployment.md的 skill讲部署流程一个code-style.md的 skill讲代码规范。当 agent 接到修 bug的任务时它会加载 testing 相关的 skill接到发版任务时加载 deployment 相关的 skill。这种按需加载的机制比一股脑把所有信息塞进 prompt 要高效得多。提示skill 文件不是越长越好。我见过有人写了几千行的 skill 文件结果 agent 加载后反而变慢因为上下文被占满了。好的 skill 应该像好的文档一样精准、简洁、只讲关键信息。2.3 为什么现在这个时间点特别重要AI coding agent 正在从玩具变成生产力工具。以前大家用 Copilot 补全代码现在用 Claude Code 直接改整个文件、跑测试、提交 commit。能力越强对上下文的要求就越高。一个只会补全的助手你不需要告诉它项目结构一个能改代码、跑命令的代理你必须告诉它边界在哪里。agent-skills这个概念火起来本质上是因为 agent 的能力已经超过了随便给点上下文就能干活的阶段。它需要更精确的指令、更明确的约束、更结构化的知识。这就像你带一个新员工如果他只是帮你复印文件你不需要给他讲公司战略如果他开始独立负责项目你就必须给他一套完整的工作手册。3. 一个 skill 文件应该包含什么3.1 核心要素拆解我参考了几个开源项目的 skill 写法也自己写了不少总结下来一个高质量的 skill 文件应该包含这几块内容触发条件什么情况下这个 skill 应该被加载。比如当任务涉及测试时或当用户提到部署时。项目背景这个项目是干什么的技术栈是什么目录结构大概什么样。关键命令常用的构建、测试、运行、部署命令以及它们的参数和注意事项。代码规范命名约定、文件组织方式、注释风格等。常见陷阱这个项目里容易踩的坑比如某个配置文件不能手动改、某个命令必须在特定目录下跑。验证方式改完代码后怎么确认没改坏比如跑哪些测试、看哪些日志。这六块内容不是每块都必须有但触发条件、关键命令、验证方式这三块我建议一定要写。没有触发条件agent 不知道什么时候用没有关键命令agent 会瞎猜没有验证方式agent 改完不知道对不对。3.2 用 test-driven-development 作为 skill 的实例关键词里提到了test-driven-development这其实是一个非常适合做成 skill 的场景。TDD 的流程是固定的先写测试跑测试看它失败写实现代码跑测试看它通过重构。这个流程如果让 agent 自己发挥它可能会跳过看测试失败这一步直接写实现。你可以写一个tdd.md的 skill内容大概是这样# TDD Skill ## 触发条件 当任务涉及新增功能或修复 bug 时加载。 ## 流程 1. 先写一个失败的测试测试文件放在 tests/ 目录下命名规则是 *.test.ts。 2. 运行 pnpm test:unit -- 测试文件名确认测试失败且失败原因是功能未实现不是语法错误。 3. 写最小实现代码让测试通过。 4. 再次运行测试确认通过。 5. 运行 pnpm lint 和 pnpm typecheck确认没有引入新问题。 ## 注意事项 - 不要一次写多个测试一个测试对应一个功能点。 - 测试失败信息要仔细看确认是预期失败。 - 实现代码不要过度设计先让测试通过再说。这个 skill 写完之后agent 接到加一个用户注册功能的任务时就会自动按 TDD 流程走。我实测下来它确实会先写测试、跑测试、再写实现而不是直接改业务代码。这个行为的一致性就是 skill 带来的价值。3.3 skill 文件的格式和存放位置不同工具的 skill 格式不太一样。Claude Code 用的是CLAUDE.md文件放在项目根目录或者.claude/目录下。有些工具支持多个 skill 文件按目录组织。skills CLI这类工具则是提供了一套命令行接口让你可以安装、更新、组合 skill。我建议的存放方式是项目根目录放一个CLAUDE.md作为主入口里面写最核心的信息然后在.claude/skills/目录下放具体的 skill 文件按主题命名。这样主入口保持简洁具体细节按需加载。注意skill 文件要纳入版本管理。它是项目知识的一部分应该和代码一起提交、一起 review。我见过有人把 skill 文件放在本地不提交结果换台机器就没了非常可惜。4. 把 skills 接入日常工作流的实操路径4.1 从零开始建第一个 skill如果你还没用过任何 skill我建议从最简单的开始。不要一上来就写一个覆盖全项目的巨型 skill那样很容易写崩。先选一个你每天都要重复告诉 agent 的事情把它写成 skill。比如你每天都要告诉 agent这个项目用 pnpm 不用 npm那就写一个最小的 skill# 项目基础信息 - 包管理器pnpm不要用 npm 或 yarn。 - Node 版本20.x用 nvm use 切换。 - 测试命令pnpm test:unit不要用 pnpm test。 - 代码检查pnpm lint提交前必须跑。就这么几行放在CLAUDE.md里。下次启动 Claude Code它就会知道这些信息不会再问你用什么包管理器。这个小小的改变能省掉每天好几次的重复对话。4.2 逐步扩展从单文件到多 skill当你习惯了单文件 skill 之后可以开始拆分。把测试相关的放一个文件部署相关的放一个文件代码规范放一个文件。拆分的标准是触发条件是否不同。如果两个信息总是在同一个任务里用到那它们可以放一起如果它们分别对应不同类型的任务那就拆开。我自己的项目里CLAUDE.md只保留最基础的信息技术栈、目录结构、核心命令然后.claude/skills/下有testing.md、deployment.md、database.md、api-design.md四个文件。agent 接到不同任务时会加载不同的 skill。这样每个 skill 文件都不长加载速度快信息也精准。4.3 用 skills CLI 管理 skill 的版本和依赖skills CLI这类工具解决的是skill 多了之后怎么管理的问题。当你有十几个 skill 文件分布在不同的项目里手动同步就很痛苦。CLI 工具可以让你把 skill 发布成包在其他项目里安装、更新。我目前的使用方式是把通用的 skill比如 TDD 流程、代码 review 清单发布成内部包各个项目通过 CLI 安装。项目特有的 skill 则放在项目自己的仓库里。这样通用知识可以复用项目知识保持独立。不过要提醒一句不要过度依赖 CLI 工具。skill 的核心价值在于内容不在于管理工具。我见过有人花大量时间折腾 CLI 配置结果 skill 文件本身写得很潦草那就本末倒置了。5. 实测中遇到的坑和应对方式5.1 skill 加载了但 agent 不遵守这是最常见的问题。你明明写了用 pnpm 不用 npmagent 还是跑了npm install。原因通常有三个一是 skill 文件的位置不对agent 根本没加载到二是 skill 文件里的指令不够明确agent 理解成了建议而不是规则三是 skill 文件太长关键信息被淹没了。我的应对方式是第一确认 skill 文件在 agent 会读取的路径下不同工具的路径规则不一样要查文档确认。第二用命令式语气写 skill比如必须用 pnpm而不是建议用 pnpm。第三把最重要的规则放在文件最前面不要藏在中间。5.2 skill 之间的冲突当你有了多个 skill 文件可能会出现冲突。比如testing.md里说测试文件放在tests/目录code-style.md里说所有文件放在src/目录下。agent 加载两个 skill 后不知道该听谁的。解决方式是建立优先级规则。在CLAUDE.md里写清楚当 skill 冲突时以更具体的 skill 为准。或者干脆在写 skill 时就避免重叠每个 skill 只负责一个明确的领域不交叉。5.3 skill 更新后 agent 行为突变有时候你更新了一个 skill 文件agent 的行为突然变了之前能跑通的流程现在跑不通了。这通常是因为新加的规则和旧规则冲突或者新规则太严格把正常操作也拦住了。我的做法是每次更新 skill 后跑一遍回归测试。选几个典型任务让 agent 重新做一遍看结果是否符合预期。如果不符合回滚 skill 改动重新设计。skill 文件也是代码需要测试。提示skill 文件的改动建议单独提交不要和业务代码混在一起。这样出问题时容易定位也容易回滚。5.4 不同模型对 skill 的解析差异关键词里提到了cc switch 接入 deepseek v4, qwen, glm 等模型这其实引出一个实际问题不同模型对 skill 文件的解析能力不一样。Claude 系列模型对结构化文本的理解比较好一些开源模型可能对格式要求更严格。我实测下来用 Markdown 格式写 skill大部分模型都能正确解析。但如果用太复杂的嵌套结构小模型可能会漏读。所以我的建议是skill 文件保持扁平结构少用深层嵌套关键信息用加粗或列表突出。6. 从个人使用到团队协作的演进6.1 个人 skill 和团队 skill 的边界个人用的 skill 可以很随意你自己看得懂就行。但团队用的 skill 必须规范因为每个人对同一句话的理解可能不一样。我建议把 skill 分成两层个人层放自己的偏好比如我喜欢用 vim 快捷键团队层放项目共识比如提交信息必须用 conventional commits。团队层的 skill 应该像代码一样 review。每次改动都要有人审核确认表述清晰、没有歧义。我见过团队因为 skill 文件里一句话写得模糊导致 agent 在不同人机器上行为不一致排查了半天才发现是 skill 的问题。6.2 skill 的版本管理和变更记录团队 skill 必须有版本管理。我推荐的做法是skill 文件放在项目仓库里和代码一起提交。每次改动写清楚变更原因比如新增数据库迁移的 skill因为最近迁移频繁出错。变更记录不用很复杂在文件顶部加一个简单的 changelog 就行# 变更记录 - 2025-01-15新增数据库迁移注意事项。 - 2025-01-10更新测试命令从 npm test 改为 pnpm test:unit。这样新人接手时能快速了解 skill 的演进过程知道哪些规则是踩过坑之后加的。6.3 用 skill 做新人 onboardingskill 文件其实是最好的新人文档。新人入职时让他先读一遍 skill 文件就能了解项目的基本规则和常见陷阱。比口头传授靠谱得多因为口头传授容易遗漏skill 文件是完整的。我现在的做法是新人入职第一天让他用 Claude Code 跑一个简单任务观察 agent 的行为。agent 会按照 skill 文件里的规则操作新人跟着看一遍就大概知道项目怎么跑了。这比让他自己摸索快很多。7. 关于 agent-skills 的几个常见疑问7.1 skill 会不会让 agent 变得死板有人担心skill 写得太细agent 就只会按固定流程走失去灵活性。这个担心有一定道理但可以通过设计来避免。我的做法是skill 里只写必须遵守的规则和必须避免的陷阱不写具体怎么做。具体怎么做留给 agent 自己发挥。比如 TDD skill 里我写必须先写测试但不写测试代码应该长什么样。这样 agent 知道流程但具体实现可以灵活处理。规则和自由的边界是 skill 设计的关键。7.2 skill 和 fine-tuning 的区别有人会问为什么不直接 fine-tune 一个模型让它记住项目知识答案是成本和灵活性。fine-tune 需要大量数据、大量算力而且更新一次很慢。skill 文件改一行就生效成本几乎为零。对于大多数项目来说skill 是更务实的选择。当然如果项目非常大、规则非常稳定fine-tune 也有它的价值。但对中小团队和个人开发者来说skill 的性价比明显更高。7.3 没有 Claude Code 能用 skill 吗可以。skill 的本质是结构化文本任何支持读取项目文件的 AI 编程工具都能用。Cursor 有.cursorrulesCopilot 有.github/copilot-instructions.md形式不同思路一样。你甚至可以把 skill 文件的内容直接粘贴到对话里虽然不如自动加载方便但也能起作用。关键词里提到的claude code harness可以不登录用其他模型吗其实也反映了大家对这个问题的关注。不同工具的接入方式不一样但 skill 的核心逻辑是通用的把项目知识结构化让 agent 能读取。8. 我个人的使用体会用了大半年 skill 之后我最大的感受是它改变的不是 agent 的能力而是我和 agent 的协作方式。以前我把 agent 当成一个需要不断指导的实习生现在更像是一个读过项目文档的新同事。它不需要我每次从头解释我也能把精力放在真正需要判断的地方。另一个体会是写 skill 的过程其实是在梳理自己的项目知识。很多规则我平时是凭直觉遵守的写 skill 的时候才意识到原来我是这么做的。这个过程本身就有价值即使不用 AI把项目规则写清楚也是好事。最后分享一个小技巧skill 文件不要一次写完边用边加。每次发现 agent 犯了一个重复的错误就把对应的规则加进去。这样积累下来的 skill每一条都是真实踩过的坑比一开始就设计一个完美体系要实用得多。