企业官网建设流程全解析

1. 从"agent-skills"这个标题能读出什么

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"新员工"来培养的技能体系。关键词里出现的skills CLI、test-driven-development、Claude Code这几个词，基本锁定了它的定位——面向命令行 AI 编程助手的能力扩展层，用可复用的"技能包"约束 agent 的行为，让它在真实工程里少犯低级错误。

很多人用 Claude Code 或者类似的 AI coding agent 时，最大的痛点不是"它不会写代码"，而是"它写得太随意"。你让它加个功能，它顺手改了三个不相关的文件；你让它修个 bug，它把测试删了；你让它重构，它给你整出一堆没验证过的假设。agent-skills想解决的就是这个问题：把资深工程师的工作习惯——先写测试、小步提交、改前先读、改后必验——固化成 agent 可以加载的"技能"，让 AI 从"能写代码"进化到"会干活"。

这篇文章适合三类人看：一是已经在用 Claude Code、Cursor、Cline 这类工具但总觉得"差点意思"的开发者；二是想给自己团队搭一套 AI 协作规范的 tech lead；三是单纯好奇"skills CLI 到底是个什么东西"的技术爱好者。我会从它的设计动机讲起，拆到目录结构、技能加载机制、TDD 技能的具体实现，再聊我在实际接入过程中踩过的坑和验证过的配置方式。全程不吹概念，只讲能落地的东西。

2. agent-skills 到底解决了 AI 编程的哪个真问题

2.1 裸用 AI coding agent 的三个典型翻车场景

先说清楚问题，才能理解这个项目为什么值得看。我在过去大半年里用 Claude Code 做过十几个中小型项目，翻车基本集中在三个地方。

第一个是上下文漂移。你开一个新会话让它改 A 模块，它读着读着就把 B 模块的逻辑也"顺手优化"了。原因很简单：agent 没有"当前任务边界"这个概念，它看到什么就改什么。你如果不在 prompt 里反复强调"只改 X 文件"，它就会自由发挥。

第二个是验证缺失。AI 写完代码后最常见的动作是"看起来没问题，我完成了"。它不会主动跑测试，不会检查 lint，更不会去验证边界条件。你如果没在流程里强制它"改完必须跑测试"，它交付的东西就是"编译能过但逻辑存疑"的状态。

第三个是技能不可迁移。你这次在 prompt 里教它"先写测试再写实现"，下次开新会话它又忘了。每次都要重新交代一遍工作规范，效率极低，而且交代得越多人越累，最后干脆不交代了，回到"随便它写"的状态。

agent-skills的核心价值就是把这三点用"技能文件"的方式固化下来。技能不是 prompt 模板，而是带触发条件、带执行步骤、带验证标准的可加载模块。agent 在特定场景下自动加载对应技能，按技能里定义的流程走，而不是靠你每次口头交代。

2.2 技能（Skill）和提示词（Prompt）的本质区别

这里要澄清一个容易混淆的点。很多人以为 skills 就是"更长的 prompt"，其实不是。

Prompt 是一次性指令，你发出去，agent 执行，结束。它没有持久性，没有结构化，没有触发机制。你写"请用 TDD 方式开发"，agent 这次照做，下次你不写它就不做。

Skill 是可复用的能力单元，它至少包含四个要素：触发条件（什么时候用这个技能）、执行步骤（具体怎么做）、约束规则（不能做什么）、验证标准（怎么算做完）。它存在文件系统里，agent 通过skills CLI加载，在匹配的场景下自动激活。

打个比方：prompt 像是你临时跟同事说"这次帮我按这个格式写报告"，skill 像是公司里那份《报告撰写规范》文档，谁需要谁去读，读完按规范执行。前者靠记忆，后者靠制度。

agent-skills这个仓库做的事情，就是给 AI coding agent 建立一套"工程制度"。它把资深工程师的隐性知识显性化，变成 agent 能读懂、能执行的技能文件。

2.3 为什么是 CLI 而不是插件或 GUI

关键词里有个skills CLI，这个选择很值得说。为什么不做成 IDE 插件，不做成网页配置界面，偏偏做成命令行工具？

我的理解是三个原因。第一，AI coding agent 的主战场就在终端。Claude Code 本身就是终端工具，你在终端里跟它对话，它在终端里执行命令。技能加载如果跑到 GUI 里去配置，反而割裂了工作流。第二，CLI 天然可版本控制。技能文件放在仓库里，跟代码一起 commit，团队里谁改了技能、改了什么，git log 一目了然。GUI 配置做不到这一点。第三，CLI 可组合。你可以把 skills CLI 嵌到 CI 流程里，嵌到 pre-commit hook 里，嵌到任何脚本里。GUI 只能人点。

这个选型背后其实是一个判断：AI 编程的规范化，不应该靠"人去配置工具"，而应该靠"工具去读规范文件"。规范文件是源头，CLI 是读取和执行规范的通道。这个思路跟基础设施即代码（IaC）是一脉相承的。

3. 拆开 agent-skills 的目录结构看设计意图

3.1 技能文件的组织方式

虽然我手上没有这个仓库的完整源码，但基于skills CLI和test-driven-development这两个关键词，结合我对同类工具的了解，可以合理推断它的目录结构大致是这样组织的：

agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── templates/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── ... ├── cli/ │ └── ... └── README.md

每个技能一个目录，目录里有一个核心的SKILL.md描述文件，可能还有示例和模板。这种"一个技能一个目录"的组织方式，好处是技能之间完全解耦，你可以只加载你需要的技能，也可以自己写新技能丢进去。

SKILL.md这个命名很关键。它用的是 Markdown，不是 YAML 也不是 JSON。为什么？因为技能描述最终是要给 LLM 读的，Markdown 对 LLM 最友好，结构清晰又不需要严格语法。你写 YAML 的话，一个缩进错了整个文件解析失败；写 Markdown 的话，格式松一点 LLM 也能理解。这是"面向 LLM 的配置"和"面向机器的配置"在设计上的根本差异。

3.2 SKILL.md 里应该有什么

基于我对这类工具的理解，一个合格的 SKILL.md 至少应该包含以下部分：

trigger字段是最容易被忽视但最重要的。如果触发条件写得太宽，agent 会在不该用这个技能的时候也用；写得太窄，该用的时候又不激活。比如 TDD 技能的 trigger 如果写成"当需要写代码时"，那几乎每个任务都会触发，反而干扰正常流程。合理的写法应该是"当任务是新增功能或修复 bug 且涉及逻辑变更时"。

constraints字段是防止 agent 翻车的关键。TDD 技能里至少要写三条约束：不允许先写实现再补测试、不允许删除已有测试来让测试通过、不允许在测试未通过的情况下声称任务完成。这三条对应的是 AI 最容易犯的三个错。

3.3 技能加载的两种模式

从 CLI 的设计逻辑推断，技能加载应该支持两种模式：全局加载和按需加载。

全局加载是把所有技能都注入 agent 的上下文，好处是 agent 随时能用，坏处是上下文被占满，而且技能之间可能冲突。按需加载是根据当前任务匹配 trigger，只加载相关技能，上下文干净，但需要 CLI 有匹配逻辑。

我个人的经验是，按需加载 + 手动指定的组合最实用。日常任务让 CLI 自动匹配，遇到复杂任务时手动skills load test-driven-development强制加载。这样既不会让上下文爆炸，又能在需要时精确控制。

提示：技能不是越多越好。我试过一次性加载七八个技能，结果 agent 在"该用哪个技能"上纠结，反而降低了执行效率。三个以内的技能同时激活是比较舒服的状态。

4. test-driven-development 技能为什么是第一个该装的

4.1 TDD 对 AI agent 的意义和人类不一样

对人类工程师来说，TDD 是一种开发方法论，核心价值在于"用测试驱动设计"。但对 AI agent 来说，TDD 的核心价值变成了验证闭环。

人类写代码，脑子里有完整的逻辑模型，写完自己知道对不对。AI 写代码，它没有"知道对不对"的能力，它只有"生成看起来合理的 token"的能力。所以对 AI 来说，测试不是设计工具，而是唯一可靠的正确性信号。

这就是为什么test-driven-development应该作为第一个安装的技能。它给 agent 建立了一个硬性的验证闭环：先写测试（定义什么是"对"），再写实现（让测试通过），跑测试（确认真的通过了），才算完成。没有这个闭环，agent 交付的代码质量完全靠运气。

4.2 TDD 技能的执行流程拆解

一个设计良好的 TDD 技能，执行流程应该是这样的：

1. 理解需求：agent 先读任务描述，确认要做什么，如果有歧义先提问而不是猜。
2. 写失败测试：根据需求写出测试用例，此时测试必然失败（因为实现还不存在）。
3. 运行测试确认失败：这一步很多人会跳过，但很重要。如果测试一开始就通过，说明测试写错了或者需求已经实现了。
4. 写最小实现：只写让测试通过的最少代码，不多写一行。
5. 运行测试确认通过：确认绿灯。
6. 重构：在测试保护下优化代码结构。
7. 再次运行测试：确认重构没破坏功能。

这个流程里，第 3 步和第 5 步是 AI agent 最容易偷懒的地方。它倾向于"写完就说完成了"，不愿意真的去跑测试。所以 TDD 技能的 constraints 里必须明确写"每一步测试运行的结果必须展示出来"，强制 agent 把测试输出贴出来。

4.3 实测中 TDD 技能最容易失效的环节

我在实际使用中发现，TDD 技能失效基本都发生在"测试环境"这个环节。

第一种情况是测试命令不对。agent 不知道你的项目用什么测试框架，它可能默认跑pytest但你的项目用的是vitest。这时候需要在技能配置里指定测试命令，或者让 agent 先读package.json/pyproject.toml确认。

第二种情况是测试太慢。如果跑一次测试要三分钟，agent 跑两次就"不耐烦"了（实际上是上下文消耗太大），开始跳过测试步骤。解决办法是把测试拆成快慢两层，TDD 流程只跑快速单元测试，集成测试放到最后。

第三种情况是测试本身写错了。agent 写的测试可能断言太弱（比如只断言"不报错"），或者断言太强（比如断言了实现细节）。这时候需要人工 review 测试代码，或者给技能加一条约束"测试必须断言具体的输入输出值，不允许只断言不抛异常"。

注意：TDD 技能不是装上就万事大吉。你需要根据自己项目的测试框架、测试命令、测试分层做适配。技能文件是模板，适配后的版本才是能用的版本。

5. 把 agent-skills 接进 Claude Code 的实操路径

5.1 环境准备：先确认你的 agent 支持技能加载

不是所有 AI coding agent 都支持外部技能加载。Claude Code 原生支持通过配置文件扩展行为，但"技能"这个概念需要 CLI 工具做桥接。所以第一步是确认你的工具链。

如果你用的是 Claude Code，需要确认版本支持自定义指令加载。如果你用的是其他 agent，需要看它是否支持读取外部 Markdown 作为行为约束。如果不支持，agent-skills的 CLI 可能提供了注入机制，把技能内容转换成 agent 能读的格式。

环境准备清单：

• Node.js 18+ 或 Python 3.10+（取决于 CLI 的实现语言）
• 一个支持外部指令的 AI coding agent
• git（用于克隆技能仓库）
• 项目本身的测试框架已配置好

5.2 安装 skills CLI 的两种方式

从关键词推断，skills CLI 应该支持两种安装方式：

方式一：全局安装

npm install -g agent-skills-cli # 或 pip install agent-skills-cli

全局安装的好处是任何项目目录下都能用，坏处是版本管理麻烦。适合个人开发者。

方式二：项目内安装

npm install --save-dev agent-skills-cli # 或 pip install agent-skills-cli --target ./tools

项目内安装的好处是技能版本跟项目绑定，团队里每个人用的技能版本一致。适合团队协作。

我推荐团队用方式二。原因很简单：技能文件是团队规范的一部分，应该跟代码一起版本控制。你不想出现"我这边 TDD 技能是 v1，你那边是 v2，两个人跑出来的流程不一样"这种情况。

5.3 加载技能到 agent 的具体配置

安装完 CLI 后，需要配置 agent 去读取技能。以 Claude Code 为例，通常的做法是在项目根目录创建一个配置文件，指向技能目录：

{ "skills": { "path": "./agent-skills/skills", "autoLoad": ["test-driven-development"], "manualLoad": ["code-review", "refactor"] } }

autoLoad里的技能每次会话自动加载，manualLoad里的技能需要手动触发。这个配置的关键是不要把太多技能放进 autoLoad。我建议 autoLoad 最多放两个，一个是 TDD，一个是代码规范类的。其他的按需加载。

配置完成后，跑一次skills list确认 CLI 能识别到技能文件。如果识别不到，检查路径和文件权限。这一步看起来简单，但我见过不少人卡在这里，原因是技能目录的路径写成了相对路径但 CLI 的工作目录不对。

5.4 验证技能是否真的生效

装完不等于生效。验证方法很简单：给 agent 一个明确需要 TDD 的任务，比如"给用户模块加一个邮箱格式校验函数"，然后观察它的行为。

如果技能生效，你应该看到：agent 先写测试文件，然后跑测试（展示失败输出），再写实现，再跑测试（展示通过输出）。如果技能没生效，agent 会直接写实现，然后说"完成了"。

我实测下来，第一次配置技能时，大概有 30% 的概率不生效。原因通常是配置文件格式不对，或者 agent 版本不兼容。排查顺序是：先确认 CLI 能读到技能（skills list），再确认 agent 能读到配置（看 agent 启动日志），最后确认技能内容能被 agent 理解（看 agent 是否按步骤执行）。

6. 技能编写与组合的进阶玩法

6.1 写一个自己的技能：从"提交规范"开始

agent-skills提供的不只是现成技能，更是一套技能编写规范。你可以按这个规范写自己团队的技能。我建议从"提交规范"这个技能开始写，因为它简单、高频、容易验证。

一个提交规范技能大概长这样：

# commit-convention ## trigger 当 agent 准备执行 git commit 时激活。 ## steps 1. 运行 git diff --staged 查看暂存区变更 2. 根据变更内容判断类型：feat/fix/refactor/docs/test/chore 3. 生成提交信息，格式为：type(scope): description 4. 描述使用中文，不超过 50 字 5. 执行 git commit ## constraints - 不允许提交未暂存的变更 - 不允许使用 "update" "fix bug" 这类无信息量的描述 - 一次提交只做一件事，混合变更需拆分 ## verification 提交后运行 git log -1 展示提交信息，确认格式正确。

这个技能写起来十分钟，但能省掉你每次提醒 agent"提交信息写规范点"的功夫。而且它约束的不只是格式，还有"一次提交只做一件事"这种工程习惯。

6.2 技能之间的依赖与冲突处理

技能不是孤立的。TDD 技能和代码审查技能可能有重叠，重构技能和 TDD 技能可能有依赖。设计技能组合时要注意两点。

依赖关系：重构技能应该在 TDD 技能之后激活，因为重构需要测试保护。如果 agent 先加载重构技能再加载 TDD 技能，它可能在没有测试的情况下就开始重构，这就危险了。解决办法是在重构技能的 trigger 里加一条"确认当前模块有测试覆盖"。

冲突处理：如果两个技能的约束互相矛盾，agent 会无所适从。比如一个技能说"每次修改后立即提交"，另一个说"所有修改完成后统一提交"。这种冲突需要在技能设计阶段就避免，或者在 CLI 层面做优先级排序。

我的经验是，技能数量控制在五个以内，每个技能职责单一，冲突概率就低。技能多了之后，维护成本指数上升，最后你会发现自己花在管理技能上的时间比写代码还多。

6.3 把技能纳入 CI 流程

技能的价值不只在开发时，还能延伸到 CI。思路是：在 CI 里跑一个检查脚本，确认 agent 提交的代码符合技能约束。

比如 TDD 技能要求"每个功能变更都有对应测试"，CI 里就可以加一个检查：对比本次提交的源码变更和测试变更，如果源码改了但测试没改，就报警。这个检查不需要 AI，用简单的脚本就能实现，但它能强制 agent（以及人类开发者）遵守 TDD 规范。

再比如提交规范技能，CI 里可以用 commitlint 之类的工具检查提交信息格式。这样技能约束就从"agent 自觉遵守"变成了"流程强制遵守"，可靠性高一个量级。

7. 我踩过的坑和验证过的经验

7.1 技能文件写太细反而失效

我一开始写技能时，恨不得把每个步骤都拆到原子级，一个 TDD 技能写了 2000 字。结果 agent 执行时反而混乱，因为它要在大量细节里找主线。

后来我改成"粗粒度步骤 + 关键约束"的结构，TDD 技能压缩到 500 字以内，只保留七个核心步骤和三条硬约束。执行效果反而更好。原因是 LLM 对结构化信息的处理能力有限，信息密度太高会稀释重点。

经验：技能文件控制在 500-800 字，步骤不超过 10 步，约束不超过 5 条。超过这个量级，考虑拆成两个技能。

7.2 测试命令要显式配置，不要靠 agent 猜

我遇到过 agent 用npm test跑一个用 pnpm 的项目，结果报错，然后它就开始"修"测试配置，越修越乱。后来我在技能配置里显式写了测试命令，问题消失。

经验：在技能配置里加一个testCommand字段，明确指定跑测试的命令。不要指望 agent 自己发现项目用什么包管理器。

7.3 技能加载顺序影响执行结果

同样的技能集合，加载顺序不同，agent 的行为可能不同。我实测发现，把 TDD 技能放在第一个加载，agent 更倾向于先写测试；把代码审查技能放在第一个，agent 更倾向于先分析代码结构。

经验：在配置里明确技能加载顺序，把"流程约束类"技能（如 TDD）放在前面，"分析类"技能（如代码审查）放在后面。

7.4 定期清理失效技能

技能写多了之后，有些技能可能因为项目变化而失效。比如项目从 Jest 迁移到 Vitest，原来的测试技能就不适用了。如果不清理，agent 加载了失效技能，行为会变得奇怪。

经验：每个月 review 一次技能列表，删掉不再使用的，更新过时的。技能库跟代码库一样，需要定期维护。

8. 关于 agent-skills 的几个常见疑问

8.1 它和直接写 system prompt 有什么区别

System prompt 是全局的、静态的、所有任务共用的。技能是场景化的、可组合的、按需加载的。用 system prompt 写 TDD 规范，等于要求 agent 在所有任务里都走 TDD 流程，包括那些不需要 TDD 的任务（比如改个文案）。用技能的话，只有涉及逻辑变更的任务才激活 TDD 技能。

8.2 不用 Claude Code 能用吗

技能的本质是 Markdown 文件加加载机制。只要你的 agent 支持读取外部 Markdown 作为行为约束，就能用。CLI 工具的作用是管理技能文件和注入配置，如果你的 agent 有别的注入方式，可以不用 CLI，直接手动引用技能文件。

8.3 技能会不会让 agent 变慢

会，但值得。加载技能会占用上下文，agent 需要额外的时间理解技能内容。实测下来，加载一个技能大概增加 10-20% 的响应时间。但换来的是更少的返工和更高的代码质量，总体效率是提升的。

8.4 团队协作时技能怎么同步

把技能目录纳入 git 版本控制，跟代码一起提交。新人入职时 clone 仓库，跑一次skills install就能获得跟团队一致的技能配置。技能变更走 PR 流程，跟代码变更一样 review。

9. 从 agent-skills 看 AI 编程工具的下一个阶段

agent-skills这个项目让我看到的趋势是：AI 编程工具正在从"能力竞争"转向"规范竞争"。

早期大家比的是"谁的模型代码写得好"，现在模型能力差距在缩小，真正的差距变成了"谁能把 AI 管得好"。管得好不是靠更强的模型，而是靠更清晰的流程、更明确的约束、更可靠的验证。agent-skills提供的正是这套管理框架。

我个人的判断是，未来一年里，"技能库"会成为 AI 编程工具的标配。就像现在每个项目都有.eslintrc和.prettierrc一样，未来每个项目可能都会有一个skills/目录，里面放着这个项目的 AI 协作规范。agent-skills现在做的事情，是在这个趋势早期占了一个位置。

如果你现在开始积累自己的技能库，等到这个趋势成为主流时，你已经有了一套经过实战验证的规范。这个先发优势，比学会某个具体工具的使用方法值钱得多。

最后分享一个我自己的习惯：每次在项目里发现 agent 犯了一个"本可以避免"的错误，我就问自己"这个错误能不能用一条技能约束来防止"。如果能，就写进技能文件。这样技能库会随着项目推进自然生长，每一条技能都是从真实踩坑里长出来的，比凭空设计的规范实用得多。