企业官网建设流程全解析

1. 从“agent-skills”说起：为什么我们需要给AI编码代理装上技能包

第一次看到agent-skills这个项目名，我脑子里蹦出来的不是某个具体工具，而是一类正在快速成型的东西——给AI编码代理（AI coding agents）定义、分发、复用“技能”的机制。你可以把它理解成给一个刚入职的聪明实习生发一本《岗位操作手册》，手册里写清楚：遇到什么场景、该调用什么工具、按什么步骤执行、验收标准是什么。没有这本手册，实习生也能干活，但干得随机、不稳定、每次都要重新教；有了手册，他就能稳定输出，而且团队里每个人都能共享同一套最佳实践。

agent-skills要解决的核心问题就是这个：把“怎么让AI代理把一件事做对”这件事，从一次性的提示词（prompt）里抽出来，变成可版本化、可组合、可测试的资产。它通常包含一个skills CLI，用来创建、安装、列出、运行技能；技能本身往往以目录或包的形式存在，里面装着指令、脚本、模板、测试用例。配合Claude Code这类支持工具调用和终端执行的代理运行时，技能就能真正落地——代理不只是“聊”，而是能读文件、跑命令、改代码、跑测试。

这篇文章适合谁看？三类人：第一类是把Claude Code当日常编码搭子、但总觉得它“时灵时不灵”的开发者；第二类是团队里想统一AI编码规范、避免每个人各写一套提示词的技术负责人；第三类是对test-driven-development和代理工程化感兴趣、想看看“技能”这层抽象到底怎么设计的工程师。我会从设计思路、核心细节、实操流程、问题排查四个层面，把agent-skills这类项目拆开讲透，中间会穿插Claude Code的安装配置、skills CLI的用法、以及我在实际使用中踩过的坑。

先给一个整体判断：agent-skills不是那种“装完就起飞”的银弹，它更像是一套工程约束。你投入多少，它回报多少。如果你只是偶尔让AI写个正则，那没必要上技能体系；但如果你每天都要让代理做重复性任务——比如“新增一个API端点并补测试”“按规范重构某个模块”“生成数据库迁移脚本”——那技能包带来的稳定性提升是肉眼可见的。

2. 核心设计思路拆解：技能为什么比提示词更靠谱

2.1 提示词的三个致命伤

在讲agent-skills的设计之前，得先说清楚它要替代的东西——裸提示词——到底哪里不行。我用Claude Code做项目时，最开始也是把要求写在对话里：“帮我加一个用户注册接口，用FastAPI，要校验邮箱，写单元测试。”第一次效果不错，第二次换个模块，代理就开始自由发挥：有时候用Pydantic v1的写法，有时候忘了加异常处理，测试覆盖率忽高忽低。问题出在三个地方。

第一是不可复用。提示词躺在聊天记录里，换一个会话就没了。你没法像代码一样git clone一份提示词给同事。第二是不可测试。你怎么知道这次代理执行得对？只能靠人肉review，而人肉review的注意力是有限的。第三是上下文漂移。长对话里，代理会逐渐“忘记”早期约束，尤其是当你在中间插入了别的任务之后。这三个问题叠加，导致裸提示词只适合一次性、低风险的任务。

agent-skills的思路是把技能做成文件系统里的实体。一个技能通常是一个目录，里面有SKILL.md（或类似的主指令文件）、可选的脚本、模板、测试。代理运行时（比如Claude Code）在需要时加载这个技能，把里面的指令注入上下文，并可以调用技能附带的脚本。这样做的好处是：技能可以被版本控制、被代码审查、被自动化测试，而且每次加载都是“新鲜”的，不会受长对话污染。

2.2 技能的分层：指令、工具、验收

我观察下来，一个设计良好的技能包通常分三层。最上层是指令层，用自然语言写清楚“什么时候用这个技能、目标是什么、有哪些约束”。这一层是给代理的“大脑”看的，要写得像给新人的任务说明，而不是像API文档。中间层是工具层，也就是技能附带的脚本或命令。比如一个“生成数据库迁移”的技能，可能带一个scripts/check_schema.py，代理在动手前先跑一下，确认当前schema状态。最下层是验收层，通常是测试用例或检查清单。test-driven-development之所以常和agent-skills一起出现，就是因为TDD天然适合做验收层：先写测试，代理改代码直到测试通过，通过与否是客观的，不依赖人的主观判断。

这三层对应到skills CLI的操作，大概是：skills create生成骨架，skills install把技能装到代理能发现的位置，skills run触发一次技能执行，skills test跑验收。不同项目的CLI命令名可能略有差异，但逻辑大同小异。理解了这个分层，你再看任何agent-skills实现，都能快速定位它哪一层做得好、哪一层偷懒了。

2.3 为什么选“技能”而不是“插件”或“工作流”

有人会问：这不就是插件吗？或者用工作流引擎（比如某些低代码平台）也能做。区别在于代理的自主性。插件通常是确定性的：输入A，输出B，中间没有决策。工作流也是预先编排好的。但AI编码代理的价值恰恰在于它能根据上下文做判断——比如同样是“加接口”，在有缓存层的项目里它应该顺手加缓存失效逻辑，在没有的项目里就不该加。技能给的是约束下的自由度：指令层划定边界和验收标准，具体怎么实现由代理在边界内决定。这比死板的工作流更适应真实代码库的多样性，又比裸提示词更可控。

另一个考量是与现有工具链的兼容。Claude Code本身支持读取项目里的CLAUDE.md之类的文件作为上下文，agent-skills可以看作是把这种机制进一步结构化、可分发化。你不需要换掉Claude Code，只需要在项目里放一个skills/目录，代理就能发现并使用。这种“渐进增强”的路径，比要求团队整体迁移到某个新平台要现实得多。

3. 核心细节解析与实操要点：技能包里到底装什么

3.1 技能目录的标准结构

我参考过几个不同的agent-skills实现，也自己搭过，比较通用的目录结构是这样的：

skills/ add-api-endpoint/ SKILL.md scripts/ check_routes.py templates/ endpoint.py.tmpl test_endpoint.py.tmpl tests/ test_skill.py

SKILL.md是入口，通常包含几块内容：name和description（让代理知道这个技能是干嘛的）、when_to_use（触发条件）、instructions（具体步骤）、verification（怎么算完成）。scripts/放辅助脚本，templates/放代码模板，tests/放验收测试。这个结构不是强制的，但遵循它能让技能更容易被不同运行时识别。

写SKILL.md时有个关键技巧：指令要写成“检查点”而不是“教程”。比如不要写“首先打开文件，然后找到第10行……”，而要写“确认目标模块已有对应的测试文件；如果没有，先创建；接口实现后，运行pytest tests/test_target.py必须全绿”。前者假设了固定的代码结构，后者适应变化。代理在执行时会自己规划路径，你只需要把“什么算对”说清楚。

3.2 触发条件的设计：别让技能乱触发

技能多了之后，最大的问题不是“代理不会用”，而是“代理用错”。比如你有一个“重构”技能和一个“加功能”技能，代理可能在你只想加个小功能时触发重构，把代码改得面目全非。所以when_to_use要写得足够具体，最好包含反例。我常用的写法是：

当用户明确要求“新增端点”且目标文件是路由文件时使用。如果用户只是问“这个端点怎么工作”，不要使用本技能，直接解释即可。

这种“正向条件+反向排除”的写法，能显著降低误触发。另外，技能之间最好有优先级或互斥声明。有些skills CLI支持在元数据里写conflicts_with，没有的话就在指令里手动写清楚。

3.3 脚本与代理的协作边界

技能附带的脚本应该做确定性的事，代理做判断性的事。举个例子：一个“生成迁移脚本”的技能，脚本可以负责“读取当前数据库schema并输出JSON”，代理负责“根据JSON和用户需求决定加哪些字段”。不要让脚本去猜用户意图，也不要让代理去手写正则解析schema——那是脚本的活。这个边界划清楚，技能就稳定；划不清楚，就会出现“脚本输出格式变了，代理解析失败”这类问题。

实操中我建议脚本遵循两个原则：输出结构化（JSON优先，避免自由文本）、幂等（跑两次结果一样）。代理调用脚本时，通常会把stdout拿回来解析，结构化输出能减少歧义。幂等则保证代理重试时不会产生副作用。

3.4 与Claude Code的集成方式

Claude Code作为代理运行时，集成agent-skills一般有两种方式。一种是项目级：在项目根目录放skills/，Claude Code启动时自动扫描。这种方式适合团队共享，技能跟着代码库走。另一种是用户级：装在用户主目录下，所有项目都能用。适合个人常用技能，比如“按我的代码风格格式化”。

配置时要注意Claude Code的上下文窗口。技能不是越多越好，每个技能加载都会占token。我一般把项目级技能控制在5个以内，用户级控制在10个以内。如果技能很多，可以用skills CLI的list命令看看哪些是活跃的，定期清理不用的。另外，Claude Code的某些版本对技能目录的命名有要求（比如必须是skills而不是.skills），装完后最好用skills list确认一下代理能不能发现。

4. 实操过程与核心环节实现：从零搭一个技能并跑通

4.1 环境准备：Claude Code安装与基础配置

在搭技能之前，得先把代理运行时装好。Claude Code的安装方式因平台而异。在macOS或Ubuntu上，通常通过包管理器或官方提供的安装脚本。安装完成后，第一次运行需要配置模型访问方式。这里有个常见问题：Claude Code默认可能要求登录官方账号，但很多开发者想用自己的第三方API或本地模型。根据热词里提到的“claude code harness可以不登录用其他模型吗”，答案是：取决于具体版本和配置方式。有些版本支持通过环境变量指定API端点，有些则需要修改配置文件。

我自己的做法是：先按官方文档完成基础安装，确认claude命令能跑起来，再考虑替换模型。替换模型时，注意Claude Code对模型的能力有要求——它需要模型支持工具调用（function calling）和较长的上下文。如果用一个不支持工具调用的模型，代理就无法执行终端命令，技能里的脚本也就跑不起来。所以选模型时，先确认它支持这些能力。配置完成后，用claude --version和claude "列出当前目录文件"做个冒烟测试，确认代理能读文件、能执行命令。

4.2 用skills CLI创建第一个技能

假设skills CLI已经装好（通常通过npm或pip），创建技能的命令大概是：

skills create add-api-endpoint --template basic

这会生成一个技能目录骨架。然后编辑SKILL.md，填入指令。我以一个FastAPI项目为例，写一个“新增GET端点”的技能。指令部分我会这样写：

## 目标 在指定的路由文件中新增一个GET端点，返回JSON，并补充对应的单元测试。 ## 步骤 1. 确认目标路由文件存在，且已导入必要的依赖（如 `APIRouter`）。 2. 在路由文件中新增端点函数，路径和函数名由用户指定。 3. 在 `tests/` 下找到或创建对应的测试文件，新增测试用例，覆盖正常返回和参数校验失败两种情况。 4. 运行 `pytest tests/`，确保新增测试通过且没有破坏已有测试。 ## 验收 - 新端点可通过 `curl` 或测试客户端访问。 - 新增测试全部通过。 - 已有测试无回归。

写完后，用skills install add-api-endpoint把它装到项目里。然后启动Claude Code，输入“用add-api-endpoint技能，在users路由里加一个GET /users/{id}端点”。代理应该会加载技能、按步骤执行、最后跑测试。

4.3 参数计算与选择：技能粒度的权衡

技能粒度是个需要反复调的参数。太粗，比如一个“开发整个功能”的技能，指令会变得又长又模糊，代理执行时容易跑偏；太细，比如“新增一行import”也做成技能，技能数量爆炸，维护成本高。我的经验是：一个技能对应一个可独立验收的交付物。比如“新增端点”是一个交付物，“新增数据库迁移”是另一个，“重构某个函数”是第三个。每个交付物都有明确的完成标准，这样技能边界清晰，验收也简单。

另一个参数是指令长度。我试过写很详细的指令，结果代理反而拘谨，遇到指令没覆盖的情况就卡住。后来我把指令控制在200-400字，只写目标、关键约束、验收标准，具体实现留给代理。这样代理的完成率反而更高。如果某个技能经常在某个环节出错，再针对性地加一条约束，而不是一开始就写满。

4.4 跑通TDD闭环：让测试成为技能的裁判

test-driven-development和agent-skills结合，效果最好。具体做法是：技能指令里明确要求“先写测试，再写实现，最后跑测试”。代理执行时，会先根据模板生成测试文件，然后实现功能，再运行测试。如果测试失败，代理会根据错误信息调整实现，直到通过。这个闭环的关键是测试必须由技能提供或由代理生成且可运行。如果测试是写在指令里的伪代码，代理没法执行，闭环就断了。

我在实操中会要求技能附带一个tests/目录，里面放一个基础测试模板。代理生成新测试时，基于模板改，保证测试框架和项目一致。跑测试的命令也写在技能里，比如pytest tests/test_users.py -v。这样代理不需要猜项目用什么测试框架。实测下来，有TDD闭环的技能，一次通过率比没有的高不少，因为代理有了客观的反馈信号，不会“自认为写对了”就停下。

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

5.1 技能不触发或触发错误

最常见的问题是代理根本没加载技能。排查步骤：先用skills list确认技能已安装且路径正确；然后检查Claude Code的启动日志，看它扫描了哪些目录；最后确认技能名和用户输入的关键词是否匹配。如果技能被加载了但没触发，多半是when_to_use写得太窄或太宽。太窄就放宽条件，太宽就加反例。我遇到过一次，技能描述里写了“新增端点”，结果用户说“加个接口”就没触发。后来在描述里补了“接口、端点、路由”几个同义词，问题解决。

5.2 脚本执行失败

脚本失败通常有三类原因：路径问题、依赖问题、权限问题。路径问题最常见——脚本里用了相对路径，但代理的工作目录和预期不一致。解决办法是在脚本里用绝对路径，或者让技能指令明确cd到项目根目录再执行。依赖问题比如脚本需要requests但环境里没装，解决办法是在技能里声明依赖，或者把脚本写成只用标准库。权限问题在Ubuntu上常见，脚本没有执行权限，chmod +x即可。排查时，先手动跑一遍脚本，确认脚本本身没问题，再看代理调用时的上下文差异。

5.3 代理“自作主张”偏离技能

有时候代理加载了技能，但执行到一半开始自由发挥，比如跳过了测试步骤。这通常是因为指令里的验收标准不够硬。我的对策是把验收标准写成可执行的检查，而不是描述性文字。比如不写“确保测试通过”，而写“运行pytest tests/ -q，退出码必须为0”。代理对可执行检查的遵守度明显更高。另外，可以在技能里加一条“如果任何验收检查失败，停止并报告，不要继续修改代码”，防止代理在失败后乱改。

5.4 技能之间的冲突

当项目里有多个技能时，可能出现两个技能都声称适用的情况。比如“新增端点”和“重构路由”都匹配“修改路由文件”。解决办法是在技能元数据里声明优先级，或者在指令里写清楚互斥条件。我一般会给技能加一个priority字段，数字小的优先。如果没有这个机制，就在SKILL.md开头写“本技能仅当用户明确要求新增功能时使用；如果用户要求改善现有代码结构，请使用重构技能”。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑是技能名用中文。早期我图省事，技能名写成“新增接口”，结果CLI和代理对中文名的处理不一致，有时找不到。后来统一用英文短横线命名，问题消失。第二个坑是在技能里写死项目路径。换一个项目，技能就废了。正确做法是用相对路径或环境变量。第三个坑是技能太多导致启动慢。Claude Code启动时要扫描所有技能，技能多了启动明显变慢。定期清理不用的技能，能省不少时间。第四个坑是忽略代理的反馈。有时候代理会报告“技能里的某条指令与当前代码库不符”，这其实是技能需要更新的信号，别忽略，及时改。

6. 技能体系的扩展与团队协作

6.1 把技能纳入代码审查

技能既然是文件，就应该像代码一样审查。我们团队的做法是：新增或修改技能时，走正常的PR流程，至少一个人review。review的重点不是指令写得好不好看，而是验收标准是否可执行、触发条件是否清晰、有没有和现有技能冲突。review通过后，技能随代码库一起合并，所有人下次拉代码就能用。这样技能的质量有保障，也不会出现“某个人本地有个神奇技能但别人都没有”的情况。

6.2 技能的分发与版本管理

技能可以放在项目仓库里，也可以做成独立的包通过skills CLI分发。项目级技能适合和项目强相关的，比如“按本项目规范生成迁移”。跨项目通用的技能，比如“生成commit message”，适合做成包。版本管理上，技能包遵循语义化版本，代理加载时检查版本兼容性。如果技能依赖某个特定版本的Claude Code或某个脚本运行时，在元数据里声明，避免不兼容导致执行失败。

6.3 用技能沉淀团队最佳实践

技能最大的价值，我觉得是把团队里“老手才知道的坑”固化下来。比如我们项目里有个约定：所有数据库查询必须走一个封装层，不能直接调ORM。这个约定以前只存在于文档和口口相传中，新人经常忘。后来我把它写进“新增查询”技能的指令里，代理每次生成查询代码都会自动走封装层。新人用代理时，自然就遵循了规范。这比写十页文档都管用。所以我的建议是：每当你发现自己在重复提醒代理某件事，就把它做成技能。

6.4 技能与测试驱动开发的深度结合

最后再展开说一下TDD。agent-skills加TDD，本质上是在给代理建立反馈回路。没有反馈回路，代理只能靠“感觉”判断自己做对了没有，这在复杂任务上极不可靠。有了测试，代理每改一次代码就能得到客观信号。我现在的做法是：技能指令里强制要求“先运行测试确认失败，再实现，再运行测试确认通过”。这个“红-绿”循环，代理执行起来很自然，而且能有效防止它跳过验证。实测下来，带TDD闭环的技能，产出代码的一次通过率能到八成以上，不带的话可能只有五成。这个差距，在每天几十次调用的场景下，累积起来非常可观。

如果你刚开始接触agent-skills，我的建议是从一个小技能做起，比如“新增一个简单的工具函数并补测试”。跑通整个流程后，再逐步扩展。别一上来就搞大而全的技能体系，那样容易在细节里迷失。技能这东西，用起来才知道哪里需要调整，先跑起来比什么都重要。