企业官网建设流程全解析

1. 从 agent-skills 说起：为什么它值得每个 AI 编码玩家认真研究

第一次看到agent-skills这个项目名的时候，我下意识以为又是一个把 prompt 模板打包成 JSON 的小仓库。真正翻完它的结构、跑通它的 CLI、把它接到自己的编码工作流里之后，我才意识到这东西解决的是一个非常具体、也非常痛的问题：AI coding agents 的“能力”到底该怎么组织、复用和分发。

我们现在的处境其实挺尴尬的。Claude Code、各类 AI coding agents 已经能读写文件、跑终端命令、做代码审查，但每个人手里的 agent 能力都是散装的——有人把规则写在CLAUDE.md里，有人塞进自定义 slash command，有人干脆每次对话手动贴一大段提示词。换一个项目、换一台机器、换一个同事，这套东西就全部失效。agent-skills想做的事情，就是把这些零散的“技能”抽象成一种可安装、可组合、可版本管理的单元，再用一个skillsCLI 把它们分发出去。

这篇文章适合三类人看：第一类是把 Claude Code 当日常主力工具、想让 agent 更听话的开发者；第二类是正在搭自己 AI 编码工作流、需要一套能力管理方案的技术负责人；第三类是对 test-driven-development 这类工程实践怎么和 agent 结合感兴趣的人。我会从设计思路、核心机制、实操落地、踩坑排查四个层面把它讲透，尽量做到你看完就能照着搭一套自己的 skills 体系。

需要先说明一点：agent-skills这类项目迭代很快，具体命令和目录结构可能随版本变化，我下面写的是基于常见实践的合理还原，核心思路是稳定的，细节你以自己拉到的版本为准。

2. agent-skills 的整体设计与思路拆解

2.1 它到底在解决什么问题

要理解agent-skills，得先理解 AI coding agents 的一个根本矛盾：agent 的通用能力和项目的具体规范之间，存在一条鸿沟。

Claude Code 这类工具本身很聪明，但它不知道你们团队的代码风格、不知道你们的测试框架是 Jest 还是 Vitest、不知道提交信息要不要带 issue 编号、不知道数据库迁移必须走某个脚本。这些“项目知识”如果每次都靠对话临时灌输，成本极高且不稳定。

传统的解法有三种，各有各的毛病：

• 写进全局配置文件：比如把规则塞进CLAUDE.md。问题是文件会越来越臃肿，几十条规则堆在一起，agent 注意力被稀释，而且没法按需加载。
• 做成 slash command：每个命令一个文件，调用时手动触发。问题是命令之间无法组合，也没法声明依赖关系。
• 每次对话手动贴提示词：最灵活也最不可靠，纯靠人肉记忆，团队协作基本没法用。

agent-skills的思路是把“技能”变成一等公民。一个 skill 就是一个自包含的单元，里面封装了某类任务的知识、步骤、甚至可执行的脚本。它有自己的元数据（叫什么、什么时候用、依赖什么），可以被 CLI 安装到项目里，也可以被 agent 在合适的时机自动加载。

打个比方：全局配置像是一本厚厚的员工手册，agent 每次都要从头翻；slash command 像是一个个独立的小工具，用哪个拿哪个；而 skills 更像是标准化的工具箱——每个箱子上贴着标签说明用途，需要拧螺丝就打开拧螺丝那箱，需要测电压就打开测电压那箱，箱子之间还能嵌套组合。

2.2 为什么是 CLI 而不是插件市场

agent-skills选择用skillsCLI 作为分发入口，这个决策我觉得很关键，值得展开说说。

插件市场模式（比如某些 IDE 的扩展商店）的好处是可视化、一键安装，但坏处也很明显：它把技能和某个特定平台绑死了。你在 A 工具的商店里装的技能，换到 B 工具就用不了。而 AI coding agents 这个领域现在正是群雄逐鹿的阶段，今天用 Claude Code，明天可能试试别的，把能力锁死在单一平台上风险太大。

CLI 模式则天然是平台无关的。skills命令做的事情本质上就是：从某个源拉取 skill 定义，写到你项目的约定目录里，然后让 agent 去读这个目录。至于 agent 是 Claude Code 还是别的什么，只要它能读文件、能执行命令，就能消费这些 skills。这种“能力与载体解耦”的设计，是它能跨工具复用的根本原因。

另外 CLI 还有个隐性好处：可脚本化、可 CI 化。你可以在项目初始化脚本里加一行skills install xxx，新同事 clone 下来跑一遍就拥有了全套能力，不用手动配置任何东西。这一点在团队协作场景下价值巨大。

2.3 目录结构背后的设计哲学

一个典型的agent-skills项目结构大概长这样（基于常见实践还原）：

skills/ test-driven-development/ SKILL.md scripts/ run-tests.sh references/ testing-patterns.md code-review/ SKILL.md ...

这里有几个设计点值得琢磨。

每个 skill 一个目录，目录名就是 skill 标识符。这看起来平平无奇，但它保证了 skill 的自包含性——删掉一个目录就等于卸载一个技能，不会留下任何残留。对比一下那些把配置散落在多个文件里的方案，这种设计在维护性上高下立判。

核心是SKILL.md。这个文件既是给人看的文档，也是给 agent 看的指令。它通常包含 frontmatter（元数据，比如 name、description、何时触发）和正文（具体的步骤、规则、示例）。agent 读取时先看元数据判断“这个技能跟当前任务相关吗”，相关才加载正文，这就是所谓的渐进式披露——避免一次性把所有技能内容灌进上下文。

scripts/放可执行脚本。这是我觉得最妙的地方。很多技能不是纯知识，而是“知识 + 动作”。比如 test-driven-development 这个技能，它不只是告诉 agent“要先写测试”，还提供一个run-tests.sh让 agent 能真的把测试跑起来看结果。知识和执行闭环了，agent 才不是纸上谈兵。

references/放参考资料。这些是“按需查阅”的内容，比如详细的测试模式清单、API 用法速查。agent 平时不加载，需要时才去读，进一步节省上下文。

2.4 和 test-driven-development 的天然契合

热搜词里出现了test-driven-development，这不是偶然。TDD 几乎是 skills 体系最理想的落地场景，原因有三。

第一，TDD 有明确的、可判定的流程：先写失败的测试，再写让测试通过的最小实现，最后重构。这种流程化的东西特别适合封装成 skill，因为它不需要 agent 发挥创造力，只需要它按部就班执行。

第二，TDD 需要执行反馈。光靠 agent 自己“觉得”测试通过了不算数，必须真的跑一遍。而 skills 里的scripts/正好提供了这个执行能力，agent 可以调用脚本拿到真实的测试结果，形成“写测试→跑测试→看结果→改代码”的闭环。

第三，TDD 的规则容易被 agent 忽略。你如果只在对话里说一句“请用 TDD”，agent 大概率会偷懒直接写实现。但把它做成一个显式的 skill，在元数据里声明“当用户要求实现新功能时触发”，agent 就有了明确的指令来源，遵守率会高很多。

我实测下来，把 TDD 封装成 skill 之后，agent 主动先写测试的比例从“看心情”变成了“基本稳定”，这个提升是很实在的。

3. 核心细节解析与实操要点

3.1 SKILL.md 的元数据怎么写才有效

SKILL.md的 frontmatter 是整个技能能否被正确触发的关键。写得太宽泛，agent 会在不相关的任务上乱加载；写得太窄，该触发的时候又触发不了。我踩过的坑基本都集中在这里。

一个比较稳妥的元数据写法是这样的：

--- name: test-driven-development description: 当需要实现新功能、修复 bug 或重构代码时使用。强制先写测试再写实现，确保每一步都有测试覆盖。 ---

这里description的写法有讲究。它不应该只描述“这个技能是什么”，而应该描述“什么时候该用它”。我见过很多人写成description: 测试驱动开发技能，这种写法对 agent 来说几乎没有触发信号，因为它没有告诉 agent 在什么场景下该激活。

更好的做法是把触发条件写进去，用“当……时使用”这种句式。agent 在判断是否加载某个 skill 时，本质上是拿当前任务和 description 做语义匹配，触发条件写得越具体，匹配越准。

注意：description 里不要堆砌太多关键词试图“广撒网”，这会导致误触发。宁可精准一点，需要覆盖多个场景就拆成多个 skill。

3.2 渐进式披露：别把上下文当垃圾桶

这是 skills 体系里最容易被忽视、但影响最大的机制。

AI coding agents 的上下文窗口是有限资源。如果你把所有技能的完整内容都塞进去，agent 的注意力会被严重稀释，真正重要的信息反而被淹没。agent-skills用渐进式披露来解决这个问题，分三层：

这个设计的好处是，你可以装几十个 skill，但平时只占用第一层的少量上下文。只有当某个任务真的和某个 skill 相关时，它的正文才会被加载进来。

实操建议：SKILL.md 正文控制在 500 行以内，超出的内容拆到references/里。正文只放核心流程和关键规则，细节、示例、边界情况都放参考资料。我见过有人把整个团队的编码规范几千行全塞进一个 SKILL.md，结果就是 agent 每次加载都吃掉大量上下文，还经常抓不住重点。

3.3 scripts 目录：让 agent 从“会说”到“会做”

scripts/是 skills 区别于普通提示词模板的分水岭。它让 agent 能真正执行动作，而不只是生成文本。

以 TDD skill 为例，scripts/run-tests.sh大概长这样：

#!/usr/bin/env bash set -euo pipefail # 自动探测测试框架并运行 if [ -f "package.json" ]; then if grep -q '"vitest"' package.json; then npx vitest run --reporter=verbose elif grep -q '"jest"' package.json; then npx jest --verbose else npm test fi elif [ -f "pytest.ini" ] || [ -f "pyproject.toml" ]; then python -m pytest -v else echo "未识别的测试框架，请手动配置" >&2 exit 1 fi

这个脚本的价值在于：agent 不需要知道项目用的是哪个测试框架，它只需要调用run-tests.sh，脚本自己会探测。这就把“环境适配”的复杂度从 agent 转移到了脚本里，agent 的负担更轻，出错概率更低。

写 scripts 有几个要点：

• 必须幂等：脚本可能被反复调用，不能有副作用累积。
• 输出要结构化：agent 要解析脚本输出，所以尽量用清晰的格式（比如测试结果用PASS/FAIL前缀），别输出一堆花里胡哨的进度条。
• 失败要明确：用非零退出码表示失败，agent 才能判断“这一步没成功”。
• 加超时保护：测试可能卡死，脚本里最好有timeout兜底，避免 agent 无限等待。

提示：脚本里不要硬编码绝对路径，用相对于 skill 目录的路径或者环境变量，否则换台机器就废了。

3.4 技能的粒度怎么把握

这是设计 skills 时最纠结的问题：一个 skill 应该多大？

我的经验是按“任务边界”切，而不是按“知识领域”切。举个例子，“前端开发”是个知识领域，太大了，做成一个 skill 会变成一锅粥。而“给 React 组件写单元测试”是个任务边界，清晰、可执行、有明确输入输出，适合做成一个 skill。

判断粒度是否合适，可以问自己三个问题：

1. 这个 skill 能用一句话说清“什么时候用它”吗？
2. 它的执行步骤能列成 5 到 10 步吗？
3. 它需要依赖其他 skill 吗？如果需要，依赖关系清晰吗？

如果第一个问题答不上来，说明太宽泛；如果第二个问题步骤超过 15 步，说明太细，应该合并或拆分；如果第三个问题答案是“依赖一大堆”，说明耦合太重，需要重新划分边界。

我个人的习惯是让每个 skill 对应一个“可独立验证的产出”。比如 TDD skill 的产出是“一组通过的测试 + 实现代码”，code-review skill 的产出是“一份审查报告”。有明确产出，skill 的边界就自然清晰了。

4. 实操过程与核心环节实现

4.1 环境准备与 CLI 安装

假设你已经有了一个用 Claude Code 或类似 agent 的项目，接下来要接入 skills 体系。第一步是拿到skillsCLI。

基于常见实践，安装方式通常是通过包管理器：

# 以 npm 生态为例（具体以项目文档为准） npm install -g @agent-skills/cli # 验证安装 skills --version

如果你不想全局安装，也可以用npx临时调用：

npx @agent-skills/cli --help

安装完之后，进入你的项目根目录，初始化 skills 配置：

cd your-project skills init

这个命令一般会做几件事：创建skills/目录、生成一个基础的配置文件、可能还会往你的 agent 配置里加一段说明，告诉 agent 去哪里找 skills。

注意：skills init可能会修改你现有的 agent 配置文件（比如CLAUDE.md）。跑之前先git commit一下，出问题好回滚。我第一次跑的时候没注意，把原来的配置覆盖了，折腾了半天才恢复。

4.2 安装第一个 skill：以 TDD 为例

初始化完成后，安装 test-driven-development skill：

skills install test-driven-development

这个命令会从源拉取 skill 定义，写到skills/test-driven-development/目录下。装完之后你可以ls看一下，确认SKILL.md和scripts/都在。

接下来是关键一步：验证 skill 能被 agent 正确识别。不同 agent 的验证方式不一样，但通用做法是启动一个 agent 会话，问它“你现在有哪些可用的 skills”。如果配置正确，agent 应该能列出刚装的 TDD skill。

如果 agent 说“没有可用 skills”，八成是配置文件里的路径不对。检查一下你的 agent 配置里指向 skills 目录的那一行，确保路径是相对于项目根目录的。

4.3 手动跑一遍 skill 脚本

在让 agent 用之前，我强烈建议你先手动把 skill 里的脚本跑一遍。这一步能提前暴露环境问题，避免 agent 调用时才发现脚本跑不起来。

cd skills/test-driven-development bash scripts/run-tests.sh

如果脚本报错，先解决脚本本身的问题。常见的有：脚本没有执行权限（chmod +x scripts/*.sh）、依赖的工具没装、路径写死了。这些在手动阶段解决掉，agent 用起来才顺。

我踩过的一个坑：脚本里用了npx vitest，但项目里 vitest 是 devDependency，npx会去下载最新版而不是用本地的，导致版本不一致测试行为诡异。后来改成./node_modules/.bin/vitest才稳定。脚本里调用本地工具时，优先用node_modules/.bin/下的可执行文件，别用npx。

4.4 让 agent 真正用起来：一个完整任务演示

环境都通了之后，来跑一个真实任务。假设你要给一个函数加个新功能。

你在 agent 会话里说：“给calculateDiscount函数加上会员等级折扣逻辑。”

如果 TDD skill 配置正确，agent 的行为应该是这样的：

1. 先读SKILL.md，确认当前任务匹配 TDD 触发条件。
2. 按照 skill 里的流程，先写一个失败的测试，覆盖会员等级折扣的各种情况。
3. 调用scripts/run-tests.sh，确认测试确实失败（红）。
4. 写最小实现让测试通过。
5. 再次调用脚本，确认测试通过（绿）。
6. 重构代码，保持测试通过。

这个流程走下来，你会明显感觉到 agent 的行为比“裸奔”时更有章法。它不再是一上来就写实现，而是被 skill 的流程约束着走。

提示：第一次跑的时候盯着点，看 agent 是不是真的调用了脚本。有些 agent 会“假装”跑了测试然后编个结果，这时候你需要在 skill 里明确要求“必须调用脚本并贴出真实输出”。

4.5 参数与配置的取舍

skills 体系里有一些可配置项，值得根据项目情况调整。

触发阈值：有些实现允许你配置 skill 触发的敏感度。调高会更容易触发（可能误触发），调低会更保守（可能漏触发）。我的建议是初期调高一点，观察哪些 skill 被误触发，再针对性收紧它们的 description。

上下文预算：如果 agent 支持配置上下文分配，给 skills 留的预算别超过总窗口的 30%。剩下的留给实际代码和对话历史，否则 agent 会“只见规则不见代码”。

脚本超时：默认超时通常偏短，跑大型测试套件容易超时。根据你项目的测试耗时，把超时设成平均耗时的 2 到 3 倍比较稳妥。

这些参数没有标准答案，得根据你项目的实际情况调。我的做法是先用默认值跑一周，记录哪些地方别扭，再针对性调整，避免一上来就过度配置。

5. 常见问题与排查技巧实录

5.1 skill 不触发怎么办

这是最高频的问题。agent 明明装了 skill，但该用的时候不用。排查顺序如下：

我遇到最多的是 description 写得太泛。比如写成“代码相关技能”，agent 根本不知道什么时候该用。改成“当需要重构现有函数、提取公共逻辑时使用”之后，触发率立刻上来了。

5.2 脚本执行失败但 agent 说成功了

这个坑很隐蔽。agent 调用脚本后，如果脚本失败但 agent 没正确解析退出码，它可能会误报成功。

解决办法是在 skill 里明确要求 agent 检查退出码，并且把脚本输出原样贴出来。你可以在 SKILL.md 里写：

执行 scripts/run-tests.sh 后，必须检查退出码。 退出码非 0 时，禁止继续下一步，必须先修复失败原因。 禁止在未看到真实测试输出的情况下声称测试通过。

这种显式约束能大幅降低 agent “自欺欺人”的概率。

5.3 多个 skill 冲突

当你装了多个 skill，可能出现两个 skill 都想处理同一个任务的情况。比如 TDD skill 和 code-review skill 都觉得自己该在“修改代码”时触发。

解决思路有两个：一是收紧 description，让触发条件互斥；二是声明优先级，在元数据里加一个priority字段，让 agent 知道冲突时听谁的。

我一般优先用第一种，因为优先级机制依赖 agent 正确实现，不如把触发条件写清楚来得可靠。

5.4 上下文被 skills 吃满

如果发现 agent 开始“健忘”，经常忘记前面说过的代码，很可能是 skills 占用了太多上下文。

排查方法：看 agent 是否在每次对话都加载了大量 skill 正文。如果是，说明渐进式披露没生效，可能所有 skill 的正文都被当成第一层加载了。

修复方向：确认 SKILL.md 的正文足够精简，把大段内容移到 references/。同时检查 agent 配置，确保它支持按需加载而不是全量加载。

5.5 团队协作时的同步问题

skills 是项目级的，团队成员各自安装容易出现版本不一致。我的做法是把skills/目录纳入版本控制，而不是靠每个人自己skills install。

具体来说：由一个人负责安装和配置 skills，然后把整个skills/目录提交到 git。其他人 clone 下来就有了，不需要各自安装。更新 skill 时也走正常的 PR 流程，这样版本一致、可追溯。

注意：如果 skill 里有脚本，记得检查执行权限有没有被 git 正确记录。有时候chmod +x的改动不会被提交，导致别人 clone 下来脚本跑不了。可以在仓库里加个.gitattributes或者干脆在文档里写明需要手动chmod。

5.6 常见问题速查表

6. 我个人的一些实操心得

聊了这么多机制和流程，最后分享几个我在实际使用中攒下来的、文档里一般不会写的经验。

skill 要“小步快跑”地迭代。别指望一次写出完美的 skill。我的做法是先写个粗糙版本用起来，用一周记录 agent 在哪些地方不听话，然后针对性改 description 或加约束。一个 skill 通常要迭代三五轮才稳定。

给 skill 写“反例”比写“正例”更有用。在 SKILL.md 里明确写“不要做什么”，往往比写“要做什么”更能约束 agent。比如“不要在没有失败测试的情况下写实现代码”，这种否定式约束 agent 记得特别牢。

scripts 的输出格式值得花时间设计。我一开始随便让脚本echo结果，agent 解析得乱七八糟。后来改成固定格式，比如每行[PASS] test_name或[FAIL] test_name: reason，agent 解析准确率立刻上去了。脚本输出是 agent 的“眼睛”，值得认真对待。

别把所有东西都做成 skill。有些一次性的、项目特有的规则，直接写在项目配置里就行，没必要封装。skill 适合那些可复用、有流程、需要执行的能力。滥用 skills 只会让体系变臃肿。

定期清理不再用的 skill。项目演进过程中，有些 skill 会过时。定期 review 一遍skills/目录，删掉不再需要的，保持体系精简。我一般每个季度清一次，每次都能删掉两三个。

这套东西搭起来之后，我最大的感受是：AI coding agents 的上限，很大程度上取决于你给它搭的“脚手架”有多好。agent-skills提供的正是这样一套脚手架，它把零散的经验固化成可复用的能力，让 agent 从“每次都要重新教”变成“装一次就会”。如果你还在手动给 agent 贴提示词，真的值得花一个下午把这套体系搭起来试试。