企业官网建设流程全解析

1. 从"每次都要重新教AI"说起：agent-skills到底在解决什么

如果你最近半年一直在用 Claude Code、Cursor 这类 AI coding agent 干活，大概率经历过一种很具体的疲惫：同一个项目里，你反复告诉它"这个仓库用 pnpm 不用 npm""提交信息要遵循 Conventional Commits""测试文件必须放在__tests__目录下""别动legacy/里的代码"。每次开新会话，这些上下文就像被格式化了一样消失，你得从头再讲一遍。

agent-skills这个项目，本质上就是冲着这个痛点去的。它想做的事情可以用一句话概括：把"你希望 AI agent 怎么干活"这件事，从每次对话里的口头交代，变成一份可复用、可版本管理、可被 agent 自动加载的技能包。

我最初接触这个概念的时候，第一反应是"这不就是 prompt 模板吗"。但真正用下来会发现，它和随手存一段 prompt 有本质区别。prompt 模板是"你复制粘贴给 AI 的一段话"，而 skill 是"agent 在特定场景下会主动识别并加载的一套行为规范"。前者靠人记得去用，后者靠机制保证被用上。这个差别听起来小，实际体验差得很远。

关键词里出现的skills CLI、Claude Code、Cursor，其实指向了同一件事：主流 AI coding agent 都在往"可扩展技能"这个方向走。Claude Code 有它的 skills 机制，Cursor 有 rules 和 agent 配置，各家叫法不同，但底层逻辑是一致的——让 agent 的能力边界从"模型本身会什么"扩展到"你教会它什么"。

这篇文章适合谁看？三类人。第一类是完全没接触过 agent skills、想知道这东西值不值得投入时间的新手；第二类是已经在用 Claude Code 或 Cursor、但还停留在"每次手动喂上下文"阶段的用户；第三类是团队里负责统一 AI 编码规范的人，你们可能正在纠结要不要把 skills 纳入工程化流程。我会从概念、目录结构、安装配置、实际编写、踩坑经验几个层面把它讲透，尽量做到你看完就能上手。

需要先说明一点：agent-skills这个标题本身比较宽泛，项目正文和关键词都是空的，所以下面的内容是我基于当前 AI coding agent 生态里 skills 机制的通用实践来展开的，涉及具体命令和路径的地方，我会标注清楚哪些是通用逻辑、哪些是特定工具的约定，你按自己实际用的工具对照着看。

2. 拆开一个 skill 看内部：它凭什么比一段 prompt 更管用

2.1 skill 的三层结构：元数据、触发条件、执行指令

要理解 skill 为什么有效，得先看它的内部构造。一个设计良好的 skill，通常包含三个层次，缺一不可。

最外层是元数据（metadata），一般写在文件头部的 frontmatter 里，包含 name、description 这类字段。这一层的作用是让 agent 在"还没读全文"的时候就能判断"这个 skill 跟我当前的任务有没有关系"。你可以把它理解成书的封面和目录——agent 先扫一遍所有 skill 的元数据，决定要不要翻开哪一本。

中间层是触发条件（trigger）。这是最容易被新手忽略、但恰恰最关键的部分。触发条件描述的是"什么情况下应该加载这个 skill"。比如一个处理数据库迁移的 skill，触发条件可能是"用户提到 migration、schema change、ALTER TABLE 等关键词，或者当前工作目录下存在 migrations 文件夹"。写得好的触发条件，能让 agent 在正确的时机自动想起这个 skill；写得模糊的触发条件，要么永远不触发，要么在不该触发的时候乱触发。

最内层是执行指令（instructions），也就是你真正想教给 agent 的那套行为规范。这部分可以很长，可以包含步骤、示例、反例、注意事项。因为只有触发之后才会被加载进上下文，所以它不会像常驻 prompt 那样一直占用 token。

这三层结构带来的直接好处是按需加载。假设你给项目配了 20 个 skill，agent 平时只需要扫 20 条元数据（可能就几百 token），只有真正相关的那个才会被完整读进来。这比把所有规范塞进一个巨大的 system prompt 要经济得多，也更不容易让模型"注意力涣散"。

2.2 为什么"自动触发"比"手动引用"更可靠

我见过不少人把 skill 当成"高级版 prompt 收藏夹"用——写好了放在那儿，需要的时候手动@一下。这么用不是不行，但浪费了 skill 机制最大的价值。

手动引用的根本问题是依赖人的记忆。你在赶进度的时候，很容易忘记"哦对，我有个 skill 是管提交信息的"。而自动触发把这份记忆外包给了 agent 本身。只要触发条件写对了，agent 在遇到相关任务时会自己去查有没有对应的 skill。

这里有个反直觉的点：触发条件写得越具体，自动触发反而越可靠。新手常犯的错误是触发条件写得太宽，比如"处理任何代码相关任务时加载"。这种写法等于没写，因为几乎所有任务都符合，agent 要么每次都加载（浪费上下文），要么干脆忽略（因为区分度太低）。正确的做法是往具体里写：涉及的文件类型、出现的命令、任务的动词，越具体越好。

2.3 skill 和 rules、memory、prompt 模板的边界在哪

生态里这几个概念经常被混着用，我按自己的理解理一下边界，方便你对号入座。

简单说，rules 是"永远生效的底线"，skill 是"特定场景才生效的说明书"。比如"所有代码用 2 空格缩进"适合放 rules，因为它任何时候都成立；而"如何新增一个 API endpoint"更适合做成 skill，因为只有做这件事的时候才需要那一长串步骤。

memory 则更偏向"事实性信息"，比如"这个项目的测试框架是 Vitest"。它不教 agent 怎么做，只是告诉 agent 现状是什么。三者配合使用效果最好，但别指望用一个替代另一个。

3. 目录结构与文件约定：skill 到底该放在哪

3.1 全局 skill 与项目级 skill 的分工

skill 的存放位置决定了它的作用范围，这是配置时第一个要做的决策。通常分两级：

全局 skill放在用户主目录下的配置文件夹里，对所有项目生效。适合放那些"我这个人干活一贯如此"的规范，比如个人偏好的代码风格、常用的提交信息格式、你习惯的调试流程。全局 skill 的好处是不用每个项目重复配置，坏处是它不知道具体项目的上下文，写的时候要更通用。

项目级 skill放在项目仓库里，跟着代码一起版本管理。适合放"这个项目特有的规矩"，比如这个仓库的目录约定、特定的构建命令、团队约定的 PR 流程。项目级 skill 的最大优势是可以随代码 review——新人 clone 下来就自带全套规范，团队成员的 agent 行为天然一致。

我的建议是：个人习惯放全局，团队约定放项目级。两者有冲突时，项目级优先，因为项目级更贴近当前任务的实际上下文。

3.2 一个典型 skill 目录长什么样

不同工具的目录约定不完全一样，但结构大同小异。下面是一个通用的组织方式，你可以对照自己用的工具调整：

skills/ ├── commit-message/ │ └── SKILL.md ├── api-endpoint/ │ ├── SKILL.md │ └── templates/ │ └── endpoint.ts ├── db-migration/ │ └── SKILL.md └── code-review/ └── SKILL.md

每个 skill 一个文件夹，主文件通常叫SKILL.md（有些工具用skill.md或index.md，看具体约定）。文件夹名就是 skill 的标识，尽量用短横线连接的英文小写，别用中文和空格，避免路径解析出问题。

如果 skill 需要附带模板文件、示例代码、脚本，就放在同一个文件夹下的子目录里。这样 skill 是自包含的，迁移和分享都方便。我见过有人把模板散落在项目各处，结果 skill 一换项目就找不到文件了，这种坑完全可以避免。

3.3 SKILL.md 的头部字段怎么写才不踩坑

头部元数据是 agent 决定"要不要读这个 skill"的唯一依据，值得多花点心思。一个典型的头部大概长这样：

--- name: commit-message description: 生成符合 Conventional Commits 规范的提交信息，适用于本仓库所有 git commit 操作 trigger: 当用户要求提交代码、生成 commit message，或执行 git commit 时 ---

几个实操要点：

name用英文小写加短横线，和文件夹名保持一致，别整花活。description要写清楚"这个 skill 干什么"和"什么时候用"，一句话讲明白，因为 agent 主要靠它做初筛。trigger字段不是所有工具都支持，如果你的工具没有这个字段，就把触发条件写进 description 里。

注意：description 里别写"这是一个非常有用的 skill"这种自夸的话，agent 不看你夸得好不好，只看关键词匹配。把精力放在把场景描述准确上。

还有一个容易忽略的点：description 里要包含用户可能说的原话。比如用户可能说"帮我提交一下""commit 一下""生成提交信息"，这些说法都该在 description 或 trigger 里出现，提高匹配率。

4. 从零装好第一个 skill：安装、配置与验证

4.1 安装前的环境确认

在动手之前，先确认你的 agent 工具版本支持 skills 机制。这个很重要，因为 skills 是比较新的特性，老版本可能压根不认这个目录。

如果你用的是 Claude Code，先在终端里跑一下版本命令确认版本号，然后查一下官方文档里 skills 相关的说明，确认当前版本是否支持。如果你用的是 Cursor，skills 相关的功能可能叫别的名字（比如 rules、agent 配置），需要先搞清楚它对应的是哪套机制。

关键词里提到的skills CLI，指的应该是管理 skill 的命令行工具。这类工具通常提供init、list、install、remove这类子命令，用来创建、查看、安装、卸载 skill。具体命令名各工具不同，但思路一致：用 CLI 管理比手动建文件夹可靠，因为 CLI 会帮你处理路径、权限、格式校验这些琐事。

4.2 用 CLI 初始化一个 skill 的完整流程

假设你的工具提供了 skills CLI，典型流程是这样的：

# 查看当前已安装的 skill skills list # 在项目里初始化一个新的 skill skills init commit-message # 这会在约定目录下生成一个带模板的 SKILL.md # 编辑它，填入你的规范

如果工具没有 CLI，手动创建也行，但要严格遵循目录约定。手动创建时最容易出错的地方是路径层级——多一层少一层都可能导致 agent 扫不到。建议先手动建一个，用list命令验证能被识别，再批量创建。

初始化之后，先别急着写复杂内容。先写一个最小可用的 skill，跑通"能被识别、能被触发"这个链路，再往里加内容。我见过太多人一上来就写几百行规范，结果发现根本没被加载，白忙活。

4.3 怎么验证 skill 真的被加载了

验证是新手最容易跳过、但绝对不能跳过的一步。方法有几种，从简单到复杂：

方法一：看 agent 的加载日志。很多工具在加载 skill 时会打印日志，或者在响应里标注"已加载 skill: xxx"。跑一个能触发该 skill 的任务，看有没有这条提示。

方法二：故意在 skill 里放一个"暗号"。比如在 skill 里写"生成提交信息时，开头加上[SKILL-ACTIVE]标记"。然后让 agent 提交一次，看输出里有没有这个标记。有，说明加载成功；没有，说明触发条件没匹配上。

方法三：对比测试。同一个任务，一次在配了 skill 的环境跑，一次在没配的环境跑，对比输出差异。这个方法最直观，但比较费时间。

我一般用方法二，快且明确。如果暗号没出现，就去检查触发条件——十有八九是关键词没覆盖到用户的实际说法。

4.4 触发失败的常见原因排查

触发失败是最高频的问题，我整理了一个排查顺序，按这个顺序查基本能定位：

按这个表从上往下查，大部分问题五分钟内能解决。如果全查完还是不触发，那就去看工具的官方文档，确认它的 skills 机制有没有特殊要求。

5. 写出一个真正好用的 skill：内容编排的实战心得

5.1 指令部分要"像给新人写交接文档"

skill 的执行指令部分，最忌讳写成"官方规范摘抄"。你想想，一个新人入职，你给他一份满是"应当""须""严禁"的规范文档，他看得进去吗？agent 也一样。

好的 skill 指令，读起来应该像一个老员工在给新人讲这个活儿怎么干。具体来说：

先讲目标——这个 skill 要达成什么结果。再讲步骤——按顺序该做哪几件事。然后给示例——一个完整的、正确的例子。最后讲边界——什么情况下不该用这个 skill，或者要特别小心什么。

举个例子，一个"新增 API endpoint"的 skill，与其写"endpoint 命名须遵循 RESTful 规范"，不如写"新增 endpoint 时，先看src/api/下已有的文件，照着最相似的那个改。命名用复数名词，比如/users而不是/user。改完记得在src/api/index.ts里注册路由，这一步最容易漏。"

后者信息量更大，也更不容易被误读。

5.2 用"反例"比用"正例"更能约束行为

这是个反直觉但很有效的技巧。只给正例，agent 知道"应该这样做"，但不知道"做到什么程度算过头"。加上反例，边界就清晰了。

比如教 agent 写提交信息，正例是feat: add user login，反例可以写"不要写成feat: 添加了用户登录功能，包括前端页面和后端接口以及数据库改动——提交信息标题控制在 50 字符内，详细说明放正文"。

反例的作用是划出禁区。模型在生成时，如果发现自己的输出接近反例，会自动往正例方向调整。这比单纯说"要简洁"有效得多。

5.3 控制 skill 长度：什么时候该拆成两个

skill 不是越长越好。一个 skill 如果超过几百行，就要考虑拆分了。判断标准很简单：如果这个 skill 里有两块内容，它们的触发场景明显不同，就该拆。

比如一个"数据库操作"skill，如果它同时管"新增迁移"和"查询优化"，这两件事的触发场景完全不同——前者在改 schema 时触发，后者在排查慢查询时触发。硬塞在一起，会导致每次触发都加载一堆无关内容。

拆分的另一个好处是可维护性。skill 短了，改起来不容易误伤。我一般把单个 skill 控制在 100 到 200 行之间，超过就看看能不能拆。

5.4 把团队约定沉淀进 skill 的正确姿势

如果你是团队里负责统一规范的人，skill 是个很好的载体，但用法有讲究。

别把 skill 当成规范文档的搬运工。团队 wiki 上那份 5000 字的编码规范，直接复制进 skill 是没用的，因为太长、太泛、触发条件不明确。正确做法是按场景拆分：把"提交规范"拆成一个 skill，"代码 review 检查项"拆成另一个，"发布流程"再拆一个。每个 skill 只解决一个具体场景的问题。

让 skill 跟着代码走。项目级 skill 放进仓库，改规范的时候顺手改 skill，review 的时候一起看。这样能保证 skill 和实际代码规范不脱节。我见过团队把 skill 放在共享网盘里，结果半年后没人记得更新，agent 还在按老规范干活。

给 skill 加个 owner。每个 skill 在头部或注释里标注负责人，出问题知道找谁。这个习惯在 skill 数量多起来之后特别有用。

6. 那些文档不会告诉你的坑：我的踩坑记录

6.1 触发条件写太宽，导致 skill 互相打架

我最早配 skill 的时候，给一个"代码审查"skill 写的触发条件是"审查代码时"。结果发现，只要我让 agent 看任何代码，它都会加载这个 skill，然后开始输出一堆审查意见——哪怕我只是想让它解释一下某段代码在干嘛。

问题出在"审查"这个词太宽。后来我改成"当用户明确要求 review、审查、检查代码质量，或提到 PR、pull request 时"，误触发就少多了。

教训：触发条件要匹配"用户的意图"，而不是"任务涉及的领域"。用户看代码不一定是想审查，可能只是想理解。这两者要区分开。

6.2 skill 里的路径写死，换台机器就崩

这个坑很隐蔽。我在 skill 里写了"模板文件在/Users/myname/projects/xxx/templates/"，本地跑得好好的，同事 clone 下来直接报错——他的用户名不一样，路径根本不存在。

正确做法是用相对路径，或者用工具提供的变量。大多数 skill 机制支持引用 skill 自身所在目录，比如用相对于 SKILL.md 的路径。这样 skill 跟着文件夹走，换谁用都不会崩。

如果非要引用项目根目录，也要用相对于项目根的路径，而不是绝对路径。这个习惯能省掉大量"在我机器上能跑"的扯皮。

6.3 更新 skill 后 agent 还在用旧版本

skill 改了，但 agent 行为没变，这是缓存问题。有些工具会缓存 skill 内容，改完需要重启会话或者手动刷新。

排查方法：在 skill 里加一行明显的标记（比如版本号），改完看 agent 输出里是不是新版本号。如果不是，就是缓存没刷新。解决办法通常是重启 agent 会话，或者跑一下工具的刷新命令。

养成习惯：改完 skill 先验证一次再继续干活。别改完就闷头写代码，等发现行为不对再回头查，浪费时间。

6.4 多个 skill 同时触发时的优先级混乱

当项目级和全局都有相关 skill 时，agent 可能同时加载两个，然后行为变得很奇怪——一会儿按这个规范，一会儿按那个。

解决办法是在 skill 里显式声明优先级，或者干脆避免重复。我的做法是：项目级 skill 里明确写"本 skill 优先于全局同名 skill"，全局 skill 里则写"如果项目里有对应 skill，以项目级为准"。虽然有点啰嗦，但能避免很多混乱。

如果工具支持优先级配置，那就用配置解决，比在内容里写更可靠。

6.5 把敏感信息写进 skill

这个必须单独拎出来说。skill 是会被版本管理的，如果你在里面写了 API key、内部地址、账号密码，等于把这些信息提交到了仓库里。

skill 里只放"怎么做"，不放"用什么凭证"。需要凭证的地方，让 agent 去读环境变量或者本地配置文件，这些文件应该在.gitignore里。这个原则和写代码是一样的，别因为 skill 看起来像文档就放松警惕。

7. 让 skill 真正融入日常：一些进阶用法

7.1 用 skill 固化"重复性排查流程"

除了编码规范，skill 还能用来固化排查流程。比如"线上报错排查"这个场景，步骤往往是固定的：先看日志、再查监控、然后定位最近改动、最后回滚或修复。这套流程完全可以写成一个 skill。

好处是，当你半夜被叫起来处理故障、脑子不太清醒的时候，agent 能按 skill 里的步骤一步步引导你，不至于漏掉关键环节。这种"流程型 skill"的价值，在压力场景下特别明显。

7.2 skill 与测试、CI 的配合

skill 不只能约束 agent 写代码，还能约束它跑测试。比如一个"提交前检查"skill，可以规定"提交前必须跑pnpm test和pnpm lint，都通过才能提交"。

更进一步，如果 CI 里也有对应的检查，skill 就相当于把 CI 的门槛前移到了本地。agent 在提交前就帮你把问题拦住了，省得推上去被 CI 打回来。这个用法我强烈推荐，尤其是团队协作的项目。

7.3 把 skill 当成团队知识传承的载体

老员工离职，他脑子里那套"这个项目该怎么改"的经验，往往就流失了。skill 是个不错的沉淀方式——把老员工的操作习惯、注意事项、踩过的坑，写成 skill 留在仓库里。

新人入职，clone 下来，agent 就自带这套经验。虽然不能完全替代手把手带，但至少能让新人少踩一些明显的坑。这个价值，随着团队规模变大、人员流动变快，会越来越明显。

7.4 定期清理不再适用的 skill

skill 也会过时。项目重构了、技术栈换了、规范更新了，对应的 skill 如果没跟着改，就会变成"误导 agent 的噪音"。

我的习惯是每个季度过一遍 skill 列表，问三个问题：这个 skill 还在用吗？触发条件还准确吗？内容还符合当前实践吗？三个问题有一个答不上来，就去改或者删。

宁可少几个 skill，也不要留一堆过时的。过时的 skill 比没有 skill 更糟，因为它会让 agent 按错误的方式干活，而且你还不知道。

8. 关于 agent-skills 这件事，我自己的几点体会

用了一段时间 skill 机制之后，我最大的感受是：它改变的不是 agent 的能力上限，而是 agent 行为的稳定性。

模型本身很聪明，你临时给它讲一遍规范，它也能照做。但问题是，它每次都要重新理解一遍，理解的结果还不一定一致。skill 的价值在于把"理解"这一步固化了——规范写一次，之后每次都是同一套，输出自然就稳定了。

另一个体会是，写 skill 的过程，其实是在逼自己把模糊的经验说清楚。很多规范我们平时是"心里知道但说不出来"的，写 skill 的时候必须把它变成明确的文字，这个过程本身就有价值。我写完几个 skill 之后，发现自己对项目的理解都清晰了不少。

最后分享一个小技巧：刚开始别追求完美，先写一个粗糙的版本用起来，用着用着再改。我第一个 skill 写得挺烂的，触发条件也不准，但用了一周之后，我大概知道哪里该改了。skill 这东西是迭代出来的，不是一次设计出来的。你要是等想清楚了再写，可能永远写不出来。

如果你现在还没开始用 skill，建议从最小的一个场景入手——比如就管提交信息这一件事。跑通了，你自然就知道怎么扩展到其他场景了。