企业官网建设流程全解析

1. 从“agent-skills”说起：为什么它值得单独拎出来聊

第一次看到agent-skills这个词，是在翻 Claude Code 相关生态的时候。当时我的第一反应是：这不就是把“提示词工程”换了个马甲吗？但真正上手用了一段时间、又自己动手拆过几个 skill 之后，我改变了看法。agent-skills本质上是一套给 AI coding agent 用的能力封装规范，它把过去散落在各个 prompt 模板、系统指令、项目约定里的“隐性经验”，变成了可复用、可版本管理、可被 CLI 直接调用的显式技能包。

说得再直白一点：以前你让 Claude Code 帮你写测试，你得在对话里反复叮嘱“先写测试、再写实现、跑一遍确认失败、再补实现”，每次开新会话都得重来一遍。现在你可以把这一整套流程固化成一个 skill，命名成test-driven-development，之后只要触发对应场景，agent 就自动按这套流程走。这就是agent-skills最核心的价值——把重复的、有固定套路的工程动作，沉淀成 agent 能直接调用的技能。

它解决的问题其实很具体：AI coding agent 能力很强，但“发挥不稳定”。同一个模型，你今天让它写代码它写得很好，明天同样的需求它可能就跳过了测试、忽略了边界条件。原因不是模型变笨了，而是上下文里缺少稳定的行为约束。agent-skills就是补上这一环的机制。配合skills CLI这类工具，你可以安装、列出、更新、卸载技能，像管理 npm 包一样管理 agent 的行为模式。

这篇文章适合谁看？三类人。第一类是把 Claude Code 当日常主力开发工具、想让它更“听话”的人；第二类是团队里负责统一 AI 编码规范、希望把团队约定固化下来的人；第三类是对 AI coding agent 底层机制好奇、想自己写 skill 的技术人。不管你是刚装完 Claude Code 的新手，还是已经用了一阵子但总觉得“差点意思”的老用户，下面这些内容应该都能对上你的需求。

2. agent-skills 的整体设计与思路拆解

2.1 它到底解决了什么痛点

要理解agent-skills的设计，得先理解 AI coding agent 的一个根本矛盾：通用性和确定性之间的拉扯。模型本身是通用的，你问它什么它都能答；但工程实践要求的是确定性，同一个任务每次都应该按同样的标准完成。这个矛盾在真实项目里会以各种形式冒出来。

我举个自己踩过的例子。有段时间我用 Claude Code 做一个 Node 项目，反复让它“加个接口”。前几次它很规范，会先看现有的路由结构、复用已有的中间件、补上参数校验。到第五六次的时候，它突然开始自己造一套新的错误处理格式，跟项目里原有的完全不一致。我回头翻对话才发现，是因为那次会话里我没提“遵循现有约定”，而前面的上下文又被压缩掉了。这种问题靠“每次多说一句”是治标不治本的，因为你不可能记住所有该叮嘱的点。

agent-skills的思路是把这些“该叮嘱的点”从对话里抽出来，变成独立的、有明确触发条件的技能单元。每个 skill 本质上是一份结构化的说明文档，告诉 agent：在什么场景下、应该按什么步骤、遵守什么约束、产出什么结果。它不依赖你每次手动提醒，而是由 agent 根据当前任务自动匹配和加载。

2.2 为什么是“技能”而不是“提示词”

这里有个关键的设计选择值得说清楚。很多人会问：我直接写个长 prompt 不就行了，为什么要搞成 skill？区别在于三个层面。

第一是触发机制。普通 prompt 需要你主动粘贴或者放在系统指令里，它是“常驻”的，会一直占用上下文。而 skill 是“按需加载”的，agent 判断当前任务需要某项技能时才把它拉进来，用完就释放。这对上下文窗口宝贵的 coding agent 来说非常重要。

第二是组织粒度。一个 skill 对应一个明确的能力边界，比如“写单元测试”“做代码审查”“处理数据库迁移”。这种粒度让技能可以被组合、被替换、被单独升级。你不可能把一个两万字的巨型 prompt 拆开维护，但你可以维护二十个各司其职的 skill。

第三是可分发性。skill 是文件，可以放进 git 仓库、可以通过 CLI 安装、可以团队共享。prompt 是文本，散落在聊天记录、笔记、文档里，很难形成工程化的资产管理。skills CLI的存在就是为了解决分发问题，让技能像依赖包一样可管理。

2.3 和 Claude Code 的关系

agent-skills不是 Claude Code 独有的，但它在 Claude Code 生态里体现得最明显。Claude Code 作为终端里的 AI coding agent，本身就支持通过配置文件、项目约定文件来约束行为。agent-skills是在这个基础上更进一步，把行为约束标准化、模块化。

实际使用中，你会看到 skill 通常以目录形式存在，每个目录里有一个描述文件（一般是 markdown 或特定格式的配置），说明这个技能的元信息、触发条件、执行步骤。Claude Code 在运行时扫描这些技能，根据当前任务上下文决定加载哪些。这套机制让“让 agent 按我的方式干活”这件事，从玄学变成了可配置的工程问题。

提示：不要把 skill 理解成“更长的系统提示”。它的核心是条件触发 + 结构化步骤，写 skill 时最重要的不是把话说得多全，而是把触发条件和执行边界划清楚。

3. 核心细节解析与实操要点

3.1 一个 skill 的典型结构长什么样

虽然不同实现细节有差异，但一个可用的 skill 通常包含几个必备部分。我用一个test-driven-development技能来举例说明，因为这是热词里出现频率最高的场景之一，也是最容易看出 skill 价值的场景。

一个 TDD skill 大致需要包含这些信息：技能名称和描述（让 agent 知道这是干什么的）、触发条件（什么情况下该用这个技能，比如“用户要求新增功能”或“用户要求修复 bug”）、执行步骤（先写失败测试、再写最小实现、再重构、再验证）、约束条件（比如“测试必须先于实现”“每次只处理一个断言”“不允许跳过失败验证”）、产出要求（测试文件位置、命名规范、覆盖率要求）。

把这些写清楚之后，agent 在遇到“帮我加个功能”这类请求时，就会自动套用这套流程，而不是直接上来就写实现代码。这就是 skill 相对普通 prompt 的优势——它把“怎么做”固化下来了。

3.2 触发条件的设计是成败关键

我见过很多人写 skill 失败，问题几乎都出在触发条件上。要么写得太宽泛，导致 agent 在不该用的时候也加载，干扰正常任务；要么写得太窄，实际根本触发不了。

好的触发条件应该描述任务意图而不是具体关键词。比如“当用户要求实现新功能或修改现有行为时”就比“当用户说‘加个功能’时”要好，因为后者只能匹配特定措辞。同时要给出排除条件，比如“当用户只是询问概念、不涉及代码改动时，不触发此技能”。这种正反两面的界定能大幅提升触发准确率。

还有一个实操心得：触发条件里最好带上优先级或冲突处理。如果两个 skill 的触发条件重叠了怎么办？比如“代码审查”和“重构”可能同时匹配一个任务。这时候需要在 skill 里说明优先级，或者让 agent 按顺序执行。这个细节很多人会忽略，但在技能多了之后会变成大问题。

3.3 步骤描述要“可执行”而非“可理解”

写 skill 最容易犯的错，是用人类读起来很顺、但 agent 执行起来很模糊的语言。比如“确保代码质量”这种话，人看了知道大概意思，agent 看了不知道具体做什么。好的步骤描述应该是动作 + 对象 + 判定标准。

对比一下：

• 模糊版：“写好测试后运行验证。”
• 可执行版：“运行测试命令，确认新测试失败且失败原因与预期一致；若测试直接通过，说明测试未覆盖目标行为，需重写测试。”

后者把“验证”这个动作拆成了可判断的分支，agent 执行时不会含糊。这个原则贯穿整个 skill 编写过程——凡是需要 agent 做判断的地方，都要给出明确的判定依据。

3.4 用 skills CLI 管理技能包

skills CLI是配套的工具，用来安装、查看、更新技能。它的使用逻辑跟包管理器很像。常见操作包括：列出当前可用的技能、安装某个技能到项目或全局、查看某个技能的详情、更新到最新版本、卸载不再需要的技能。

实操中我建议项目级技能和全局技能分开管理。项目级技能放在项目目录下，跟着代码走，团队成员拉下来就有一致的 agent 行为；全局技能放在用户目录下，是你个人的通用习惯，比如“我总是希望代码注释用中文”。这样区分之后，换项目时不会把上个项目的特殊约定带过去，团队协作时也不会因为个人偏好污染项目规范。

注意：安装第三方 skill 之前一定要读一遍它的内容。skill 会直接影响 agent 的行为，一个写得不好的 skill 可能让 agent 做出你不期望的操作。把它当成要引入项目的依赖来对待，该审的审，该锁版本的锁版本。

4. 实操过程与核心环节实现

4.1 环境准备：先把 Claude Code 跑起来

要玩agent-skills，前提是有一个能用的 AI coding agent 环境。以 Claude Code 为例，安装方式根据系统不同有差异。macOS 和 Ubuntu 上的安装流程大同小异，核心是确保运行环境里有合适的 Node 版本，然后通过官方提供的安装方式把 CLI 装好。装完之后用claude命令启动，首次使用需要完成账号相关的初始化流程。

这里有个常见疑问：不注册账号能不能用其他模型？实际操作中，Claude Code 支持通过配置接入第三方模型服务，包括一些国内可访问的模型。配置方式通常是在设置文件里指定 API 端点和密钥。这个环节的细节建议直接参考官方文档，因为接口格式和配置项会随版本变化。我自己的经验是，先把默认配置跑通，再折腾第三方接入，否则出问题时很难判断是环境问题还是配置问题。

VS Code 用户还可以装对应的插件，在编辑器里直接调用。插件配置的核心是让编辑器知道 CLI 的路径和启动参数。Ubuntu 环境下如果遇到权限或路径问题，检查一下 shell 的 PATH 配置通常能解决。

4.2 写第一个 skill：从 TDD 开始

环境就绪后，我们来实际写一个 skill。选 TDD 作为第一个，是因为它的流程足够清晰，容易验证效果。

第一步，确定 skill 的存放位置。项目级的话，在项目根目录下建一个约定的技能目录。第二步，创建技能描述文件，按前面说的结构填入名称、描述、触发条件、步骤、约束。第三步，写完后在 Claude Code 里触发一次，观察它是否按预期加载并执行。

我实际写的时候，TDD skill 的步骤是这么组织的：

1. 接收功能需求后，先不写实现代码，而是分析需求涉及的输入、输出、边界情况。
2. 为每个边界情况写一个测试用例，测试文件放在项目约定的测试目录下。
3. 运行测试，确认所有新测试都失败，且失败原因是“功能未实现”而非“测试本身有语法错误”。
4. 编写能通过测试的最小实现，不追求优雅，只追求通过。
5. 再次运行测试，确认全部通过。
6. 在测试保护下重构实现代码，每次重构后重跑测试。
7. 输出变更摘要，包括新增测试数、实现文件、覆盖率变化。

这套步骤写进 skill 之后，我特意测试了几次。第一次让它“加一个邮箱格式校验函数”，它确实先写了测试，跑出失败，再写实现。第二次我故意说“快点，直接写实现”，它仍然坚持先写测试，因为 skill 里的约束明确写了“测试必须先于实现”。这就是 skill 的价值——它让 agent 在你想偷懒的时候替你守住纪律。

4.3 参数与判定标准的量化

写 skill 时，凡是能量化的地方尽量量化。比如“测试覆盖率”这种要求，如果只写“保持较高覆盖率”，agent 没法判断。写成“新增代码行覆盖率不低于 80%，分支覆盖率不低于 70%”就可执行了。再比如“代码审查”技能里，“检查函数长度”可以量化为“单个函数不超过 50 行，超过则建议拆分”。

量化的好处是让 agent 的产出有明确的验收标准，也方便你在 skill 迭代时判断效果。我一般会在 skill 里放一个简单的检查清单，agent 执行完主要步骤后逐项自检。这个自检环节能显著减少“看起来做了但没做到位”的情况。

4.4 技能的组合与编排

单个 skill 用顺了之后，自然会想组合。比如一个完整的“新增 API 接口”任务，可能涉及“TDD 写测试”“数据库迁移”“接口文档更新”三个技能。这时候有两种编排方式：一种是让 agent 根据任务自动匹配多个技能并按依赖顺序执行；另一种是写一个上层 skill，显式调用下层技能。

我倾向于后者，因为显式编排更可控。上层 skill 里写清楚“先执行数据库迁移技能，再执行 TDD 技能，最后执行文档技能”，agent 就按这个顺序走。自动匹配虽然省事，但技能多了之后容易出现顺序错乱或遗漏。可控性优先于自动化，这是我踩过几次坑之后的结论。

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

5.1 技能不触发怎么办

这是最高频的问题。技能写好了，但 agent 该用的时候没用。排查思路按顺序来：先确认技能文件放在 agent 会扫描的目录下，路径错了后面都白搭；再检查触发条件的描述是否过于具体，导致实际任务匹配不上；然后看是不是有另一个技能的触发条件更宽泛，把任务“抢”走了。

我遇到过一次，TDD 技能死活不触发，最后发现是另一个“快速实现”技能的条件写成了“任何涉及代码修改的任务”，优先级还更高。把那个技能的条件收窄之后，TDD 就正常了。所以技能之间的触发条件要互相避让，这是设计时就要考虑的事。

5.2 技能触发了但执行走样

有时候技能加载了，但 agent 执行到一半就偏离了。常见原因是步骤描述里有歧义，或者约束条件不够硬。比如“尽量先写测试”里的“尽量”就是软约束，agent 可能理解为“可以不做”。改成“必须先写测试，未写测试前不得修改实现文件”就硬多了。

另一个原因是上下文太长，skill 的内容被挤到了后面，agent 注意力下降。这时候可以考虑把 skill 拆小，或者把最关键的约束放在 skill 描述的开头。重要的约束前置，这是个很实用的技巧。

5.3 多个技能冲突

技能冲突的表现是 agent 行为前后矛盾，或者反复横跳。根源通常是两个技能的约束互相打架。比如一个技能要求“所有函数必须有注释”，另一个要求“代码保持简洁，避免冗余注释”。这种冲突需要在设计层面解决，要么合并技能，要么明确优先级。

我的做法是维护一个技能清单，定期检查触发条件和约束是否有重叠。技能数量控制在十个以内比较好维护，超过之后冲突概率明显上升。

5.4 常见问题速查表

5.5 几个独家避坑技巧

第一，新写的 skill 先在沙盒项目里试，别直接上生产项目。skill 的行为影响面比你想的大，一个措辞不当可能让 agent 在关键任务上做出奇怪操作。

第二，给 skill 写版本号和变更记录。技能是会迭代的，没有版本管理的话，某天发现行为变了都不知道是哪次改动导致的。

第三，定期清理不再用的 skill。技能堆积不仅增加冲突概率，还会拖慢 agent 的匹配过程。我一般每个月过一遍，把三个月没用过的删掉或归档。

第四，团队共享的 skill 要配文档。光有 skill 文件不够，得说明它解决什么问题、什么时候该用、有什么已知限制。不然新人看到一堆技能目录会懵。

6. 技能生态的延展与个人实践体会

agent-skills这套机制真正有意思的地方，在于它把“怎么和 AI 协作”这件事从个人经验变成了可积累的资产。以前你用 AI 写代码，用得好不好全看个人会不会提问；现在你可以把好的协作方式固化成技能，让它稳定复现，还能分享给别人。

我自己的技能库现在有十几个，覆盖测试、审查、重构、文档、迁移这些高频场景。最明显的变化是，我不再需要每次开新会话都重新“调教”agent，它一上来就按我习惯的方式干活。这种一致性带来的效率提升，比单纯追求模型能力提升要实在得多。

往后看，技能生态大概率会往两个方向走：一是标准化，出现通用的技能格式和分发渠道，让技能能跨不同的 agent 平台使用；二是组合化，单个技能解决单点问题，多个技能编排解决复杂工作流。现在已经有这个苗头了，skills CLI这类工具就是在往标准化方向走。

如果你还没开始写自己的 skill，我的建议是从一个你每天都要重复叮嘱 agent 的动作开始。把它写下来，跑通，再迭代。不用追求一次写完美，技能这东西是越用越顺的。我第一个 TDD 技能改了七八版才稳定，但改的过程本身就是对“我到底希望 AI 怎么帮我干活”的一次梳理，这个收获比技能本身还值。