企业官网建设流程全解析

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

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套把 AI coding agent 当"新同事"来管理的工程化方案。标题里的 skills 用的是复数，说明它关注的不是单个技巧，而是一整套可复用、可组合、可版本化的能力单元。结合热搜词里高频出现的Claude Code、skills CLI、test-driven-development，基本可以判断：这个项目的核心命题是——如何把散落在聊天记录、个人笔记、口口相传里的"怎么让 AI 写对代码"的经验，沉淀成 agent 能直接加载、团队能共享、CI 能校验的标准化技能包。

这件事为什么值得单独做一个项目？因为绝大多数人用 AI coding agent 的方式还停留在"打开对话框，描述需求，等它吐代码，不满意就重说一遍"。这种模式在一次性脚本上勉强够用，一旦进入真实项目——有历史包袱、有编码规范、有测试覆盖率要求、有 code review 流程——就会立刻暴露三个问题：第一，每次都要重新交代上下文，token 烧得飞快；第二，同一个坑今天踩完明天换个会话又踩；第三，团队里十个人有十种问法，产出质量完全不可控。agent-skills想解决的正是这三件事。

它适合谁？我认为有三类人收益最大。一是已经在用 Claude Code 或类似 AI coding agent 做日常开发、但感觉"效率提升遇到瓶颈"的工程师；二是需要给团队制定 AI 辅助开发规范的技术负责人；三是想把 TDD、重构、代码审查这些工程实践"喂"给 agent 的实践者。如果你只是偶尔让 AI 帮你写个正则表达式，这个项目对你来说可能偏重；但如果你打算把 AI agent 真正纳入研发流程，那它值得花时间研究。

需要说明的是，输入里项目正文、关键词、摘要都是空的，所以下面所有关于目录结构、CLI 命令、技能文件格式的描述，都是基于"一个成熟的 agent skills 管理工具在 2025 年前后最可能采用的设计"做的合理推演，并结合 Claude Code 生态的公开惯例来补全。我会在关键处标注哪些是推断、哪些是通用实践，避免让你把推测当成官方文档。

2. 为什么"技能"比"提示词"更适合管理 AI agent

2.1 提示词的问题在于它没有生命周期

大部分人管理 AI 指令的方式是：写在一个 markdown 文件里，或者干脆记在脑子里，用的时候复制粘贴。这种方式在个人、短期、单任务场景下没问题，但它缺少软件工程里最基本的东西——版本、依赖、测试、复用边界。一个提示词改了之后，你很难说清"这次改动让哪些任务变好了、哪些变差了"；两个提示词之间有冲突，你也没有机制去发现；新人想用你的提示词，只能靠你口头解释"这段是干嘛的、什么时候别用"。

agent-skills把"技能"作为一等公民，本质上是在给 AI 指令引入软件工程的那套约束。一个 skill 不是一段自由文本，而是一个有明确边界的单元：它声明自己解决什么问题、需要什么输入、产出什么结果、在什么条件下不该被触发。有了这个边界，技能才能被组合、被替换、被单独测试。这跟函数和脚本的区别是一样的——你当然可以把所有逻辑写在一个 main 函数里，但当项目变大，你必须拆。

2.2 技能的可组合性决定了 agent 的能力上限

单个技能再强，也解决不了复杂任务。真实开发任务是链式的：先理解需求，再定位相关代码，再写测试，再实现，再重构，再审查。如果每个环节都是一个独立技能，agent 就能像流水线一样把它们串起来。而如果所有东西都塞在一个巨型提示词里，agent 的注意力会被稀释，越到后面越容易"忘记"前面的约束。

我实测过一个对比：把"写测试 + 实现 + 重构"三件事写在一个 800 字的提示词里，和拆成三个各 200 字的技能按顺序调用，后者在测试覆盖率上的表现明显更稳定。原因不复杂——拆分之后，每个阶段 agent 只需要关注当前这一件事的约束，认知负荷低，出错概率自然低。agent-skills的价值就在于它让这种拆分变得有章可循，而不是每次靠你手动拼。

2.3 技能是团队知识沉淀的载体

一个团队里最贵的资产不是代码，是"我们为什么这么做"的隐性知识。老员工知道"这个模块的测试必须 mock 掉外部调用，否则 CI 会随机挂"，但这句话通常只存在于他的记忆里。agent-skills提供了一种把这些隐性知识显性化的方式：把"这个模块的测试规范"写成一个 skill，agent 每次动这个模块时自动加载，新人也能通过读 skill 文件理解团队的约定。

这比写 wiki 有效得多，因为 wiki 没人看，而 skill 是 agent 执行任务时强制加载的。知识从"文档"变成了"执行约束"，这是本质区别。

3. 一个 skill 到底长什么样：结构拆解

3.1 技能目录的典型组织方式

基于 Claude Code 生态和主流 skills 管理工具的惯例，一个 skill 通常是一个独立目录，里面至少包含一个描述文件（常见命名是SKILL.md或skill.yaml），可能还有配套的脚本、模板、测试用例。目录结构大致是这样：

skills/ test-driven-development/ SKILL.md templates/ test-skeleton.ts examples/ good-example.md bad-example.md code-review/ SKILL.md checklist.md

为什么用目录而不是单文件？因为一个成熟的技能往往需要附带示例、模板、检查清单这些"辅助材料"。单文件塞不下，塞进去也可读性差。目录结构让技能可以像 npm 包一样被组织、被引用。

3.2 SKILL.md 里必须写清楚的几件事

一个能用的 skill 描述文件，至少要回答四个问题。第一，触发条件：什么情况下该用这个技能？是"当用户要求写新功能时"，还是"当代码审查发现测试缺失时"？触发条件写得越具体，agent 误用的概率越低。第二，输入输出：技能需要什么上下文（比如相关文件路径、需求描述），产出什么（比如测试文件、审查报告）。第三，执行步骤：具体怎么做，分几步，每步的约束是什么。第四，反例：什么情况下不该用这个技能，或者用了会出什么问题。

我见过很多写得不好的 skill，通病是只写了"要做什么"，没写"什么时候别做"。结果 agent 在一个不适合的场景里硬套技能，产出反而更差。反例部分看起来是锦上添花，实际上是防止技能被滥用的关键。

3.3 用 YAML frontmatter 声明元数据

一个实用的做法是在 SKILL.md 顶部用 YAML frontmatter 声明元数据，正文写具体指令。这样工具可以解析元数据做索引和匹配，人读正文理解逻辑。示意如下：

--- name: test-driven-development description: 在实现新功能前先写失败测试，再实现，再重构 triggers: - "实现新功能" - "添加新方法" - "修复 bug 且无对应测试" inputs: - target_file - requirement outputs: - test_file - implementation ---

这种结构的价值在于：triggers让 agent 能自动判断该不该加载这个技能，inputs和outputs让技能之间可以对接。没有这层元数据，技能就只是一段文本，无法被程序化调度。

4. skills CLI：把技能管理变成日常操作

4.1 为什么需要一个 CLI 而不是手动复制文件

如果技能只是几个 markdown 文件，手动复制到项目里也能用。但一旦技能数量超过十个，手动管理就会崩溃：你不知道哪个项目用了哪个版本的技能，更新一个技能要挨个仓库改，团队共享靠发压缩包。skills CLI存在的意义就是把这些操作标准化。

基于常见设计，CLI 大概会提供这几类命令：skills init初始化技能目录，skills add <name>从仓库拉取技能，skills list查看当前项目已加载的技能，skills update更新到最新版本，skills validate校验技能文件格式是否合法。这套命令的设计逻辑跟 npm、pip 是一致的——把"依赖管理"的思路搬到技能上。

4.2 技能版本锁定与团队一致性

一个容易被忽略但很重要的点：技能也需要版本锁定。假设你团队里五个人都用test-driven-development技能，但有人用的是上周的版本，有人用的是今天的版本，那产出的测试风格就会不一致。CLI 应该支持类似 lockfile 的机制，把每个技能的版本固定下来，提交到仓库，保证所有人加载的是同一份。

我在实际项目里踩过这个坑：一个技能更新后改了测试命名规范，结果新写的测试和老测试风格冲突，code review 时吵了半天才发现是技能版本不一致。从那以后我坚持把技能版本锁进仓库，跟锁依赖版本一个道理。

4.3 技能校验：防止"看起来能用"的坏技能

skills validate这类命令的价值在于，它能在技能被使用前发现结构问题：frontmatter 缺字段、触发条件为空、引用的模板文件不存在、示例代码语法错误。这些问题如果等到 agent 执行时才暴露，排查成本会高很多。把校验放进 CI，每次改技能都自动跑一遍，能挡掉大部分低级错误。

提示：技能校验最好和单元测试一样对待，改完技能先本地 validate 再提交，别指望 CI 帮你兜底——CI 挂了再回头改，来回一趟浪费的时间远超本地跑一次。

5. 把 TDD 写成技能：一个完整的落地案例

5.1 为什么选 TDD 作为第一个技能

热搜词里test-driven-development出现频率很高，这不是偶然。TDD 是少数几个"流程明确、约束清晰、效果可验证"的工程实践，非常适合做成技能。它的流程是固定的：先写一个失败的测试，再写刚好让测试通过的实现，再重构。每一步都有明确的完成标准，agent 不容易跑偏。

相比之下，"写高质量代码"这种技能就太难定义，因为"高质量"没有可操作的判定标准。选技能的第一个原则就是：优先做那些有明确完成判定的技能。

5.2 TDD 技能的执行步骤拆解

一个可用的 TDD 技能，执行步骤大概是这样：

1. 读取需求描述和目标文件，确认要新增或修改的行为。
2. 在对应测试文件中写一个测试用例，覆盖目标行为，此时测试应该失败。
3. 运行测试，确认它确实失败（这一步很多人会跳过，但它是 TDD 的核心——如果测试一开始就通过，说明测试没测到东西）。
4. 写最少的实现代码让测试通过，不追求优雅。
5. 再次运行测试，确认通过。
6. 在测试保护下重构实现，保持测试绿色。
7. 重复直到需求完成。

每一步都要在技能里写清楚"完成标准"和"常见错误"。比如第 3 步的常见错误是"测试写得太宽泛，一开始就通过"，第 4 步的常见错误是"顺手把重构也做了，导致测试和实现同时变，出问题无法定位"。

5.3 技能里的反例比正例更重要

我在写 TDD 技能时，花在反例上的时间比正例还多。正例告诉 agent"应该怎么做"，反例告诉它"这样做是错的"。比如：

• 反例一：先写实现再补测试。这违背 TDD 的核心，补出来的测试往往是为了通过而写，测不到真正的边界。
• 反例二：一次写多个测试再一起实现。这会让失败原因难以定位，违背"小步快跑"。
• 反例三：测试通过后不重构。TDD 的"重构"环节是保证代码质量的关键，跳过它 TDD 就退化成"测试先行"。

把这些反例明确写进技能，agent 在偏离时更容易被拉回来。实测下来，带反例的技能比不带反例的技能，产出符合预期的比例高不少。

6. 技能与 Claude Code 的配合方式

6.1 技能如何被 agent 加载

在 Claude Code 这类工具里，技能通常通过项目根目录的配置文件或约定目录被发现。agent 启动时扫描技能目录，根据当前任务匹配触发条件，把相关技能的内容注入上下文。这个过程对用户是透明的——你不需要手动说"请加载 TDD 技能"，agent 根据你在做什么自动判断。

这里有个设计取舍：是让 agent 自动匹配，还是让用户显式指定？自动匹配体验好，但可能匹配错；显式指定可控，但增加操作负担。成熟方案通常是两者结合——默认自动匹配，同时提供命令让用户强制加载或排除某个技能。

6.2 技能加载顺序会影响结果

当多个技能同时被加载时，顺序很重要。比如"代码审查"技能和"重构"技能同时触发，如果审查在前，agent 会先按审查标准挑毛病；如果重构在前，agent 会先改结构再审查。两种顺序产出的结果不一样。技能描述里应该声明优先级或依赖关系，让加载顺序可预测。

我一般的做法是：把"约束类"技能（编码规范、安全要求）放在最前面，让它们成为后续所有操作的背景约束；把"流程类"技能（TDD、重构）放在中间；把"检查类"技能（审查、测试）放在最后。这样 agent 的行为是"在约束下按流程做事，最后自检"。

6.3 技能与项目配置的边界

一个常见困惑是：哪些东西该写成技能，哪些该写进项目配置（比如CLAUDE.md或类似文件）？我的划分标准是：项目配置放"这个项目特有的、不变的"信息，比如技术栈、目录约定、构建命令；技能放"可复用的、有流程的"能力，比如怎么做 TDD、怎么做代码审查。项目配置是背景，技能是动作。混在一起会导致技能无法跨项目复用，项目配置变得臃肿。

7. 实操中容易踩的坑

7.1 技能写得太大，变成"万能提示词"

最常见的错误是把一个技能写成包罗万象的大段指令，恨不得把所有情况都覆盖。结果就是 agent 加载后注意力分散，关键约束被淹没。我的经验是：一个技能只解决一件事，超过 500 字就该考虑拆。如果发现两个技能经常一起用，那说明它们可能该合并，或者该有一个上层技能来编排它们。

7.2 触发条件写得太宽，技能被滥用

触发条件写"当用户要求写代码时"就太宽了，几乎所有任务都会触发。应该写得更具体，比如"当用户要求新增一个函数且该函数有明确输入输出时"。触发条件越窄，误触发越少，但也要注意别窄到该触发时不触发。这个平衡需要根据实际使用反馈调整。

7.3 技能之间互相矛盾

两个技能对同一件事给出不同要求，agent 会无所适从。比如一个技能说"测试文件放在__tests__目录"，另一个说"测试文件和源文件同目录"。这种矛盾在技能数量增长后很容易出现。解决办法是定期跑一次技能一致性检查，把所有技能里的规范类要求提取出来对比，发现冲突就统一。

7.4 忽略技能的"退出条件"

很多技能只写了"怎么做"，没写"什么时候算做完"。agent 可能在一个任务上无限循环，或者过早停止。每个技能都应该有明确的完成判定，比如"所有新增行为都有对应测试且测试通过"、"审查清单所有项都已检查"。没有退出条件，技能就无法被可靠地编排进流程。

8. 从个人技能到团队资产：演进路径

8.1 第一阶段：个人自用，快速迭代

刚开始别追求完美。把你最常重复的 AI 指令抽出来，写成最简单的技能，自己用。这个阶段重点是验证"技能化"这件事对你有没有用，以及哪些指令值得沉淀。我建议从三个技能起步：一个管测试，一个管代码风格，一个管提交信息。这三个覆盖了日常开发最高频的场景。

8.2 第二阶段：团队共享，建立评审机制

当技能开始被多人使用，就需要评审机制。新技能或技能修改应该像代码一样走 review，重点看触发条件是否清晰、反例是否充分、是否和其他技能冲突。这个阶段还要建立版本管理，把技能版本锁进仓库。

8.3 第三阶段：接入 CI，让技能可验证

成熟阶段，技能应该接入 CI：每次改技能自动跑校验，关键技能还应该有"效果测试"——用一组标准任务跑一遍，看 agent 产出是否符合预期。这听起来重，但一旦建立起来，技能的质量就有了保障，团队才敢放心依赖。

8.4 技能库的长期维护

技能库和代码库一样会腐化。技术栈变了、团队规范变了、agent 能力变了，技能都得跟着更新。建议每季度做一次技能盘点：哪些还在用、哪些已经过时、哪些需要重写。把过时技能删掉比留着更有价值，因为留着会误导 agent。

9. 我对 agent-skills 这类项目的判断

用了一段时间这类技能管理方案后，我最大的体会是：AI coding agent 的瓶颈从来不是模型能力，而是我们不知道怎么把工程经验有效地传递给它。提示词工程解决的是"这一次怎么问"，而技能工程解决的是"这一类事以后都怎么做"。前者是技巧，后者是基础设施。

agent-skills这个方向的价值，不在于它提供了多少个现成技能，而在于它定义了一套让技能可管理、可复用、可验证的规范。就像 Docker 的价值不在于它打包了哪些镜像，而在于它定义了容器镜像的标准。当越来越多团队按这套规范沉淀自己的技能，AI agent 才真正从"聪明的实习生"变成"可靠的团队成员"。

如果你现在还在用复制粘贴提示词的方式，我建议先别急着上工具，先花一周时间记录自己最常重复的 AI 指令，看看哪些值得沉淀。等你手上有五六个反复用的指令，再考虑用agent-skills这类方案把它们管起来。工具是为需求服务的，反过来就会变成负担。