企业官网建设流程全解析

1. 从"装完就吃灰"说起：agent-skills 到底解决了什么问题

如果你最近半年在折腾 AI coding agents，大概率经历过这个循环：兴冲冲装好 Claude Code，配好 API，打开终端，然后……不知道让它干什么。问它写个快排，它写得挺好，但你本地项目里那些真正烦人的活儿——批量改配置、按规范生成组件、跑一遍检查再提交——它一样没帮你干。问题不在模型，在于你从来没告诉过它"在这个项目里，活儿该怎么干"。

agent-skills就是冲着这个痛点来的。它是一套给 AI coding agents 用的技能包规范与配套 CLI，核心思路非常朴素：把"你希望 agent 怎么干活"从你脑子里、从聊天记录里，沉淀成项目里可版本化、可复用、可分享的文件。装完之后，你的 Claude Code、以及任何支持 skills 协议的 agent，都能自动识别这些技能，在合适的时机调用它们，而不是每次都要你重新解释一遍。

我把它理解成给 agent 写的"岗位说明书 + 操作手册"。以前你招个新人，得口头带他两周；现在你把 SOP 写进skills/目录，agent 一进项目就自动读到了。这个类比我觉得挺准的——skills 不是提示词模板那么简单，它包含触发条件、执行步骤、可用工具、注意事项，是一份结构化的作业指导书。

适合谁看？三类人最该关注。第一类是已经在用 Claude Code 或类似 agent、但只停留在"问答"阶段的开发者，你会发现自己浪费了大量重复沟通成本。第二类是团队里负责工程规范的人，skills 是把团队约定固化下来的绝佳载体。第三类是想做 agent 工具链的开发者，skills CLI 的设计思路值得研究。至于完全没接触过 AI coding agent 的朋友，建议先跑通基础流程再回来看，不然容易一头雾水。

下面我会从设计思路、核心机制、实操落地、踩坑排查四个层面，把 agent-skills 这套东西拆开讲透。所有命令和目录结构我都会给到可直接抄的程度，参数选择也会说明为什么这么定。

2. agent-skills 的整体设计与核心机制拆解

2.1 为什么是"技能文件"而不是"更长的提示词"

很多人第一反应是：我直接把要求写进CLAUDE.md或者系统提示词不就行了，为什么要搞一套 skills？我一开始也这么想，实际用下来发现两者定位完全不同。

系统提示词和CLAUDE.md是常驻上下文，每次对话都会加载，写多了会挤占宝贵的上下文窗口，而且它是"全局生效"的——你写一条"生成组件要用函数式写法"，那不管当前在改后端还是写脚本，这条规则都挂在那儿，属于噪音。skills 则是按需加载：agent 判断当前任务匹配某个 skill 的触发条件时，才把这个技能的内容读进来。这就像公司里贴在墙上的员工守则（常驻）和抽屉里的专项操作手册（按需取用）的区别。

另一个关键差异是可组合性。提示词是一坨文本，skills 是带元数据的结构化单元。每个 skill 有自己的名字、描述、触发场景、依赖工具，agent 可以精确地"挑一个来用"，而不是在一大段文字里自己找重点。这对复杂项目特别重要——一个前端项目可能有"生成 React 组件""写单元测试""更新 changelog"三个技能，它们互不干扰，各自独立演进。

提示：不要把 skills 当成提示词的替代品，两者是互补关系。全局的编码风格、项目背景放CLAUDE.md，具体任务的执行流程放 skills。

2.2 skills 的目录结构与元数据设计

一个标准的 skill 在文件系统里长这样，这是我在多个项目里验证过的最小可用结构：

your-project/ ├── .claude/ │ └── skills/ │ ├── gen-component/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── component.tsx.tpl │ └── run-checks/ │ └── SKILL.md ├── CLAUDE.md └── src/

核心是每个技能目录下的SKILL.md。它的开头是一段 YAML frontmatter，用来声明元数据，后面是 Markdown 正文，写具体执行逻辑。一个真实可用的例子：

--- name: gen-component description: 按项目规范生成 React 函数式组件，包含类型定义、样式文件和测试骨架。当用户要求"新建组件""生成组件"时使用。 allowed-tools: Read, Write, Bash --- # 生成 React 组件 ## 触发条件 用户提到新建/生成/创建组件，且指定了组件名。 ## 执行步骤 1. 读取 `src/components/` 下最近修改的 2 个组件，学习当前写法风格。 2. 在 `src/components/<Name>/` 下创建三个文件： - `index.tsx`：函数式组件，props 用 interface 定义 - `styles.module.css`：CSS Modules - `index.test.tsx`：至少一个渲染测试 3. 组件名使用 PascalCase，文件名与目录名一致。 4. 完成后运行 `pnpm lint` 校验。 ## 注意事项 - 不要引入新的第三方依赖，除非用户明确要求。 - 样式优先用 CSS Modules，禁止内联 style。

这里有几个设计决策值得说清楚。description字段是触发匹配的关键，agent 主要靠它判断"当前任务该不该用这个技能"，所以要把用户可能说的原话（"新建组件""生成组件"）都写进去，而不是写成"用于组件生成功能"这种抽象描述。allowed-tools是权限边界，声明这个技能最多能用哪些工具，避免一个生成组件的技能偷偷去删文件。正文里的步骤要写成可执行的动作序列，而不是"应该注意代码质量"这种没法落地的空话。

2.3 skills CLI 的角色与工作流

skills CLI 是配套的命令行工具，负责技能的安装、分发和校验。它的价值在于让技能可以像 npm 包一样被分享——你写好一套团队规范技能，同事一条命令就能装到本地。

常见的工作流是这样的：

# 从仓库安装技能到当前项目 skills install github:your-org/frontend-skills # 列出当前项目已安装的技能 skills list # 校验技能文件格式是否合法 skills validate # 把本地技能发布出去 skills publish

我实测下来，skills validate这个命令最容易被忽略但最有用。它会在你写错 frontmatter 字段、description 缺失、目录结构不对时直接报错，省得你装进 agent 之后发现技能死活不触发，然后花半小时排查。养成写完就 validate 的习惯，能省很多事。

注意：不同 agent 对 skills 目录的默认扫描路径可能不同。Claude Code 默认读.claude/skills/，如果你用的是别的 agent，先确认它认哪个路径，别写完发现根本没被加载。

2.4 与 slash commands 的关系和边界

热词里出现了 slash commands，这里必须澄清一下，因为很多人会把两者搞混。slash commands（斜杠命令）是用户主动触发的，你敲/gen-component Button，它才执行。skills 是agent 自主判断的，你说"帮我加个按钮组件"，agent 自己决定调用 gen-component 技能。

实际项目里两者经常配合：把高频、需要精确控制的操作用 slash command 暴露给用户，把需要 agent 智能判断的流程做成 skill。比如"发布版本"这种一步都不能错的操作用/release命令，而"根据改动生成 changelog"这种需要理解代码的活儿交给 skill。理解这个边界，你的技能体系才不会乱。

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

3.1 写好 description：决定技能能否被触发的关键

我踩过最大的坑就在 description 上。第一版我写的是"用于生成符合项目规范的组件"，结果 agent 十次有八次不触发，我手动喊它才用。后来改成把用户真实会说的话塞进去，触发率立刻上来了。

判断标准很简单：把 description 当成"用户在什么情况下会需要这个技能"的答案来写。好的 description 包含三要素——做什么、什么时候用、关键词覆盖。对比一下：

我的经验是控制在 2-3 句话，把最常用的 3-5 种用户说法列进去就够了。堆太多反而会让 agent 判断时犹豫。

3.2 步骤拆解：把"专家直觉"翻译成可执行动作

写技能正文最难的，是把你自己做这件事时的隐性判断显性化。比如你生成组件时会下意识看一眼现有代码风格，这个动作如果不写出来，agent 就不会做，生成的东西风格跟项目格格不入。

我的方法是边做边录：真的手动做一遍这个任务，把每一步操作和判断都记下来，然后整理成步骤。以"生成组件"为例，我录下来的原始记录是这样的：

• 先看 components 目录，找最近的组件参考
• 确认命名规范（发现是 PascalCase）
• 建目录、建三个文件
• 类型定义用 interface 不用 type（项目约定）
• 跑 lint

整理成技能步骤后，就变成了前面 2.2 节那个样子。关键是每一步都要是 agent 能执行的动作，"参考现有风格"要具体到"读取最近修改的 2 个组件"，否则 agent 不知道读几个、读哪些。

3.3 allowed-tools 的权限设计原则

allowed-tools是安全边界，设计原则是最小必要。一个只读分析类技能，就只给Read, Grep, Glob；一个生成文件的技能，给Read, Write；只有确实需要跑命令的才给Bash。

我见过有人图省事，所有技能都写allowed-tools: Read, Write, Bash, Edit，这等于没设边界。一旦某个技能逻辑写歪了，agent 可能执行破坏性命令。特别是团队共享的技能，权限收紧是对所有人的保护。

提示：如果某个技能确实需要 Bash，尽量在正文里把允许执行的命令范围写清楚，比如"只允许运行 pnpm lint 和 pnpm test"，给 agent 一个明确的约束。

3.4 技能粒度：多大算合适

粒度太粗，一个技能干十件事，agent 判断时容易误触发；粒度太细，一个技能只干一件小事，维护成本高还容易互相干扰。我的经验法则是：一个技能对应一个"用户能一句话说清的任务"。

"生成组件"是一个合适粒度。"生成组件并写测试并更新文档并提交"就太粗了，应该拆成三个技能，让 agent 按需组合。"给组件加一行注释"又太细，不值得单独建技能。

判断方法：如果你没法用一句话向同事描述这个技能是干嘛的，那它粒度就不对。

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

4.1 环境准备与目录初始化

先把基础环境跑通。假设你已经在用 Claude Code，第一步是确认 skills 目录位置。在项目根目录执行：

mkdir -p .claude/skills

然后创建第一个技能。我建议从最简单的开始，别一上来就搞复杂的。先做一个"项目结构速查"技能，让 agent 快速了解项目布局：

mkdir -p .claude/skills/project-overview

创建.claude/skills/project-overview/SKILL.md：

--- name: project-overview description: 当用户询问项目结构、目录用途、某个文件在哪、项目怎么组织时使用。 allowed-tools: Read, Glob, Grep --- # 项目结构速查 ## 执行步骤 1. 读取根目录的 `package.json` 和 `README.md`。 2. 用 Glob 列出 `src/` 下两层目录结构。 3. 总结：技术栈、主要目录职责、入口文件位置。 4. 如果用户问的是具体文件，用 Grep 定位后给出路径。 ## 输出格式 用简洁的列表说明，不要贴大段代码。

写完跑一下校验：

skills validate

如果 CLI 没装，先按官方文档装好。校验通过后，重启 Claude Code 会话（技能是启动时扫描的），然后问它"这个项目结构是怎样的"，看它是否自动调用了这个技能。这一步验证通过，说明你的 skills 机制跑通了。

4.2 从零写一个"提交前检查"技能

这是我觉得最实用的技能之一。每次提交前手动跑 lint、test、类型检查很烦，交给 agent 自动做。

创建.claude/skills/pre-commit-check/SKILL.md：

--- name: pre-commit-check description: 当用户要求提交代码、检查代码、准备 commit、跑测试时使用。 allowed-tools: Read, Bash, Grep --- # 提交前检查 ## 执行步骤 1. 运行 `git status` 和 `git diff --stat`，了解改动范围。 2. 按顺序执行以下检查，任一失败就停止并报告： - `pnpm lint` - `pnpm typecheck` - `pnpm test --run` 3. 全部通过后，总结改动文件数量和检查结果。 4. 如果用户要求生成 commit message，按 Conventional Commits 规范生成。 ## 注意事项 - 不要自动执行 `git commit`，只做检查和建议。 - 如果某个命令不存在，跳过并说明，不要报错中断。 - 测试失败时，把失败用例的完整输出贴出来。

这里有个关键设计：不自动提交。我试过让 agent 自动 commit，结果它把一堆临时文件也提交了。检查和建议可以自动化，最终提交动作留给人工确认，这是安全底线。

4.3 参数与触发条件的调优过程

技能写完后，触发准确率需要调优。我的做法是准备一组测试语句，反复验证。比如针对 pre-commit-check，我准备了这些：

• "帮我提交一下" → 应该触发
• "跑下测试" → 应该触发
• "检查代码" → 应该触发
• "这个函数怎么写" → 不应该触发

实测发现"检查代码"这个说法有时会被理解成"代码审查"而不是"提交前检查"，于是我在 description 里补了"提交前"这个限定词，误触发就少了。这个调优过程没有捷径，就是多试、多改 description。

注意：调优时改的是 description，不是正文。正文是执行逻辑，description 才是触发匹配的依据，别改错地方。

4.4 团队共享与版本管理

技能写好后放进 git 仓库，团队共享。我的目录组织方式是把技能和项目代码放同一个仓库，.claude/skills/跟着项目走，这样每个人 checkout 下来就自动有了。

如果技能要跨项目复用，就单独建一个 skills 仓库，用 CLI 安装：

skills install github:your-org/shared-skills

版本管理上，技能文件也要走 code review。我见过有人随手改技能导致整个团队的 agent 行为异常，所以技能变更应该像代码一样被审查。特别是allowed-tools的变更，扩大权限的改动必须有人把关。

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

5.1 技能不触发怎么办

这是最高频的问题。排查顺序我整理成了一张表：

我遇到最多的是最后一条。技能是会话启动时加载的，你改了文件不重启，agent 用的还是旧版本。这个坑我踩过不止一次，改完技能记得重启。

5.2 技能执行到一半失败

常见于 Bash 命令失败或文件路径不对。排查思路是先看 agent 报的错，再手动复现那条命令。如果手动跑没问题，那多半是 agent 执行时的工作目录不对，或者命令里的路径是相对的、依赖了错误的 cwd。

解决方法是在技能正文里把路径写绝对，或者明确说明"在项目根目录执行"。我现在的习惯是，凡是涉及文件路径的步骤，都写清楚相对于哪里。

5.3 技能之间互相干扰

当技能多了之后，可能出现 A 技能被 B 技能抢触发的情况。根因是 description 语义重叠。解决办法是给每个技能加一个独占关键词。比如"生成组件"和"生成页面"两个技能，前者加"组件/component"，后者加"页面/page"，让 agent 有明确的区分依据。

如果实在分不开，考虑合并成一个技能，在正文里用条件分支处理两种情况。粒度不是越细越好，能清晰区分才是好粒度。

5.4 权限相关的报错

如果技能里用了allowed-tools没声明的工具，agent 会拒绝执行。报错信息通常会说某个工具不可用。这时候检查两处：frontmatter 里有没有声明这个工具，工具名拼写对不对（大小写敏感，是Read不是read）。

我建议一开始把可能用到的工具都列上，跑通之后再逐步收紧到最小集合。先能用，再安全，这个顺序比较符合实际。

5.5 独家避坑清单

最后分享几条文档里不会写、但实际很要命的经验：

• 技能正文别写太长。超过 200 行的技能，agent 执行时容易漏步骤。长流程拆成多个技能串联。
• 别在技能里写死具体业务值。比如别写"组件名用 Button"，要写"组件名用 PascalCase"，否则技能没法复用。
• 技能要能独立测试。写完先手动模拟一遍 agent 的执行路径，确认每步都能落地，再交给 agent。
• 给技能加个"失败时怎么办"。比如检查失败时是停止还是继续，写清楚，否则 agent 会自己瞎猜。
• 定期清理不用的技能。技能越多，agent 判断成本越高，误触发概率越大。季度清一次。

这套东西我用了几个月，最大的感受是：agent 的能力上限，取决于你给它多少结构化的上下文。skills 就是把这个上下文工程化的手段。刚开始写会觉得麻烦，但一旦积累起来，你会发现 agent 从"什么都要问"变成了"自己就知道该干嘛"，这个转变带来的效率提升是实打实的。