企业官网建设流程全解析

1. 从"每次都要重新解释一遍"说起：agent-skills 到底想解决什么

如果你已经在日常开发里用上了 AI coding agent，不管是 Claude Code、Cursor 还是别的什么工具，大概率都经历过这样一个阶段：一开始觉得挺惊艳，用着用着就开始烦躁。烦躁的点不在于模型不够聪明，而在于每次开一个新会话，它就像失忆了一样——你上周刚跟它讲清楚的项目规范、代码风格、目录约定、提交信息格式，这周它又忘得一干二净，你还得从头再讲一遍。

agent-skills这个项目，本质上就是冲着这个痛点去的。它想做的事情，用一句话概括：把那些你反复对 AI agent 说的话，沉淀成可复用、可版本管理、可跨工具共享的"技能包"。你写一次，之后所有支持这套约定的 agent 都能直接读取并遵循。

这里要先厘清一个容易混淆的概念。很多人第一次听到 "agent skills" 会以为是某种插件市场，或者像浏览器扩展那样点一下安装就完事。其实不是。它更接近一套约定俗成的目录结构和文件格式，配合一个skillsCLI 来做安装、分发和管理。核心载体是纯文本（通常是 Markdown），所以它天然对版本控制友好，也天然跨工具——只要某个 agent 愿意读这个目录，它就能用上这些技能。

那它具体能做什么？我把它拆成三层价值来看：

• 第一层，消除重复沟通成本。项目里那些"只可意会"的约定，比如"我们的 React 组件一律用函数式 + hooks，禁止 class 组件""API 错误码统一走AppError封装""提交信息遵循 Conventional Commits"，全部写进 skill 文件，agent 每次启动自动加载。
• 第二层，把个人经验变成团队资产。老员工脑子里那套"这个模块改之前先看哪几个文件""这个服务的部署有个隐藏的坑"，以前只能靠口口相传，现在可以固化成 skill，新人（以及新会话里的 agent）直接继承。
• 第三层，跨工具复用。这是我觉得最有意思的地方。你在 Claude Code 里调教好的一套技能，理论上可以原样搬到 Cursor 或者别的支持该约定的工具里，不用重写。

适合谁来参考这篇内容？三类人最值得往下看：一是已经在用 AI coding agent、但还没系统化管理过"给 agent 的指令"的开发者；二是团队里负责工程规范、想让 AI 辅助开发更可控的技术负责人；三是对 agent 工作流本身感兴趣、想理解"技能"这套抽象怎么落地的人。哪怕你现在只用 Cursor 的基础补全功能，理解这套思路对你后续升级工作流也有直接帮助。

下面我会从目录结构、CLI 用法、和具体工具的配合、以及我自己踩过的坑几个角度，把这件事讲透。

2. 拆开一个 skill 看内部：目录约定与文件格式的门道

要真正用好 agent-skills，第一步不是急着敲命令，而是先搞明白"一个 skill 长什么样"。因为这套东西的灵活性恰恰来自它的简单，而简单的东西如果不理解约定，很容易写出 agent 根本读不懂的文件。

2.1 一个 skill 的最小构成

从常见实践来看，一个 skill 通常是一个独立目录，目录名就是技能标识（一般用 kebab-case，比如commit-convention、api-error-handling）。目录里最核心的是一个入口文件，通常是SKILL.md或者skill.md，这个文件承载了技能的元信息和主体内容。

一个典型的SKILL.md大致长这样：

--- name: commit-convention description: 规范 Git 提交信息的格式，遵循 Conventional Commits version: 1.0.0 tags: [git, workflow] --- # 提交信息规范 本项目所有提交信息必须遵循以下格式： <type>(<scope>): <subject> - type 取值：feat / fix / docs / refactor / test / chore - scope 为受影响模块名，可选 - subject 使用中文，不超过 50 字，结尾不加句号 示例： feat(auth): 增加手机号登录校验 fix(cart): 修复优惠券叠加计算错误

这里有几个细节值得单独拎出来说，因为它们直接决定 agent 能不能正确解析。

第一，frontmatter 不是装饰。顶部---包裹的那段 YAML，是给工具和 agent 用来做索引的。name和description尤其关键——很多 agent 在决定"要不要加载这个 skill"时，靠的就是 description 的语义匹配。description 写得含糊，比如只写"一些规范"，agent 很可能就忽略它了。我的经验是，description 要写成一句完整的、带场景的话，比如"当需要编写或修改 Git 提交信息时使用，规范提交格式"。

第二，正文要"可执行"，不要"可阅读"。这是新手最容易犯的错。很多人写 skill 像写文档，大段大段讲背景、讲历史、讲为什么。但 agent 读 skill 的目的是照着做，不是理解来龙去脉。所以正文应该尽量用祈使句、清单、示例，把"要做什么"和"不要做什么"写清楚。背景解释可以放，但要短，放在最后或者折叠起来。

第三，示例比规则更有约束力。我实测下来，给 agent 三五个正例和反例，比给它十条抽象规则管用得多。因为模型在生成时是模式匹配的，看到具体例子它会直接模仿。所以每个 skill 里，我都建议至少放一组"正确示例 / 错误示例"的对照。

2.2 目录里还能放什么

除了入口文件，一个 skill 目录通常还允许放辅助资源。常见的有：

• examples/目录：放更完整的代码示例文件，入口文件里用相对路径引用。
• templates/目录：放模板文件，比如新组件的脚手架模板。
• scripts/目录：放一些辅助脚本，某些工具支持在 skill 里定义可执行动作。
• README.md：给人看的说明，agent 一般不会读，但团队协作时有用。

这里有个坑我要提前说：不要假设所有 agent 都会递归读取子目录。有些实现只读入口文件，子目录里的内容需要你在入口文件里显式引用（比如"参考 examples/good.ts"），agent 才会去读。所以如果你把关键规则藏在子目录里却没在入口引用，很可能就白写了。

2.3 为什么用 Markdown 而不是 JSON/YAML

有人会问，既然是要给机器读的，为什么不用结构化格式？我的理解是这样：skill 的内容本质上是自然语言指令，而不是配置数据。配置数据适合结构化，但"提交信息用中文、不超过 50 字"这种规则，用 YAML 表达反而别扭，用自然语言最自然。而且 Markdown 对人类也友好，团队 review skill 变更时，diff 看起来清清楚楚，这点在协作场景里价值很大。

提示：如果你的 skill 里既有规则又有大量结构化数据（比如一张错误码对照表），可以把表格直接写在 Markdown 里，agent 对 Markdown 表格的解析能力普遍不错，没必要为了"结构化"硬拆成两个文件。

理解了单个 skill 的结构，接下来就可以看怎么把它们组织起来、分发出去，这就轮到skillsCLI 登场了。

3. skills CLI 的安装、组织与分发：把技能当成依赖来管

如果说 skill 文件是"内容"，那skillsCLI 就是"管道"。它负责把技能从某个来源安装到你的项目或全局环境，让你不用手动复制粘贴。这套思路其实很像 npm——技能就是包，CLI 就是包管理器。

3.1 安装与初始化

从常见实践看，skillsCLI 一般通过 Node 生态分发，所以前提是你机器上有可用的 Node 环境。安装命令大致是：

npm install -g skills-cli

装完之后，通常先做一次初始化，在项目里建立技能目录：

skills init

这一步会在项目根目录创建一个约定好的技能存放位置，常见的是.skills/或者.agent/skills/。具体路径取决于工具约定，但核心逻辑一致：有一个明确的、agent 会去扫描的目录。

初始化之后，你可以选择把技能装在项目级还是全局级：

• 项目级：技能跟着仓库走，团队成员 clone 下来就自动拥有。适合项目专属规范。
• 全局级：装在用户目录下，所有项目共享。适合个人通用偏好，比如"我总是希望注释用中文"。

我的建议是：项目强相关的规范一律项目级，个人风格偏好放全局级。混在一起会导致两个问题——项目规范被个人偏好污染，或者个人习惯被迫在每个项目里重复配置。

3.2 安装一个技能

安装单个技能的命令形态通常是：

skills add <skill-name> # 或者从某个来源安装 skills add <source> --skill <skill-name>

这里的<source>可以是本地路径、Git 仓库地址，或者某个技能集合。安装完成后，CLI 会把技能文件放到约定目录，并可能更新一个索引文件（比如skills.lock或manifest.json），记录装了哪些技能、什么版本。

这个索引文件很关键，它应该被提交到版本控制。这样团队里其他人拉下代码后，跑一条skills install就能把所有人的技能环境对齐，跟npm install是一个道理。

3.3 组织多个技能：分层与命名

当技能多起来之后，组织方式就变得重要了。我见过两种典型做法：

我个人的偏好是命名前缀 + 适度扁平。比如所有和 Git 相关的技能都叫git-*，所有和测试相关的叫test-*。这样既不用依赖目录递归，又能一眼看出归属。分类目录虽然好看，但前面说过，不是所有 agent 都递归扫描，风险更高。

3.4 分发：怎么让团队用上同一套技能

分发这件事，最朴素也最可靠的方式就是把技能目录提交进仓库。听起来很土，但它解决了 90% 的问题：版本可控、review 可做、回滚容易。

进阶一点的做法是维护一个内部技能仓库，把通用技能抽出来，各项目通过 CLI 从这个仓库拉取。这样规范升级时，改一处、全项目生效。但要注意版本锁定——如果技能仓库直接改主干，所有项目下次安装就变了，可能引入意外。所以内部仓库也应该打 tag、发版本，项目里锁定版本号。

注意：技能本质上是在给 agent 下达指令，所以它是有"权限"的。一个恶意或写错的技能，可能让 agent 做出你不期望的操作（比如自动执行某些命令）。团队分发技能时，一定要走 code review，别把技能当成无关紧要的文档。

CLI 这套东西讲完，接下来要面对一个更实际的问题：这些技能到底怎么和 Claude Code、Cursor 这些具体工具对接上。

4. 和 Claude Code、Cursor 对接：技能是怎么被"读进去"的

这是很多人最关心、也最容易迷糊的部分。技能文件写好了，CLI 也装了，但 agent 到底怎么知道要去读它们？不同工具的机制不一样，我分开说。

4.1 Claude Code 的加载逻辑

Claude Code 这类以 CLI 形态为主的 agent，通常有一个"项目上下文"的概念。它在启动时，会去扫描项目里约定的一些文件——比如CLAUDE.md、.claude/目录下的配置，以及技能目录。

从常见实践看，让 Claude Code 用上 agent-skills 的关键动作是：在它的项目配置文件里显式引用技能目录。比如在CLAUDE.md里写一句：

本项目使用 agent-skills 管理开发规范，技能位于 .skills/ 目录。 在处理任务前，请先阅读 .skills/ 下与当前任务相关的技能文件。

这句话看起来简单，但它解决了"agent 不知道技能存在"的问题。有些实现支持自动扫描，有些需要显式声明，显式声明是最稳的。

另外，Claude Code 的权限模型也值得提一句。技能里如果包含"执行某条命令"的指令，agent 在执行前通常会请求确认。这是好事，别嫌烦。我见过有人为了图省事把权限全开，结果 agent 在重构时顺手删了一批文件。技能是"建议"，权限是"闸门"，两者要分开看。

4.2 Cursor 的接入方式

Cursor 的机制不太一样。它更偏向 IDE 集成，上下文来源主要是打开的文件、@引用的内容，以及项目规则文件（比如.cursorrules或较新的 rules 配置）。

要让 Cursor 用上 agent-skills，常见做法有两种：

• 规则文件桥接：在.cursorrules里引用技能目录，或者直接把关键技能内容摘要进去。缺点是规则文件有长度限制，塞不下太多。
• 手动@引用：在对话里用@.skills/commit-convention/SKILL.md显式引用。优点是精准，缺点是每次都要手动。

我实测下来，混合用最舒服：把最核心、最高频的几条规范（比如代码风格、提交格式）摘要进规则文件，让它默认生效；把低频但重要的技能（比如某个复杂模块的改造指南）留在技能目录，需要时手动引用。

这里有个细节：Cursor 的规则文件对格式比较敏感，如果你从 skill 里复制内容过去，记得去掉 frontmatter，只保留正文，否则可能被当成普通文本干扰解析。

4.3 跨工具复用的现实与边界

"一次编写，到处使用"是 agent-skills 的理想，但现实里要打个折扣。不同工具对技能的理解能力、加载时机、上下文窗口都不一样。同一个 skill，在 Claude Code 里可能被完整加载，在 Cursor 里可能只被部分引用。

所以我的建议是：把技能写成"自包含、可独立阅读"的单元。也就是说，每个 skill 不依赖其他 skill 就能被理解。这样无论工具加载了哪几个，都不会出现"读了一半看不懂"的情况。跨工具复用的正确姿势不是"完全一致"，而是"核心规则一致，接入方式各随其便"。

工具对接讲清楚之后，我想聊聊更"软"但更有价值的部分——怎么写出真正管用的技能，以及我在这个过程里踩过的坑。

5. 写出"agent 真的会照做"的技能：措辞、粒度与反模式

技能写得好不好，直接决定 agent 是"照着做"还是"看了等于没看"。这一节是我个人经验最集中的地方，也是我觉得比 CLI 用法更值得花时间的地方。

5.1 措辞：从"描述"转向"指令"

新手写技能，最容易写成说明书。比如：

本项目的代码风格比较注重可读性，我们倾向于使用较短的函数，并且希望变量命名清晰。

这段话人读没问题，但 agent 读完之后，很可能还是按它自己的默认风格来。因为它没有拿到明确的、可判定的指令。

改成指令式：

编写函数时遵循以下规则：

• 单个函数不超过 40 行，超过则拆分
• 变量名使用完整单词，禁止a、b、tmp这类缩写（循环下标i、j除外）
• 每个导出函数必须有 JSDoc 注释，说明参数和返回值

差别在哪？后者每一条都是可判定的——agent 生成代码后，能自己检查"这个函数是不是超过 40 行了"。可判定性是指令的灵魂。

5.2 粒度：一个技能只干一件事

我一开始犯的错是"贪大"。写了一个叫coding-standards的技能，把代码风格、命名、注释、测试、提交、分支策略全塞进去，结果文件长到几百行。问题来了：agent 在处理一个具体任务时，可能只需要其中一小部分，但整个文件都被加载进上下文，既浪费窗口，又稀释了重点。

后来我改成一个技能只解决一类问题：

• code-style：只管代码风格
• naming：只管命名
• commit-convention：只管提交
• test-strategy：只管测试

这样每个文件短小精悍，agent 按需加载，命中率明显提升。粒度这件事，宁可细一点，也不要粗。

5.3 反模式清单

下面这些是我踩过或者见别人踩过的坑，列出来供你对照：

• 反模式一：把技能当知识库。塞进大量项目背景、架构图、历史决策。agent 不需要这些来执行任务，需要的是"做什么"。背景最多用一两句话交代。
• 反模式二：规则互相矛盾。两个技能里对同一件事给了不同要求，agent 会随机选一个，行为不稳定。定期做一次技能审计，把冲突挑出来。
• 反模式三：只写"要什么"，不写"不要什么"。模型有时候会"过度发挥"，明确写出禁止项（"不要引入新的第三方依赖""不要修改 public API"）能有效约束它。
• 反模式四：示例过时。技能里的示例代码如果和当前代码库脱节，agent 会照着旧示例写，反而制造问题。示例要跟着代码一起维护。
• 反模式五：没有版本和变更记录。技能改了但没人知道改了什么，出问题难追溯。给技能目录也走正常的 PR 流程。

5.4 一个我常用的"技能模板"

经过多次迭代，我现在写新技能基本套这个结构：

--- name: <kebab-case-name> description: 当<触发场景>时使用，<一句话说明作用> version: 1.0.0 --- # <技能标题> ## 适用场景 <一两句话，说明什么时候该用这个技能> ## 规则 1. <可判定的规则一> 2. <可判定的规则二> ## 正确示例 <代码或文本示例> ## 错误示例 <反例，并说明为什么错> ## 禁止事项 - <明确禁止的行为>

这个模板的好处是：触发条件清晰、规则可判定、正反例对照、禁止项兜底。实测下来，agent 遵循率比随手写的技能高不少。

6. 实战中的坑与排查：技能不生效时怎么一步步定位

技能写好了、装好了，结果 agent 还是我行我素——这是最让人抓狂的情况。这一节我把排查链路完整走一遍，你可以照着复现。

6.1 第一步：确认技能真的被加载了

很多人卡在这一步却不自知。判断方法很简单：在对话里直接问 agent。

"你现在加载了哪些技能？请列出你看到的技能名称。"

如果它列不出来，或者列的和你想的不一样，那问题在加载环节，不在技能内容。常见原因有：

• 技能目录路径不对，agent 扫描的位置和你放的位置不一致
• 项目配置文件里没有引用技能目录
• 技能入口文件名不符合约定（比如工具要SKILL.md，你写成了skill.md，某些系统大小写敏感）

6.2 第二步：确认技能内容被正确解析

如果 agent 能列出技能名，但行为不对，那可能是内容解析出了问题。重点检查：

• frontmatter 格式：YAML 缩进错了、冒号后没空格，都会导致解析失败。用个 YAML 校验工具过一遍。
• description 是否匹配任务：如果 agent 是靠语义匹配决定加载哪个技能，description 写得太泛，它可能压根没选你这个技能。
• 规则是否可判定：回到上一节说的，模糊描述 agent 无法执行。

6.3 第三步：确认优先级和冲突

有时候技能加载了、解析也对，但 agent 还是不听。这时候要怀疑冲突。比如你的技能说"用中文注释"，但另一个更高优先级的规则说"注释用英文"，agent 会选优先级高的那个。

排查方法：把相关技能都列出来，看有没有对同一件事的不同要求。解决方式是明确优先级——在项目配置里声明"技能规则优先于默认行为"，或者干脆合并冲突的技能。

6.4 第四步：上下文窗口是否被挤爆

这是个隐蔽的坑。如果你装了几十个技能，每次对话都把全部加载进去，上下文窗口很快被占满，agent 的注意力被稀释，反而记不住关键规则。

解决办法是按需加载。让 agent 根据当前任务只加载相关技能，而不是全量加载。具体怎么做取决于工具，但核心思路是：技能目录要分层，高频核心的常驻，低频的按需引用。

6.5 一个真实的排查案例

我有一次遇到的情况是：提交信息规范技能明明装了，agent 生成的提交信息还是乱七八糟。按上面四步走：

1. 问 agent，它说加载了commit-convention——加载没问题。
2. 检查 frontmatter，发现 description 写的是"Git 相关规范"，太泛——但既然加载了，这不是主因。
3. 检查冲突，发现项目规则文件里有一条"提交信息尽量简短"，和技能里的"遵循 Conventional Commits 格式"打架了。agent 选了规则文件那条。
4. 修复：把规则文件里那条删掉，统一由技能管理。

问题解决。这个案例说明，排查要按顺序来，别一上来就改技能内容，很可能内容没问题，是环境或冲突的锅。

7. 我个人的一些使用体会

用了一段时间 agent-skills 之后，有几个感受挺深，分享出来。

第一，技能的价值不在"多"，在"准"。我一开始兴致勃勃装了二十多个技能，结果发现真正高频用到的就五六个。后来我把低频的归档，只留核心的常驻，agent 的表现反而更稳定。技能不是越多越好，是越精准越好。

第二，技能要跟着项目一起演进。代码库变了、规范变了，技能不更新就会变成"历史遗留"。我现在把技能目录纳入正常的代码 review 流程，改规范的时候顺手改技能，避免脱节。

第三，别指望技能能解决所有问题。有些模糊的判断，比如"这段代码设计得好不好"，是没法写成规则的。技能擅长的是明确的、可判定的约束，对于需要审美和判断的部分，还是得人来把关。把技能用在它擅长的地方，别硬塞。

第四，跨工具复用要务实。别追求"一套技能走遍天下"，而是把核心规则抽出来，各工具按自己的方式接入。核心一致、接入灵活，这才是可持续的做法。

最后分享一个小技巧：如果你不确定某个技能写得对不对，可以让 agent 自己来评审。把技能文件丢给它，问"这个技能里有没有互相矛盾或者无法执行的规则"，它往往能挑出你自己没注意到的问题。用 agent 来优化给 agent 的指令，这个循环挺有意思。