企业官网建设流程全解析

1. 从"agent-skills"说起：为什么AI编码代理需要一套技能体系

第一次看到agent-skills这个项目名，我脑子里蹦出来的不是某个具体工具，而是一个更底层的问题：当我们把 Claude Code、Cursor、Copilot 这类 AI coding agents 真正丢进日常开发流程里，它们到底缺什么？答案往往不是模型不够聪明，而是缺少一套可复用、可组合、可测试的技能封装。agent-skills要解决的，正是这个"最后一公里"的问题——把零散的提示词、脚本、工作流沉淀成标准化的 skill，让代理能像调用函数一样调用能力。

我接触 AI 编码代理大概是从 Claude Code 刚开放那阵子开始的。当时最直观的痛点就是：每次让它做重复性任务，比如"跑一遍测试、修掉失败用例、再提交"，都得重新描述一遍流程。提示词写得再细，换个会话就归零。后来社区里陆续出现 skills CLI 这类思路，核心就是把"怎么做一件事"从对话里抽出来，变成磁盘上一个可版本管理的目录。agent-skills就是沿着这条路走的，它更像是一套约定和脚手架，而不是一个孤立的命令行工具。

这篇文章适合三类人看：一是已经在用 Claude Code、但还停留在"聊天式提问"阶段的开发者；二是想把团队内部规范固化成代理能力的 Tech Lead；三是单纯对 AI coding agents 生态好奇、想搞清楚 skills 到底怎么落地的人。我会从设计思路讲到实操细节，包括目录结构、skill 的编写要点、和 test-driven-development 怎么结合，以及我在实际配置中踩过的坑。全程按我自己的使用习惯来讲，不搞教科书那套。

需要先说明一点：agent-skills本身是一个偏"约定"的项目，它不绑定某一个具体的代理产品。你可以把它理解成一套"技能描述规范 + 加载机制"，Claude Code 能用，其他支持类似机制的代理也能用。所以下面讲的内容，重点在思路和可复现的操作，而不是某个版本的按钮位置。

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

2.1 提示词的天花板在哪里

用了几个月 AI 编码代理之后，我对提示词的态度经历了一个明显的转变。刚开始觉得"只要提示词写得好，什么都能干"；后来发现，提示词有三个绕不过去的天花板。

第一个是上下文漂移。一个长会话里，前面定义的规则到后面就慢慢被稀释了，代理开始"自由发挥"。你让它严格按 TDD 来，前两轮还行，第五轮它就直接改代码不写测试了。

第二个是不可复用。你精心打磨的一段提示词，只存在于那次对话里。想在新项目复用？复制粘贴，然后发现项目结构不一样，又得改。

第三个是不可测试。提示词的效果全靠"感觉"，没有断言、没有回归。今天好用，明天模型更新了可能就崩了，你甚至不知道是哪句话导致的。

agent-skills的思路就是把这三点逐个击破：技能以文件形式存在磁盘上，天然解决复用；技能有明确的输入输出约定，可以写测试；技能按需加载，不占用主对话的上下文预算。

2.2 技能的本质：把"过程性知识"外置

我习惯把技能理解成"过程性知识的外置"。声明性知识（比如"这个函数是干嘛的"）模型本身就有；但过程性知识（比如"我们团队提交前必须跑哪几条命令、按什么顺序"）模型不知道，得你告诉它。提示词是一种告诉方式，技能是另一种，区别在于技能是结构化、持久化、可寻址的。

结构化意味着它有固定的字段：名字、描述、触发条件、执行步骤、依赖。持久化意味着它躺在仓库里，跟着代码一起 review、一起版本化。可寻址意味着代理能根据当前任务"检索"到该用哪个技能，而不是把所有技能一股脑塞进上下文。

这个设计直接带来的好处是上下文经济。一个项目可能有几十个技能，但一次任务只需要其中两三个。如果全塞进系统提示，token 消耗爆炸不说，还会互相干扰。按需加载让代理只在需要时把相关技能读进来，这跟人查手册的逻辑是一样的——你不会把整本手册背下来，而是遇到问题时翻到对应那页。

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

热词里出现test-driven-development不是偶然的。TDD 和 agent-skills 是绝配，原因在于 TDD 本身就是一套可验证的过程：先写失败测试、再写实现、再重构。这个过程非常适合封装成技能，因为每一步都有明确的成功判据。

我在实践中的做法是：把"红-绿-重构"拆成三个技能，或者一个技能里的三个阶段。代理接到任务后，先调用"写测试"技能，跑一遍确认失败（这一步很关键，很多人跳过），再调用"实现"技能，最后调用"重构"技能。每个阶段结束都有断言，代理自己就能判断有没有走偏。这比单纯说"请用 TDD 开发"要可靠得多，因为后者全靠模型自觉。

提示：技能不是越细越好。我一开始把每个小步骤都拆成独立技能，结果代理在技能之间反复横跳，反而低效。后来改成"一个技能对应一个可独立验证的交付物"，效果好很多。

3. 技能目录结构与编写规范：一份可直接抄的模板

3.1 目录长什么样

agent-skills的目录约定通常是这样组织的，我按自己项目的实际结构来说：

agent-skills/ ├── skills/ │ ├── tdd-workflow/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ │ └── run-tests.sh │ │ └── examples/ │ │ └── sample.md │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── release-prep/ │ ├── SKILL.md │ └── scripts/ │ └── bump-version.sh └── README.md

每个技能一个目录，目录名就是技能标识。核心文件是SKILL.md，里面写清楚这个技能干什么、什么时候用、怎么用。scripts/放可执行脚本，examples/放示例，方便代理参考。

这种"一个技能一个目录"的布局有个好处：技能可以独立增删。你想禁用某个技能，直接删目录或者移出去就行，不会影响其他技能。团队协作时，每个人负责的技能互不干扰，合并冲突的概率大大降低。

3.2 SKILL.md 的字段设计

SKILL.md是整个技能的灵魂。我总结下来，一个合格的 SKILL.md 至少要包含这几块：

• name：技能名，简短、动词开头，比如run-tests、review-diff。
• description：一句话说清楚这个技能解决什么问题，这句话会被代理用来判断"要不要用这个技能"，所以必须精准。
• when_to_use：触发条件，越具体越好。比如"当用户要求提交代码前"而不是"当需要测试时"。
• steps：执行步骤，有序列表，每步都要可操作。
• verification：怎么验证这一步成功了，这是 TDD 思维的体现。
• dependencies：依赖哪些工具、脚本、环境变量。

我特别想强调description和when_to_use的区别。很多人把这两个写成一回事，其实不然。description是给"人"看的，说明技能用途；when_to_use是给"代理"看的，决定检索匹配。前者可以写得宽泛，后者必须写得窄。窄的触发条件能避免代理在不该用的时候乱用技能。

3.3 一个真实的 SKILL.md 示例

下面是我项目里tdd-workflow技能的简化版，可以直接拿去改：

--- name: tdd-workflow description: 按红-绿-重构流程完成一个功能点或修复 when_to_use: 用户要求新增功能、修复 bug，且项目已配置测试框架 dependencies: - 测试命令可通过 npm test 或 pytest 调用 --- ## 步骤 1. 阅读需求，写出一个会失败的测试用例，运行确认它失败。 2. 写最小实现让测试通过，不要提前优化。 3. 运行全部测试，确认没有破坏其他用例。 4. 在测试保护下重构，每步重构后重跑测试。 5. 输出变更摘要，包含新增/修改的文件和测试结果。 ## 验证 - 第 1 步必须看到测试失败输出，否则说明测试没写对。 - 第 3 步必须全绿，有失败就回到第 2 步。 - 第 5 步的摘要必须包含实际命令输出，不能只写"测试通过"。

这份模板的关键在于每一步都有可观测的结果。代理不需要"理解"TDD 的哲学，它只需要按步骤执行、按验证条件自检。这就是把过程性知识外置的价值。

注意：when_to_use里我特意加了"项目已配置测试框架"这个前提。没有这个前提，代理会试图在没测试的项目里硬跑 TDD，结果就是瞎编测试命令。触发条件写细一点，能省掉大量排查时间。

4. 实操落地：从零搭一套可用的技能体系

4.1 环境准备与 skills CLI 的定位

先说环境。agent-skills本身对运行环境要求不高，Node.js 18+ 或者 Python 3.10+ 都能跑，取决于你用的具体实现。我主力环境是 Ubuntu，偶尔在 macOS 上切，两边都验证过。Windows 的话建议走 WSL，原生环境路径处理容易出幺蛾子。

skills CLI 的作用是管理技能的加载和检索。你可以把它理解成一个"技能包管理器"：安装、列出、启用、禁用技能。它不负责执行技能里的逻辑，执行还是交给代理本身。这个分工很重要，别指望 CLI 帮你跑测试，它只负责让代理"知道有哪些技能可用"。

安装方式通常是全局装一个 CLI，然后在项目里初始化技能目录。我一般不在全局装太多东西，所以更倾向于用npx或者项目本地依赖的方式调用，避免版本冲突。具体命令各实现略有差异，核心就两步：初始化目录、注册技能。

4.2 编写第一个技能：以"提交前检查"为例

我建议第一个技能从"提交前检查"开始，因为它足够简单、足够高频、收益立竿见影。步骤大概是这样：

1. 在skills/下建pre-commit-check/目录。
2. 写SKILL.md，定义触发条件为"用户要求提交代码时"。
3. 步骤里列出：跑 lint、跑测试、检查是否有调试代码残留、生成提交信息。
4. 验证条件：lint 无 error、测试全绿、无console.log/print残留。

写完这个技能，你在 Claude Code 里说"帮我提交"，它就会自动走这套流程，而不是随手git commit。我实测下来，这一个技能就能挡掉大概七成的低级提交问题。

这里有个细节值得说：检查调试代码残留这一步，我一开始没加，结果代理提交了好几次带console.log的代码。后来加上之后，它会在提交前主动 grep 一遍。这个动作人容易忘，代理不会忘，这就是技能的价值。

4.3 把技能接入 Claude Code 的实际配置

接入 Claude Code 的时候，核心是让代理知道技能目录在哪、怎么读。通常有两种方式：一种是通过配置文件指定技能路径，另一种是把技能目录放在代理默认扫描的位置。

我个人的做法是在项目根目录放一个约定文件，声明技能目录。这样换代理产品时，只要新代理支持读这个约定，技能就能复用。配置里我一般会显式指定技能加载策略：是按需检索还是全量加载。前面说过，我强烈建议按需，除非你的技能总数少于五个。

配置完之后，验证是否生效的方法很简单：问代理"你现在有哪些技能可用"，看它列出来的清单对不对。如果列不全，多半是路径没配对；如果列了一堆不该有的，多半是加载策略设成了全量。

提示：技能目录建议纳入版本控制，但scripts/里的脚本要注意别把密钥、token 写进去。我见过有人把带凭证的部署脚本直接提交，这是大忌。敏感信息一律走环境变量。

4.4 用 TDD 验证技能本身是否可靠

技能也是代码，也该测试。这一点很多人忽略。我的做法是给每个技能写一个"冒烟测试"：构造一个最小场景，跑一遍技能，看输出是否符合预期。

比如tdd-workflow技能，我会准备一个只有一两个函数的小项目，故意留一个 bug，然后让代理走一遍技能流程，看它是不是真的先写测试、再修 bug。如果它跳过测试直接改代码，说明技能的when_to_use或步骤描述有问题，得回去改。

这种"测试技能"的循环，本质上就是 meta 层面的 TDD。听起来有点绕，但实际做起来很快，一个技能几分钟就能验证完。比起上线后发现代理乱来，这点投入太值了。

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

5.1 代理不触发技能怎么办

这是最高频的问题。代理明明有技能可用，却不用，直接凭感觉干活。排查顺序我一般是这样的：

先看when_to_use是不是写得太窄。太窄会导致匹配不上，比如你写"当用户明确说'请用 TDD'时"，那用户说"帮我加个功能"就触发不了。这时候要么放宽触发条件，要么在描述里补充同义表达。

再看技能描述是不是太模糊。description如果写成"帮助开发"，代理根本不知道这技能干嘛的，自然不会选。改成"按红-绿-重构流程实现功能点"，匹配度立刻上来。

最后看加载策略。如果技能压根没被加载进检索池，那前面两条都白搭。确认一下技能目录路径和加载配置。

5.2 技能之间互相打架

技能多了之后，冲突是必然的。典型场景：tdd-workflow要求先写测试，quick-fix要求直接改代码。两个技能同时被触发，代理就懵了。

解决办法是给技能排优先级，或者在触发条件里做互斥。我的习惯是给每个技能加一个priority字段，数值小的优先。同时确保高频技能和低频技能的触发条件不重叠。如果实在重叠，就在技能描述里写明"本技能优先于 XXX"。

下面这张表是我整理的常见冲突和化解方式，可以直接对照排查：

5.3 技能执行到一半失败

技能执行失败，最常见的原因是依赖没满足。比如技能里写了跑npm test，但项目用的是pnpm，命令直接报错。这类问题在dependencies字段里写清楚就能避免大半。

另一类失败是环境差异。我在 Ubuntu 上写好的脚本，换到 macOS 上因为sed语法不同就挂了。所以脚本尽量用跨平台写法，或者干脆用 Node/Python 写，别用 shell 的方言特性。

还有一类是代理理解偏差。技能步骤写得含糊，代理按自己的理解执行，结果跑偏。这时候要回去把步骤拆得更细，每步都写成"做什么、用什么命令、期望什么输出"。

5.4 独家避坑清单

踩了几个月坑，我整理了几条血泪经验，都是文档里不会写的：

• 技能别贪多。我一开始建了二十多个技能，结果代理检索时经常选错。后来砍到八个核心技能，准确率反而上去了。技能数量和检索准确率是反比关系。
• 步骤里别写"酌情处理"。代理对"酌情"的理解和你完全不一样。要么写死，要么给明确的判断条件。
• 验证条件要能自动判断。写"代码质量良好"这种没法验证，写"lint 无 error"才行。
• 定期清理僵尸技能。项目演进后，有些技能已经过时了，但还挂在目录里，代理偶尔会误用。我一般每个季度过一遍技能清单。
• 技能命名用动词开头。run-tests比tests好，review-diff比diff-review好。代理对动词开头的技能匹配更准。

注意：如果你在团队里推广技能体系，别一上来就要求所有人写技能。先自己写两三个高频技能，让大家看到效果，再慢慢铺开。强推只会招来抵触。

6. 技能体系的扩展方向与个人实践体会

6.1 从单机技能到团队技能库

个人用技能和团队用技能，复杂度完全不是一个量级。个人用，技能放本地就行；团队用，得考虑共享、版本、权限。我的做法是建一个独立的技能仓库，各项目通过子模块或者包依赖的方式引入。这样技能能统一维护，项目又能按需选用。

团队技能库还有个好处是规范落地。以前团队规范写在 Wiki 里，没人看；现在写成技能，代理执行时自动遵守，规范就"活"了。比如代码风格、提交信息格式、分支命名，全都能固化成技能。

6.2 技能与 CI 的结合

技能不只能在本地跑，还能接进 CI。思路是把技能里的检查步骤抽出来，在 CI 里跑一遍。这样即使有人绕过代理直接提交，CI 也能兜底。

我现在的做法是：技能里的scripts/目录，本地和 CI 共用同一套脚本。本地代理调用它，CI 也调用它。一份逻辑两处用，不会出现"本地过了 CI 挂了"的尴尬。

6.3 我个人的几点体会

用了大半年agent-skills这套东西，最大的体会是：它改变的不是代理的能力，而是你和代理协作的方式。以前你把代理当"聪明的实习生"，什么都得交代；现在你把代理当"按流程办事的同事"，流程写在技能里，它照着做就行。

第二个体会是技能要跟着项目长。项目初期技能少而粗，项目成熟了技能多而细。别指望一次设计到位，边用边改才是常态。

第三个体会是别过度依赖技能。技能适合流程性、重复性的任务；探索性、一次性的任务，直接对话反而更高效。分清楚什么该封装、什么不该封装，是用好这套体系的关键。

最后分享一个小技巧：我会在技能目录里放一个CHANGELOG.md，记录每个技能的修改历史。这样当代理行为发生变化时，我能快速定位是不是某个技能改动导致的。这个习惯帮我省了好几次排查时间，推荐你也试试。