企业官网建设流程全解析

1. 从"agent-skills"说起：为什么这个方向值得认真对待

第一次看到agent-skills这个项目名的时候，我脑子里冒出来的第一个念头是：终于有人把"技能"这件事从提示词里拎出来，当成一个正经的工程对象来管理了。过去大半年，我一直在用各种 AI coding agent 干活，从最早的补全插件到后来的命令行智能体，踩过的坑基本能写一本小册子。最核心的痛点从来不是模型不够聪明，而是同一个任务，每次都要重新交代一遍上下文——项目用什么测试框架、提交信息怎么写、目录结构有什么约定、哪些文件绝对不能碰。这些东西散落在各种CLAUDE.md、.cursorrules、系统提示词里，改一处忘一处，团队里每个人还各写各的。

agent-skills想解决的就是这个问题。它把"技能"抽象成一个可复用、可版本化、可组合的单元，通过一个skillsCLI 来安装、管理和分发。你可以把它理解成 AI coding agent 的"技能包管理器"——类似 npm 之于 JavaScript，或者 Homebrew 之于 macOS。一个 skill 可以是一段测试驱动开发的规范、一套代码审查清单、一个特定框架的迁移流程，甚至是一组终端命令的执行约定。它不绑定某一个具体的 agent，Claude Code 能用，其他支持技能加载的 agent 也能用。

这篇文章适合三类人看：一是已经在用 Claude Code 或其他 AI coding agent、但每次都要重复"喂规矩"的开发者；二是想给团队统一 AI 编码规范、又不想靠人肉记忆的技术负责人；三是单纯对 agent 工程化感兴趣、想看看"技能"这层抽象到底怎么落地的人。我会从设计思路讲到实操细节，把安装、配置、编写自定义 skill、排查问题这一整条链路都走一遍，尽量让你看完就能上手抄作业。

需要先说明一点：agent-skills本身是一个相对轻量的工具层，它的价值高度依赖你往里塞的内容质量。工具再好，技能写得稀烂也没用。所以我会花不少篇幅讲"怎么写一个好 skill"，这部分才是真正拉开差距的地方。

2. 核心设计思路拆解：为什么是"技能"而不是"提示词"

2.1 提示词管理的三个死结

在agent-skills这类工具出现之前，大家管理 agent 行为基本靠三种方式，每一种都有明显的天花板。

第一种是项目根目录的约定文件，比如CLAUDE.md、AGENTS.md、.cursorrules。优点是简单，扔一个文件进去就行。缺点是它是一坨扁平的文本，随着项目变大，这个文件会膨胀到几百行，模型读起来注意力被稀释，人维护起来也痛苦。更要命的是它没法按需加载——你写了一个"数据库迁移"的规范，但当前任务只是改个 CSS，模型还是得把这整段读进去，浪费上下文窗口。

第二种是系统提示词硬编码。有些团队直接改 agent 的启动配置，把规范塞进 system prompt。这种方式最稳定，但完全不可移植，换个 agent 就得重写，而且改一次要重启，迭代成本极高。

第三种是临时粘贴。每次开新会话，手动把规范贴进去。这基本等于没有管理，纯靠人肉记忆，团队协作时灾难现场。

这三个死结的共同点是：规范和任务没有解耦。规范是长期稳定的，任务是短期多变的，把两者混在一起，必然导致要么规范被稀释，要么上下文被浪费。

2.2 技能作为独立单元的三个好处

agent-skills的核心洞察是：把规范拆成独立的、有明确触发条件的"技能单元"。这个设计带来三个直接好处。

按需加载，节省上下文。每个 skill 有自己的描述和触发条件，agent 在执行任务时先看任务匹配哪个 skill，只加载相关的那几个。你写十个 skill，一次任务可能只用到两个，上下文窗口留给真正重要的代码和推理。这一点在长会话里尤其明显，我实测过一个中型项目，用 skill 管理后单次任务的 token 消耗能降三成左右。

可版本化、可分发。skill 是文件，文件就能进 git，就能打 tag，就能通过 CLI 安装。团队里谁改了规范，走正常的代码审查流程，历史可追溯。新人入职不用听老人念叨"我们这儿提交信息要怎么写"，装一下 skill 包就行。

跨 agent 复用。这是我觉得最有远见的一点。今天你用 Claude Code，明天可能换别的 agent，但你的 skill 库不用重写。只要目标 agent 支持技能加载协议，同一套 skill 就能迁移过去。这相当于给你的"团队规范资产"上了一层保险，不被单一工具绑架。

2.3 和 test-driven-development 的关系

热搜词里出现了test-driven-development，这不是偶然。TDD 是最典型的"流程型技能"——它规定的不是某段代码怎么写，而是"先写测试、再写实现、最后重构"这个动作序列。这种流程恰恰是 agent 最容易跑偏的地方：模型天生倾向于直接给你一坨能跑的代码，跳过测试。你把 TDD 写成一个 skill，明确告诉 agent"在这个项目里，任何新功能都必须先产出失败的测试"，它才会老老实实按流程走。

我在实际项目里把 TDD skill 和普通 skill 分开管理，因为它的触发频率极高，几乎每个功能开发任务都要加载。这种高频 skill 值得单独打磨措辞，把"什么算一个合格的失败测试"这种细节写清楚，否则 agent 会写出assert True == True这种糊弄人的测试。

3. 环境准备与 skills CLI 安装实操

3.1 前置条件确认

在动手之前，先把环境理清楚。agent-skills的 CLI 通常依赖 Node.js 运行时，我建议用 LTS 版本，18 或 20 都行。检查一下：

node -v npm -v

如果版本太老，先升级。macOS 上我习惯用nvm管理 Node 版本，Ubuntu 上也是同一套，跨平台一致，省得记两套命令。

# 安装 nvm（如果还没有） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置后 nvm install 20 nvm use 20

注意：不要用系统自带的 Node，很多发行版自带的版本太旧，装 CLI 时会出现各种诡异的依赖报错。用 nvm 隔离出来的环境最干净。

3.2 安装 skills CLI

安装命令本身很简单，但有几个细节值得说。

npm install -g agent-skills # 或者用 pnpm，如果你偏好更快的包管理器 pnpm add -g agent-skills

装完之后验证：

skills --version skills --help

如果skills命令找不到，八成是全局 bin 目录没进 PATH。用npm config get prefix看一下全局安装路径，然后把这个路径下的bin加进你的 shell 配置。macOS 的 zsh 用户改~/.zshrc，Ubuntu 的 bash 用户改~/.bashrc。

export PATH="$(npm config get prefix)/bin:$PATH"

改完记得source一下配置文件，或者干脆重开一个终端。

3.3 初始化项目级技能目录

CLI 装好后，进到你的项目根目录，跑初始化：

cd your-project skills init

这一步会在项目里创建一个技能目录，通常是.agent-skills/或者类似的隐藏目录，里面放一个清单文件和若干 skill 定义。具体结构取决于版本，但核心逻辑是一致的：清单文件记录装了哪些 skill、版本是多少，skill 目录里放具体内容。

我建议把.agent-skills/里的清单文件提交到 git，但把缓存或临时生成的文件加进.gitignore。这样团队共享的是"装了哪些技能"这个事实，而不是每个人本地的缓存副本。

.agent-skills/cache/ .agent-skills/*.log

3.4 安装第一个技能包

从社区或官方仓库装一个现成的 skill 试试水：

skills install tdd-workflow skills list

skills list会列出当前项目已安装的所有技能，包括名称、版本、触发条件。这一步很关键，装完一定要 list 一下确认，我遇到过网络问题导致安装"看起来成功"但实际清单没写入的情况。

提示：安装第三方 skill 前，先skills info <name>看一下它的描述和权限要求。有些 skill 会声明需要执行终端命令的权限，这种要格外谨慎，确认来源可信再装。

4. 编写自定义 skill：从结构到措辞的完整方法

4.1 一个 skill 的最小结构

现成的 skill 好用，但真正体现价值的是你自己写的。一个 skill 文件通常包含几个部分：元信息（名称、描述、触发条件）、正文内容（具体规范）、可选的示例和反例。

--- name: api-error-handling description: 统一后端 API 的错误处理规范，适用于所有新增接口 triggers: - 新增 API 接口 - 修改错误处理逻辑 - 编写接口测试 --- # API 错误处理规范 ## 必须遵守 - 所有错误响应使用统一结构：{ code, message, details } - code 使用业务错误码，不使用 HTTP 状态码代替 - 禁止把内部异常堆栈直接返回给客户端 ## 示例 ...

元信息里的triggers是最需要动脑筋的地方。写得太宽，skill 会被频繁误加载，浪费上下文；写得太窄，该用的时候用不上。我的经验是用任务动词而不是名词来描述触发条件。"新增 API 接口"比"API"好，"修改错误处理逻辑"比"错误处理"好。因为 agent 判断是否加载 skill，靠的是当前任务和触发条件的语义匹配，动词能提供更强的信号。

4.2 措辞的三个原则

写 skill 正文，我总结了三条原则，都是踩坑踩出来的。

第一，用祈使句，不用描述句。"所有错误响应使用统一结构"是祈使句，agent 会当成指令执行。"我们的项目通常使用统一结构"是描述句，agent 可能理解成"这是背景信息，可以参考也可以不参考"。规范类内容必须用祈使句，把"必须""禁止""应该"这些词用足。

第二，给反例，不只给正例。模型对"不要做什么"的遵循度，往往比对"要做什么"更高。你写"提交信息用祈使句"，它可能还是写"Added feature"。但你补一句"禁止使用 Added、Fixed 这类过去式开头"，它立刻就收敛了。反例是约束力的放大器。

第三，控制长度，一个 skill 只讲一件事。我见过有人把一个 skill 写成两千字的"项目开发大全"，结果 agent 加载后注意力全散了。skill 应该像函数一样，职责单一。测试规范一个 skill，提交规范一个 skill，目录结构一个 skill。需要组合时，让 agent 同时加载多个，而不是塞进一个巨型 skill。

4.3 用 skills CLI 创建和测试

skills create api-error-handling

CLI 会生成一个模板文件，你往里填内容。填完保存，然后测试加载：

skills test api-error-handling

这个命令会模拟一次任务匹配，看你的 skill 会不会被正确触发。我强烈建议每写完一个 skill 都跑一下 test，尤其是触发条件，光靠肉眼判断很容易想当然。

如果 test 显示"未匹配"，先检查 triggers 的措辞，再检查 description 是否足够具体。有时候问题出在 skill 名称太抽象，agent 从名字里提取不到有效信号。

5. 与 Claude Code 的集成配置详解

5.1 让 Claude Code 识别技能目录

agent-skills装好的技能，要让 Claude Code 用上，需要在 Claude Code 的配置里指向技能目录。具体做法取决于你用的是命令行版还是 VS Code 插件版，但核心都是告诉 agent 去哪里找 skill 清单。

命令行版通常在项目根目录的配置文件里加一段：

{ "skills": { "enabled": true, "path": ".agent-skills", "autoLoad": true } }

VS Code 插件版则在插件的设置里找到对应项，把技能目录路径填进去。我实测下来，autoLoad打开后体验最顺——agent 每次任务开始自动扫描技能清单，按需加载，不用手动干预。

注意：不同版本的 Claude Code 配置项名称可能有差异，以你本地claude --help或插件设置页显示的实际字段为准。别照抄网上的配置，版本对不上会静默失效。

5.2 验证集成是否生效

配置完别急着干活，先验证。开一个 Claude Code 会话，给它一个明确匹配某个 skill 触发条件的任务，比如"帮我新增一个用户查询接口"。然后观察它的行为：如果它主动提到了你的 API 错误处理规范，说明 skill 加载成功。

如果没反应，按这个顺序排查：

1. 技能目录路径对不对，skills list在项目根目录能不能正常输出
2. Claude Code 的配置有没有语法错误，JSON 少个逗号就会整个失效
3. 触发条件是不是写得太窄，换个更直白的任务描述再试
4. Claude Code 版本是否支持技能加载，太老的版本可能没这个能力

我踩过最坑的一次是配置文件路径写成了绝对路径，换台机器就失效。后来统一改成相对项目根目录的路径，跨机器就没问题了。

5.3 和其他模型的配合

热搜里提到用第三方 API 接入其他模型，这块我的建议是：技能层和模型层尽量解耦。agent-skills管理的是"规范"，模型负责的是"执行"，两者通过技能加载协议连接。只要目标 agent 支持读取技能目录，用哪个模型都能受益。

实际操作中，如果你通过某种方式把 Claude Code 接到了别的模型上，先确认这个链路是否还保留技能加载能力。有些接入方式只是替换了推理后端，技能加载逻辑还在，那就能用；有些则把整个 agent 框架换掉了，技能目录就失效了。这个要具体链路具体测，没有通用答案。

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

6.1 技能不生效的排查速查表

6.2 三个我踩过的坑

坑一：skill 名称和触发条件打架。我写过一个叫clean-code的 skill，触发条件写的是"重构代码"。结果 agent 在写新功能时也频繁加载它，因为"写代码"和"重构代码"在语义上太近。后来把名称改成refactor-checklist，触发条件收紧到"重构已有代码、消除重复逻辑"，误触发就没了。名称要具体，别用大词。

坑二：把 skill 当文档写。早期我往 skill 里塞了大量背景说明、设计理由、历史沿革，写得像一篇技术文档。结果 agent 加载后，真正该执行的规范被淹没在叙述里。后来我定了个规矩：skill 正文里，背景说明不超过三行，其余全是可执行的指令和示例。想写设计理由，写到项目 wiki 里去，别放 skill。

坑三：忽略 skill 之间的冲突。有两个 skill 分别规定"提交信息用中文"和"提交信息用英文"，同时加载时 agent 就懵了。这种冲突在 skill 数量少的时候不明显，一旦超过十个就容易撞车。我的做法是定期跑一遍skills list，人工审一遍所有触发条件，看有没有语义重叠的。重叠的要么合并，要么明确优先级。

6.3 关于权限的实操心得

有些 skill 会声明需要执行终端命令的权限，比如自动跑测试、自动格式化代码。这类 skill 威力大，风险也大。我的原则是：只给来源可信、逻辑透明的 skill 开命令执行权限。自己写的 skill 可以放心开，第三方 skill 先读一遍它的内容，确认没有奇怪的命令再开。

另外，命令执行权限最好配合项目级的沙箱或容器使用。我在一个容器化的开发环境里跑这类 skill，即使 skill 里有问题，影响范围也可控。裸机环境上跑带命令权限的第三方 skill，我是不太敢的。

7. 把技能库当成团队资产来经营

用了一段时间之后，我对agent-skills这类工具的看法变了。它表面上是个 CLI，实际上是在帮你沉淀团队的编码共识。以前这些共识散在每个人的脑子里、聊天记录里、零散的文档里，现在它们变成了可版本化、可审查、可分发的文件。

我现在维护技能库的方式是这样的：每个 skill 一个文件，进 git，改动走 PR。新人入职第一件事是skills install装团队技能包，第二件事是读一遍所有 skill，这比听老人讲两小时规矩高效得多。技能库的更新也有节奏，每当团队在 code review 里反复指出同一个问题，就说明该把它写成一个 skill 了。

有个细节值得单独提：定期清理过时的 skill。项目技术栈变了，旧的规范 skill 就成了噪音。我每个季度会过一遍技能库，把不再适用的删掉或归档。技能库和代码库一样，需要持续维护，不是装完就一劳永逸的。

最后分享一个我最近在试的用法：把 skill 和项目的测试套件绑定。TDD skill 里明确要求"每次实现前先跑一遍现有测试确认基线是绿的"，这样 agent 在动手前会先执行测试命令，等于强制它了解当前项目状态。这个用法还在打磨，但初步效果不错，agent 写出破坏性改动的概率明显下降了。