企业官网建设流程全解析

1. 从“装了一堆技能却用不起来”说起

如果你最近在折腾 AI coding agents，大概率会遇到一个很尴尬的局面：模型本身能力不差，但一到具体项目里就开始“犯迷糊”——不知道你的代码规范、不熟悉你的目录结构、写测试的方式跟你团队完全不一样。你反复在对话里贴规范、贴示例，下一次开新会话又得重来一遍。这个问题的本质不是模型不行，而是缺少一个可复用、可版本化、可组合的能力层。

agent-skills这个项目要解决的就是这件事。它把“让 AI coding agent 按特定方式干活”的能力，从一次性的提示词，变成了一套结构化的、可以安装、可以共享、可以按需加载的 skill 集合。配套的skills CLI负责把这些能力装进你的工作环境，让 Claude Code 这类 AI coding agent 在需要的时候自动调用对应技能。再叠加test-driven-development这类具体 skill，你就能让 agent 真正按 TDD 的节奏写代码，而不是嘴上说说。

这篇内容适合三类人看：一是刚开始接触 Claude Code、还在纠结怎么让它“听话”的开发者；二是已经在用 AI coding agents、但被重复提示词折磨到想砸键盘的人；三是想把团队规范沉淀成可分发资产的技术负责人。我会从设计思路讲到实操落地，把agent-skills这套东西拆开揉碎，包括我踩过的坑和实测有效的配置方式。

2. agent-skills 到底在解决什么问题

2.1 传统提示词工程的三个死穴

先说清楚为什么需要 skills 这个东西。大部分人用 AI coding agent 的方式，是在对话里写一大段系统提示，比如“你是一个资深 Python 工程师，请遵循 PEP8，写测试用 pytest，函数必须有类型注解……”。这种方式有三个绕不过去的死穴。

第一个是不可复用。你在这个项目里写的提示词，换到另一个项目就得重写，因为技术栈变了、规范变了。第二个是不可组合。当你既想要 TDD 规范，又想要特定的 commit message 格式，还想让它遵守某个框架的最佳实践，提示词会膨胀到几千字，模型注意力被稀释，效果反而下降。第三个是不可维护。规范更新了，你得去翻历史会话，找到那段提示词改掉，而团队里其他人根本不知道你改了什么。

agent-skills的思路是把这些能力拆成独立的 skill 单元，每个 skill 只负责一件事，通过skills CLI安装到本地，agent 在运行时按需加载。这就像从“每次做饭都从头备料”变成“冰箱里常备切好的配菜”，需要哪个拿哪个。

2.2 skill 的本质：给 agent 的“操作手册”

一个 skill 说白了就是一份写给 AI 看的操作手册，通常包含几个部分：触发条件（什么时候该用这个 skill）、执行步骤（具体怎么做）、约束条件（不能做什么）、以及示例（做对了长什么样）。它跟普通提示词最大的区别在于结构化和可寻址。

结构化意味着每个 skill 有固定的元数据格式，agent 能解析出它的用途和适用范围。可寻址意味着 skill 有唯一标识，可以被引用、被依赖、被版本管理。举个例子，test-driven-development这个 skill 会明确告诉 agent：先写失败的测试，再写最小实现让测试通过，最后重构。这三步不是建议，是强制流程，agent 必须按顺序执行。

我实测下来，这种结构化约束对 agent 的行为改变非常明显。以前你让它写个函数，它直接给你实现代码；装了 TDD skill 之后，它会先问你要测试文件放哪，然后老老实实先写测试。这个差别在复杂项目里就是“能维护”和“一团乱麻”的区别。

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

有人会问，为什么agent-skills要用 CLI 分发，而不是搞个图形化的插件市场。我的理解是，CLI 更贴合开发者的工作流。你在终端里敲一条命令就能装好 skill，不需要离开编辑器去点网页。而且 CLI 天然支持脚本化，团队可以把 skill 安装写进项目初始化脚本，新人 clone 完代码跑一条命令，环境就配好了。

另外 CLI 的版本管理更清晰。skill 可以锁定版本，避免某天上游更新导致 agent 行为突变。这在团队协作里很重要——你不想因为某个 skill 的作者改了默认行为，导致整个团队的代码风格一夜之间变样。

3. 核心机制拆解：skill 是怎么被 agent 用起来的

3.1 skill 的加载与匹配流程

理解agent-skills的关键，是搞清楚 agent 在什么时机、以什么方式加载 skill。整个流程大致分四步：安装、索引、匹配、注入。

安装阶段，skills CLI把 skill 文件放到约定的目录里，通常是项目根目录下的某个隐藏文件夹，或者用户级的全局目录。索引阶段，agent 启动时会扫描这些目录，读取每个 skill 的元数据，建立一张“能力清单”。匹配阶段，当你的请求进来，agent 会根据 skill 的触发条件判断哪些相关。注入阶段，被选中的 skill 内容会被拼接到当前上下文里，指导 agent 的行为。

这里有个容易踩的坑：skill 不是越多越好。如果你装了五十个 skill，每次请求都注入一大堆无关内容，上下文会被迅速占满，模型反而变笨。好的做法是按项目装 skill，这个项目需要 TDD 就装 TDD，需要特定框架规范就装那个框架的，不要一股脑全装上。

3.2 触发条件的写法决定成败

skill 能不能被正确调用，八成取决于触发条件写得好不好。写得太宽泛，比如“当用户要求写代码时”，那它会在所有场景下被激活，变成噪音。写得太窄，比如“当用户明确说‘请用测试驱动开发’时”，那它几乎不会被触发，等于白装。

我的经验是，触发条件要描述任务特征而不是用户措辞。比如 TDD skill 的触发条件应该写成“当任务涉及新增功能实现或修改现有逻辑时”，而不是“当用户提到测试时”。因为用户很少会主动说“请用 TDD”，但新增功能这个场景是客观存在的，agent 应该自己判断该用 TDD。

下面这张表是我总结的触发条件写法对比，供你参考：

3.3 skill 之间的依赖与冲突处理

当项目里装了多个 skill，它们之间可能产生依赖或冲突。依赖的例子：某个“写 API 接口”的 skill 可能依赖“错误处理规范”这个 skill，因为接口实现必须包含统一的错误处理。冲突的例子：一个 skill 要求函数必须写类型注解，另一个 skill 说保持代码简洁不要冗余，两者在“要不要写注解”上可能打架。

agent-skills处理这个问题的方式是引入优先级和依赖声明。每个 skill 可以声明它依赖哪些其他 skill，以及它的优先级数值。当多个 skill 同时匹配时，agent 按优先级排序，高优先级的约束覆盖低优先级的。依赖则确保被依赖的 skill 一定被加载，不会出现“用了接口 skill 但错误处理规范没加载”的情况。

提示：装 skill 之前先看一眼它的依赖声明，避免出现“装了 A 但没装 A 依赖的 B”这种半吊子状态。CLI 一般会在安装时提示缺失依赖，别忽略那个警告。

4. 实操：从零把 agent-skills 跑起来

4.1 环境准备与 CLI 安装

假设你已经在用 Claude Code，环境是 macOS 或者 Ubuntu，Node.js 版本在 18 以上。第一步是装skills CLI。常见的安装方式是通过包管理器，命令大致长这样：

npm install -g agent-skills-cli

装完之后验证一下：

skills --version

如果提示命令找不到，八成是全局 bin 目录没在 PATH 里。macOS 上通常是/usr/local/bin或~/.npm-global/bin，Ubuntu 上可能是/usr/bin。你可以用npm config get prefix看全局安装路径，然后把它加到 PATH。

这里有个我踩过的坑：别用 sudo 装全局包。用 sudo 装完之后，普通用户跑skills命令可能因为权限问题读不到配置目录，报一堆莫名其妙的错。正确做法是配置 npm 的全局目录到用户目录下，避免权限纠缠。

4.2 安装第一个 skill：test-driven-development

环境好了之后，装第一个 skill 练手。TDD 是最适合入门的，因为它的行为改变最直观。安装命令通常是：

skills install test-driven-development

装完之后，CLI 会把它放到 skill 目录里。你可以用skills list看看装了什么：

skills list

输出大概是这样：

Installed skills: test-driven-development v1.2.0 (active)

注意那个active状态。有些 skill 装完默认是激活的，有些需要手动启用。如果状态是inactive，用skills enable test-driven-development打开。

4.3 在 Claude Code 里验证 skill 是否生效

装完不等于生效，得验证。最直接的方式是给 Claude Code 一个新增功能的任务，看它是不是先写测试。比如你说“给这个工具类加一个计算两个日期相差天数的方法”，如果 TDD skill 生效了，agent 应该先创建一个测试文件，写一个失败的测试，然后再去实现。

如果它直接给你实现代码，说明 skill 没被加载。排查顺序是：先确认skills list里状态是 active，再确认 skill 目录路径跟 Claude Code 扫描的路径一致，最后看触发条件是不是写得太窄导致没匹配上。

我实测下来，Claude Code 对 skill 的加载有个缓存机制，装完新 skill 之后最好重启一下会话，不然可能读的还是旧的能力清单。这个细节官方文档不一定写，但实际用的时候经常遇到。

4.4 组合多个 skill 的配置示例

单个 skill 跑通之后，可以试试组合。比如一个典型的后端项目，你可能想同时装这几个：TDD 规范、API 设计规范、数据库迁移规范、commit message 规范。安装命令可以串起来：

skills install test-driven-development skills install api-design-guidelines skills install db-migration-rules skills install conventional-commits

装完之后检查一下有没有冲突。用skills doctor这类诊断命令（不同版本命令名可能不同）看看依赖是否完整、优先级是否有冲突。如果两个 skill 都声称管 commit message，你得手动调优先级，把更符合团队习惯的那个调高。

注意：skill 组合不是简单叠加。每多一个 skill，上下文占用就多一份。我的建议是单个项目常驻 skill 不超过五个，其余按需临时启用。装太多会让 agent 的响应变慢，而且约束之间容易打架。

5. 常见问题与排查实录

5.1 skill 装了但 agent 不调用

这是最高频的问题。表现是skills list显示已安装且激活，但 agent 行为没有任何变化。排查思路按这个顺序走：第一，确认 skill 目录路径。Claude Code 扫描的目录可能是项目级的.claude/skills或用户级的~/.claude/skills，你装到了别的地方它自然读不到。第二，确认触发条件。把 skill 文件打开，看触发条件描述的任务特征，跟你实际给的任务是否匹配。第三，确认会话是否重启。前面说过缓存问题，装完 skill 不重启会话，agent 用的还是旧清单。

如果这三步都排除了还是不生效，那可能是 skill 文件格式有问题。检查一下元数据是不是合法的 YAML 或 JSON，字段名有没有拼错。CLI 一般有校验命令，跑一下能快速定位格式错误。

5.2 多个 skill 行为冲突

冲突的表现是 agent 行为摇摆不定，一会儿这样一会儿那样。比如你让它写个函数，它先写了类型注解，又删掉，又加上。这通常是两个 skill 的约束矛盾，agent 在两者之间反复横跳。

解决办法是明确优先级。在 skill 配置里给每个 skill 设一个 priority 数值，数值大的覆盖数值小的。或者更彻底一点，把冲突的 skill 合并成一个，把矛盾的地方在合并时统一掉。我倾向于后者，因为优先级机制只是让冲突“不那么明显”，并没有真正解决规范层面的矛盾。

5.3 上下文被 skill 占满导致响应变慢

skill 内容也是要占 token 的。如果你装了十个 skill，每个平均五百字，那就是五千字左右的固定开销，还没算你的实际请求。上下文窗口是有限的，被 skill 占多了，留给实际代码的空间就少了，agent 处理大文件时容易丢细节。

我的做法是分层管理：核心规范（比如 TDD、代码风格）常驻，项目特定的规范（比如某个内部框架的用法）按需启用。CLI 一般支持skills enable和skills disable动态切换，写代码前根据任务类型调整一下，比一股脑全开着强。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是在错误的目录装 skill。我一开始在用户目录装，但项目里 Claude Code 只扫项目级目录，结果死活不生效，折腾了半小时才发现是路径问题。后来养成习惯，装完先skills list --verbose看实际路径。

第二个坑是忽略 skill 的版本。有次上游更新了一个 skill，默认行为从“先写测试”变成了“测试和实现同时给”，我这边没锁版本，第二天 agent 行为就变了，排查半天才想起来是 skill 更新。现在我在项目里会固定 skill 版本，升级前先看 changelog。

第三个坑是触发条件写得太“聪明”。我试过用很复杂的条件描述，结果 agent 理解不了，反而不触发。后来发现触发条件越直白越好，就描述任务类型，别搞太多逻辑判断。

6. 把 skill 沉淀成团队资产

6.1 从个人使用到团队分发

个人用 skill 是提效，团队用 skill 是统一标准。当你的团队有五六个人都在用 AI coding agent，如果没有统一的 skill 集，每个人调教出来的代码风格都不一样，review 的时候会很痛苦。把团队规范写成 skill，通过 CLI 分发，新人入职跑一条命令就对齐了。

分发的形式可以是内部 npm 包，也可以是 git 仓库。skills CLI一般支持从多种源安装，比如skills install git+https://内部仓库地址。团队维护一个 skill 仓库，按项目类型分目录，前端一套、后端一套、数据一套，各取所需。

6.2 写一个自定义 skill 的要点

写自定义 skill 的时候，有几个要点值得注意。第一，一个 skill 只干一件事。别把代码风格、测试规范、部署流程塞进一个 skill，那样既难维护又难复用。第二，示例比描述重要。给 agent 看一个“做对了”的代码示例，比写三百字描述有效得多。第三，约束要可验证。别写“代码要优雅”这种没法验证的约束，写“函数不超过五十行”“必须有错误处理”这种能检查的。

第四，留好版本号。skill 是会演进的，一开始的规范可能过两个月就不适用了。用语义化版本号，让使用者能选择升级时机。第五，写清楚适用范围。这个 skill 是给 Python 项目用的还是通用的，是给新项目用的还是老项目也适用，这些信息要写在元数据里，避免误用。

6.3 skill 的维护与迭代节奏

skill 不是写完就完了，它需要跟着项目演进。我的做法是每个季度 review 一次常驻 skill，看看有没有过时的约束、有没有可以合并的 skill、有没有新的规范需要沉淀。review 的时候拉上团队一起，因为规范这东西，写的人和使用的人理解经常有偏差。

迭代的时候注意向后兼容。如果你改了一个 skill 的默认行为，最好发个大版本号，让使用者有心理准备。小版本号留给措辞优化、示例补充这种不影响行为的改动。这个习惯能避免“某天早上来发现 agent 行为全变了”的惊吓。

7. 一些实测下来的经验

用agent-skills这套东西有一段时间了，最大的体会是：skill 的价值不在于多，而在于准。装十个泛泛的 skill，不如装两个精准的。精准的 skill 能在关键时刻改变 agent 的行为，泛泛的 skill 只是占上下文。

另一个体会是，skill 要和 code review 配合。skill 能约束 agent 写出符合规范的代码，但 agent 不是百分百可靠，还是需要人来看。我的做法是把 skill 里的核心约束提取成 review checklist，agent 写完代码，人按 checklist 过一遍，双重保险。

最后分享一个小技巧：给 skill 写一个“反例”部分。除了告诉 agent 该怎么做，也告诉它不该怎么做。比如 TDD skill 里可以写“不要先写实现再补测试，这是反模式”。反例对 agent 的约束效果，有时候比正例还强，因为模型对“禁止”类指令的遵循度通常更高。

这套东西还在演进，CLI 的命令和 skill 的格式可能会变，但核心思路是稳定的：把能力结构化、可复用、可组合。抓住这个思路，具体工具怎么变都能跟上。