1. 从“agent-skills”说起为什么它值得你花时间第一次看到agent-skills这个标题很多人会以为它只是某个仓库里堆了一堆提示词模板。但真正用过 AI coding agents 的人会明白这个项目解决的是一个非常具体、非常痛的问题如何让 AI 编程助手从“能聊天”变成“能干活”并且干得稳定、可复用、可测试。agent-skills本质上是一套面向 AI coding agents 的技能封装方案。它把常见的开发任务——比如写测试、重构代码、生成文档、执行终端命令、做代码审查——拆解成一个个独立的、可组合的“技能单元”。每个技能单元都包含明确的触发条件、执行步骤、验证方式和回滚策略。你可以把它理解成给 AI 助手准备的一套“标准作业程序”而不是每次都要靠临时提示词去碰运气。这个项目适合三类人第一类是把 Claude Code、Cursor、VS Code 里的 AI 助手当日常生产力工具的人第二类是正在搭建内部 AI 编码工作流的技术团队第三类是想理解“AI coding agents 到底怎么落地”的产品和技术管理者。不管你是刚接触claude code的新手还是已经在用skills CLI做自动化编排的老手这套思路都能帮你少踩很多坑。我最初接触这个方向是因为团队里有人抱怨“AI 写的代码不敢直接合并”。后来我们发现问题不在模型能力而在任务边界和验证机制。agent-skills的核心价值就是给每个任务加上边界和验证。下面我会从设计思路、核心细节、实操流程、常见问题四个层面把这套东西拆开讲清楚。2. 内容整体设计与思路拆解2.1 为什么需要“技能”而不是“提示词”提示词是一次性的技能是可复用的。这是最本质的区别。你可以在 Claude Code 里输入一段很长的提示词让 AI 帮你写一个 React 组件。但下次遇到类似任务你还得重新组织语言而且很难保证两次输出质量一致。agent-skills的做法是把这类任务固化下来输入是什么、输出格式是什么、中间需要检查哪些点、失败后怎么重试全部写清楚。从工程角度看这相当于把“提示工程”升级成了“技能工程”。提示工程关注的是“怎么问”技能工程关注的是“怎么保证结果可靠”。后者才是 AI coding agents 真正进入生产环境的前提。我见过太多团队卡在“AI 能写但不敢用”的阶段缺的就是这层封装。另一个关键设计是技能的可组合性。一个“写测试”的技能可以独立使用也可以被“重构代码”技能调用。这种组合能力让 AI 助手可以处理更复杂的任务链而不是每次只做一件事。比如你先让 AI 用test-driven-development技能生成测试用例再用“实现功能”技能写代码最后用“代码审查”技能检查。整个流程可以自动化也可以人工介入关键节点。2.2 技能目录结构的设计逻辑一个典型的agent-skills项目目录通常长这样agent-skills/ skills/ test-driven-development/ SKILL.md examples/ scripts/ code-review/ SKILL.md checklist.md terminal-execution/ SKILL.md safety-rules.md cli/ skills.js README.md每个技能目录下的SKILL.md是核心文件它定义了技能的元信息、触发条件、执行步骤和验证标准。examples/放的是输入输出示例方便 AI 理解预期结果。scripts/放的是辅助脚本比如格式化输出、运行测试、检查依赖。这种结构的好处是人和 AI 都能读。人看文档快速理解AI 读结构精准执行。我特别想强调SKILL.md的写法。很多人把它写成普通说明文档结果 AI 执行时经常跑偏。正确的做法是用结构化格式比如 YAML front matter 加 Markdown 正文。front matter 里写name、description、trigger、version正文里写步骤和约束。这样skills CLI可以解析元信息AI 可以按步骤执行两边都不耽误。2.3 与 Claude Code、VS Code 的集成思路agent-skills不是要替代 Claude Code 或 VS Code而是增强它们。Claude Code 本身有很强的终端执行能力和文件操作能力但它缺一套标准化的任务模板。agent-skills补的就是这块。你可以把技能目录放在项目根目录下然后在 Claude Code 的配置里指向它。这样每次启动 Claude Code它都能自动加载可用技能。在 VS Code 里思路类似。你可以通过claude code for vs code插件或者自定义任务配置把skills CLI挂到命令面板上。比如按CtrlShiftP输入“Run Skill: Test Driven Development”就能触发对应技能。这种集成方式的好处是不改变原有工作流只是多了一个入口。对于已经习惯 VS Code 的开发者来说学习成本几乎为零。注意不同版本的 Claude Code 对技能目录的加载方式可能不同。建议先查官方文档确认当前版本支持的配置项不要直接照搬旧版配置。3. 核心细节解析与实操要点3.1 SKILL.md 的写法让 AI 一次读懂写SKILL.md最忌讳的是“散文式描述”。比如“请你帮我写一个测试要覆盖边界情况最好用 Jest”——这种写法 AI 每次理解都不一样。正确的写法是结构化、可验证的。下面是一个test-driven-development技能的简化示例--- name: test-driven-development description: 根据功能描述生成测试用例再实现代码使测试通过 trigger: 当用户要求“写测试”或“TDD”时触发 version: 1.0.0 --- ## 步骤 1. 读取用户提供的功能描述文件 feature.md 2. 生成测试文件 *.test.js覆盖正常路径、边界条件、异常输入 3. 运行测试确认全部失败红 4. 生成实现代码使测试通过绿 5. 重构代码保持测试通过 6. 输出测试覆盖率报告 ## 约束 - 测试框架默认使用 Jest除非项目 package.json 指定其他框架 - 每个测试用例必须有明确的断言 - 不允许修改测试用例来迎合实现这种写法的好处是AI 知道每一步做什么也知道什么不能做。trigger字段让skills CLI可以自动匹配用户意图不需要手动指定技能名。version字段方便后续升级和回滚。我实测下来结构化SKILL.md的首次执行成功率比散文式提示词高出很多。尤其是“约束”部分能有效防止 AI 走捷径。比如有些 AI 会为了让测试通过而删掉断言加上“不允许修改测试用例”这条约束后这种情况基本消失。3.2 技能触发机制怎么让 AI 知道该用哪个技能触发机制是agent-skills里最容易被低估的部分。很多人以为只要把技能目录放那里AI 就会自动用。实际上你需要一套匹配逻辑。常见做法有三种第一种是关键词匹配。在SKILL.md的trigger字段里写关键词skills CLI扫描用户输入命中关键词就加载对应技能。这种方式简单直接但容易误触发。比如用户说“帮我看看这个测试”可能只是想问问题不一定想执行完整 TDD 流程。第二种是显式调用。用户在 Claude Code 里输入/skill test-driven-development明确指定技能。这种方式最可靠但需要用户知道技能名。适合团队内部约定好常用技能后使用。第三种是语义匹配。用一个小模型或者嵌入向量把用户输入和技能描述做相似度计算超过阈值就触发。这种方式最智能但实现复杂度也最高。我一般建议中小团队先用关键词加显式调用等技能库稳定后再考虑语义匹配。实操心得在trigger字段里同时写中英文关键词能显著提升匹配率。比如trigger: 写测试, TDD, test driven, 单元测试。中文用户和英文用户都能命中。3.3 终端执行的安全边界agent-skills里最危险也最有价值的能力是终端执行。Claude Code 本身可以执行终端命令但如果没有约束AI 可能执行rm -rf或者修改系统配置。terminal-execution技能的核心就是加安全边界。我的做法是在技能里定义三层规则白名单命令npm test、git status、ls、cat等只读或项目内操作可以直接执行。需确认命令git push、npm publish、docker build等有外部影响的命令执行前必须输出命令内容并等待用户确认。禁止命令rm -rf /、chmod 777、curl | bash等高风险操作直接拒绝执行。这套规则写在safety-rules.md里AI 每次执行终端命令前先读规则。实测下来这能挡住绝大多数误操作。有一次 AI 想执行git reset --hard来“清理工作区”被规则拦下并提示用户确认避免了一次未提交代码的丢失。3.4 与第三方模型的兼容性处理很多人关心claude code harness能不能不登录用其他模型。从技术角度看agent-skills本身是模型无关的它定义的是任务流程和验证标准不绑定具体模型。但实际使用时不同模型对SKILL.md的理解能力差异很大。我试过用同一套技能分别跑 Claude、DeepSeek、Qwen 和 GLM。结果是Claude 对结构化指令的遵循度最高基本能按步骤执行DeepSeek 在代码生成上很强但偶尔会跳过验证步骤Qwen 和 GLM 在中文理解上有优势但终端执行的安全意识需要额外加强。所以如果你要用第三方模型建议做两件事第一在SKILL.md里把约束写得更死减少模型自由发挥的空间第二在skills CLI层面加一层输出校验比如检查测试是否真的运行了、覆盖率报告是否存在。这样即使模型能力有波动整体流程仍然可控。4. 实操过程与核心环节实现4.1 环境准备从零搭建 agent-skills 工作目录假设你已经在 Ubuntu 或 macOS 上装好了 Claude Code并且 VS Code 也能正常使用。接下来我们一步步搭建agent-skills工作目录。第一步创建目录结构mkdir -p agent-skills/skills/test-driven-development mkdir -p agent-skills/skills/code-review mkdir -p agent-skills/skills/terminal-execution mkdir -p agent-skills/cli第二步初始化package.json方便后续用skills CLIcd agent-skills npm init -y第三步安装必要依赖。如果你打算用skills CLI做技能加载和触发匹配可以装一些轻量工具npm install commander chalk inquirercommander用来解析命令行参数chalk用来美化输出inquirer用来做交互确认。这三个加起来体积很小不会拖慢启动速度。第四步在 Claude Code 的配置里指向技能目录。具体配置方式取决于你用的版本。常见做法是在项目根目录的.claude/config.json里加一行{ skillsDir: ./agent-skills/skills }注意如果你用的是claude code for vs code插件配置项可能叫claudeCode.skillsPath。建议先打开插件设置面板确认字段名不要直接复制。4.2 编写第一个技能test-driven-development环境准备好后我们来写第一个完整技能。在agent-skills/skills/test-driven-development/下创建SKILL.md--- name: test-driven-development description: 根据功能描述生成测试用例并实现代码 trigger: 写测试, TDD, test driven, 单元测试, 测试驱动 version: 1.0.0 author: your-name --- ## 输入 - feature.md功能描述文件包含需求、输入输出示例、边界条件 ## 步骤 1. 读取 feature.md提取功能点和边界条件 2. 检查项目测试框架默认 Jest若 package.json 有 vitest 则用 vitest 3. 生成测试文件命名规则为 feature-name.test.js 4. 运行测试命令确认测试失败 5. 生成实现代码放在 src/ 目录下 6. 再次运行测试确认全部通过 7. 运行覆盖率命令输出覆盖率报告 8. 如果覆盖率低于 80%补充测试用例 ## 约束 - 不允许修改测试用例来迎合实现 - 每个测试用例必须有至少一个断言 - 实现代码必须通过 ESLint 检查 - 如果测试运行失败超过 3 次停止并输出错误日志 ## 输出 - 测试文件路径 - 实现文件路径 - 测试运行结果 - 覆盖率报告摘要写完后你可以用skills CLI手动触发一次node cli/skills.js run test-driven-development --input feature.md如果一切正常你会看到 AI 按步骤执行并输出测试结果。第一次跑可能会遇到测试框架识别错误这时候检查package.json里的依赖确保 Jest 或 Vitest 已安装。4.3 技能组合把 TDD 和代码审查串起来单个技能跑通后下一步是组合。假设你想实现“写测试 - 写代码 - 代码审查”的完整流程。可以在cli/skills.js里加一个pipeline命令program .command(pipeline) .argument(skills..., 按顺序执行的技能列表) .option(-i, --input file, 输入文件) .action(async (skills, options) { for (const skill of skills) { console.log(执行技能: ${skill}); await runSkill(skill, options.input); } });然后这样调用node cli/skills.js pipeline test-driven-development code-review --input feature.mdcode-review技能会在 TDD 完成后自动运行检查代码风格、潜在 bug、测试覆盖是否充分。如果发现问题它会输出修改建议并询问是否自动修复。这种组合方式比单次提示词可靠得多因为每个环节都有明确的输入输出和验证标准。我实测下来一个中等复杂度的功能模块用 pipeline 方式比手动提示词节省大约一半时间而且代码质量更稳定。尤其是代码审查环节AI 能发现一些人类容易忽略的边界条件。4.4 在 VS Code 里配置快捷入口如果你不想每次都开终端可以在 VS Code 里配快捷键。打开.vscode/tasks.json加一个任务{ version: 2.0.0, tasks: [ { label: Run TDD Skill, type: shell, command: node cli/skills.js run test-driven-development --input feature.md, problemMatcher: [] } ] }然后在keybindings.json里绑定快捷键{ key: ctrlaltt, command: workbench.action.tasks.runTask, args: Run TDD Skill }这样按CtrlAltT就能触发 TDD 技能。对于习惯键盘操作的开发者来说效率提升很明显。如果你用的是claude code for vs code插件也可以把技能挂到插件的自定义命令里具体方式参考插件文档。实操心得在 VS Code 里跑技能时建议把终端面板固定在底部方便观察 AI 执行过程。如果发现 AI 卡在某一步可以随时中断并手动介入。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最常见的问题。你明明写了trigger关键词但 AI 就是不用。排查顺序如下第一检查skills CLI是否真的加载了技能目录。可以在 CLI 里加一个list命令输出所有已加载技能。如果列表为空说明路径配置错了。第二检查trigger字段的格式。有些 YAML 解析器对中文逗号敏感建议用英文逗号分隔关键词。比如trigger: 写测试, TDD, 单元测试比trigger: 写测试TDD单元测试更可靠。第三检查用户输入是否真的命中了关键词。比如用户说“帮我看看这个测试”如果trigger里只有“写测试”就不会触发。这时候可以加一个更宽泛的关键词比如“测试”。第四如果用的是语义匹配检查相似度阈值是否设得太高。一般 0.75 左右比较合适太高会漏触发太低会误触发。5.2 AI 执行到一半卡住或跑偏AI 执行技能时卡住通常是因为某一步的输入不明确。比如feature.md里没有写边界条件AI 就不知道该怎么生成测试用例。解决办法是在SKILL.md里加一个“前置检查”步骤## 前置检查 - 确认 feature.md 存在且非空 - 确认 feature.md 包含“输入”、“输出”、“边界条件”三个部分 - 如果缺少任何一部分停止执行并提示用户补充这样 AI 在开始前就会检查输入完整性避免跑到一半才发现问题。如果 AI 跑偏了比如跳过了测试直接写实现可以在约束里加一条“必须先生成测试文件并运行失败才能生成实现代码。” 这种硬性约束能有效防止 AI 走捷径。5.3 终端命令执行失败或权限不足终端执行失败通常有两类原因命令本身有问题或者权限不够。排查时先看错误输出如果是command not found检查依赖是否安装如果是permission denied检查文件权限或是否需要sudo。但这里有个原则不要让 AI 自动加 sudo。sudo命令必须由用户手动确认。可以在safety-rules.md里明确写“禁止自动执行任何带 sudo 的命令必须输出命令内容并等待用户手动执行。”另外如果项目在容器里运行终端命令可能需要在容器内执行。这时候可以在SKILL.md里指定执行环境比如executor: docker然后skills CLI会自动把命令转发到容器里。5.4 常见问题速查表问题现象可能原因排查方法解决方式技能不触发路径配置错误运行skills list查看已加载技能检查skillsDir配置技能不触发关键词未命中打印用户输入和 trigger 匹配结果补充中英文关键词AI 跳过步骤约束不够强查看执行日志确认跳过了哪一步在约束里加硬性规则终端命令失败依赖未安装检查错误输出安装缺失依赖终端命令失败权限不足检查文件权限手动执行 sudo 命令测试覆盖率低边界条件未覆盖查看覆盖率报告补充测试用例代码审查误报规则太严格查看审查意见调整审查规则阈值第三方模型不兼容指令遵循度低对比不同模型输出加强约束或换模型5.5 独家避坑技巧第一个坑不要把技能写得太泛。比如“帮我优化代码”这种技能AI 每次理解都不一样。正确做法是拆成“优化性能”、“优化可读性”、“减少重复代码”三个独立技能每个都有明确的输入输出。第二个坑不要忽略版本管理。技能文件也要进 Git每次修改都提交。这样当 AI 执行结果变差时可以回滚到上一个版本对比。我一般会在SKILL.md的version字段里写语义化版本号方便追踪。第三个坑不要一次性加载太多技能。技能库太大时AI 的触发匹配会变慢而且容易误触发。建议按项目类型分组比如前端项目只加载前端相关技能后端项目只加载后端相关技能。skills CLI可以支持按标签过滤比如--tags frontend。第四个坑不要完全信任 AI 的终端执行。即使有白名单也建议在关键操作前加人工确认。我见过 AI 把npm run build理解成npm run build -- --prod结果构建配置不对浪费了很多时间。加一层确认能避免这类问题。6. 技能库的长期维护与扩展思路6.1 技能评审机制技能库不是写完就完了需要定期评审。我建议每两周做一次技能评审检查三件事第一哪些技能最近被触发最多是否需要优化第二哪些技能经常失败是否需要修复第三有没有新的重复任务可以抽象成技能。评审时可以让团队成员提交“技能改进建议”比如“代码审查技能总是漏掉 TypeScript 类型检查”。然后根据建议更新SKILL.md并记录变更日志。这样技能库会越来越贴合团队实际需求。6.2 从个人技能到团队技能个人用的技能和团队用的技能要求不一样。个人技能可以随意一点团队技能必须标准化。我建议团队技能遵循三个原则输入输出明确、验证方式可自动化、失败处理有预案。比如“生成 API 文档”这个技能个人用可能只需要输出 Markdown 就行。团队用就需要输入必须是 OpenAPI 规范文件输出必须是符合团队文档模板的 Markdown验证方式是用markdownlint检查格式失败时自动回滚到上一个版本。这样即使换人执行结果也一致。6.3 与 CI/CD 的集成技能库稳定后可以集成到 CI/CD 流程里。比如在 PR 提交时自动运行code-review技能检查代码质量。如果发现问题自动在 PR 里留言。这样 AI 就不只是个人助手而是团队质量守门员。集成方式很简单在 CI 配置里加一步- name: Run Code Review Skill run: node cli/skills.js run code-review --input ${{ github.event.pull_request.diff_url }}当然CI 环境里可能没有 Claude Code 的交互界面需要用非交互模式。skills CLI可以支持--non-interactive参数遇到需要确认的步骤时自动选择默认选项或者直接失败并输出日志。注意CI 环境里执行终端命令要格外小心建议只允许只读命令和测试命令禁止任何写操作。6.4 后续扩展方向agent-skills的扩展空间很大。往小了说可以加更多技能比如“数据库迁移”、“性能分析”、“安全扫描”。往大了说可以做成技能市场团队成员共享和复用技能。再进一步可以结合skills CLI做技能编排根据任务类型自动选择技能组合。我个人最看好的方向是技能与项目模板结合。比如新建一个 React 项目时自动加载前端相关技能新建一个 Node.js 服务时自动加载后端相关技能。这样开发者不需要手动配置开箱即用。另外随着 AI coding agents 的能力提升技能的定义方式也可能变化。现在主要是结构化 Markdown未来可能变成更动态的配置比如根据代码库状态自动调整步骤。但核心思路不会变给 AI 明确的任务边界和验证标准让它在可控范围内发挥能力。我在实际使用中最大的体会是agent-skills的价值不在于让 AI 更聪明而在于让 AI 更可靠。聪明是一次性的可靠是可复用的。当你把常用任务都封装成技能后你会发现 AI 编程助手真正变成了生产力工具而不是一个偶尔给你惊喜的玩具。