企业官网建设流程全解析

1. 先想清楚：Agent Skills 到底解决了什么问题

今年 AI Agent 圈子里，skills 几乎成了绕不开的话题。不管你在用 Claude、Codex、Codex 还是自研的 Agent 框架，都会碰到一个问题：怎么让模型不只会聊天，而是真的会做事。我最近把 skills 从概念到落地完整过了一遍，包括官方技能市场里的现成技能包、社区里流传的 superpower skills、以及自己动手写技能的全流程。这篇就把这些整理成一份偏实战的笔记，适合正在用 AI Agent 写代码、写文档、做自动化流程的人。如果你完全没接触过 skills，读完也能上手，因为后面每一步我都会拆开讲，不会只丢给你一句“装一个就行”。

1.1 从一次对话看 Skills 的价值

我举一个很常见的例子。你让 agent“审查一下这个前端项目的代码”，如果没有 skills，模型的回复大概率是“你应该注意可读性、性能、安全性”这种正确的废话。它不会真正打开文件，不会执行测试，也不知道你团队约定里“组件文件不能超过 200 行”这条规则。但如果你提前装了一个 frontend-review 技能，情况会完全不一样。这个技能会告诉模型：第一步看 package.json 确认技术栈，第二步跑一遍 lint，第三步按可访问性、性能、代码结构三个维度输出问题清单。于是同样的请求，agent 做出来的就接近一个初级工程师的审查报告。

这个例子引出了 skills 的核心价值：它不是给模型增加知识，而是给模型增加“操作规范”。模型本身有推理能力，但缺少专业领域的执行习惯。技能就是把这些习惯固化成可加载、可复用、可分享的文件包。社区里管这叫 superpower skills，我觉得很贴切。单个技能可能只是几个 Markdown 文件和脚本，但组合起来，真的能让 agent 从“能聊天”变成“能干活”。我见过有人先装了十几个技能再开始用 agent，体感完全是两个产品：一个是会说话的搜索引擎，一个是会帮你把事办完的实习生。

Skills 的出现，本质上是在给 Agent 补齐“工作中的肌肉记忆”。大模型的知识面很广，但它不知道你公司代码仓库里命名规范是什么，不知道你写报告时老板要求的格式是什么，更不知道一个合格的短视频分镜脚本该包含哪几个字段。这些信息放进技能包，Agent 就拥有了“场景知识”。这也是为什么说 skills 是 Agent 能力的放大器：同一个模型，配上不同技能，表现出的专业水平可以差好几个档位。

1.2 Skills 和 Prompt、Tools、Workflows 的边界

很多第一次接触 skills 的人会混淆几个概念：Prompt、Tool、Skill、Workflow。我习惯用生活化的方式区分。Prompt 是一句话，告诉模型今天要干什么；Tool 是一双手，比如终端执行、文件读写、网页搜索这些可调用能力；Skill 则是“职业习惯+操作手册”，它把指令、示例、工具绑定、判断规则打包成了一个完整的行为模式；Workflow 是多步骤流程，可以理解成一条流水线，而 Skill 是流水线上某个工位的标准作业指导书。

用代码来理解更直接。一个典型的 Skill 目录长这样：

my-skill/ ├── SKILL.md # 技能的说明书，Agent 会先读它 ├── scripts/ # 可选，技能配套的脚本 │ └── check.sh └── assets/ # 可选，模板、数据等辅助文件

SKILL.md 本身是 Markdown 文件，但格式很重要。开头要有 YAML frontmatter，写上 name 和 description，下面才是正文。Agent 会根据 description 判断什么时候激活这个技能。这意味着 Description 写得越清晰，技能被正确调用的概率越高。我见过很多好技能死在不合格的描述上，后面我会详细讲。

Tools 和 Skills 的关系也常被搞混。一个 Skill 可以调用多个 Tool。比如一个“论文润色”技能，它可以调用文件读取工具读草稿，调用搜索工具查文献，再调用文本编辑工具输出修改建议。所以 Skills 并不是取代 Tools，而是站在 Tools 之上，把工具的使用方式、使用顺序、输出标准都规定好。理解了这些，再看官方市场的各种安装包、社区里的 skills 大全会更清楚：它们本质上都是在分发这种“操作手册+工具脚本”的组合包。

2. skills 从哪来：官方市场、社区仓库、自己动手

了解概念之后，大部分人第一个动作是找现成的技能包。我这里把“找”分成三类：官方渠道、社区仓库、自己造。三者的选择逻辑不一样，混着用也行，但心里得有数。

2.1 官方渠道与社区仓库怎么选

官方市场是首选，因为上架的技能通常经过基础校验，目录结构规范、描述清晰，兼容性有保障。你可以在产品设置里找到技能管理入口，也可以直接去官方文档查看支持的目录位置。常见做法是把技能包放到用户级目录，比如~/.claude/skills下，或者项目级目录.claude/skills下。用户级目录对所有项目生效，项目级目录只对当前仓库生效。我自己的习惯是：通用技能放用户级，和业务强相关的技能放项目级，这样团队协作时跟着代码库走。

社区仓库是第二选择。GitHub 上有很多 awesome-skills 列表，也有人专门维护 skills 大全，覆盖面从代码审查到文案写作都有。下载之前我建议看一眼 star 数、更新时间、目录结构，以及是否带测试用例。另一个不能忽视的要点是安全问题，技能包里的脚本会在本机执行，所以不要看到“XX skills 安装包下载”就随便拿回来。先打开 SKILL.md 和 scripts 里的内容翻一遍，确认没有可疑命令再安装。这个习惯能帮你避免绝大多数供应链投毒的风险。

如果社区仓库都不满足需求，那就自己造。自己造 skill 并不难，本质上就是写一份 Markdown 说明书，再加几个可选脚本。很多人一听“开发技能”就被劝退了，其实不需要会写复杂程序。你只要能把一件重复性工作拆成“步骤+检查点”，就已经具备开发技能的核心能力。脚本只是把步骤里能自动化的部分自动化，不能自动化的部分靠模型推理补齐。

2.2 安装一个 skills 的标准动作

安装技能包没有统一标准，不同 Agent 产品的目录和格式略有差异，但核心动作是一致的：把技能目录放到 Agent 能扫描到的路径。以通用做法为例：

1. 下载技能包压缩包，解压后确认里面有 SKILL.md 文件；
2. 放到技能目录，比如~/.claude/skills/或者./.claude/skills/；
3. 重启当前 Agent 会话，让配置重新加载；
4. 用一个和该技能描述匹配的提示词触发测试，比如技能是“生成分镜脚本”，就用“帮我把这段文案转成 10 个镜头”来试。

这里有个关键点：Agent 不是把所有技能文件全部读入上下文，而是根据你的请求，结合技能目录里每个 SKILL.md 的 description 做检索。所以技能描述里的关键词写得越贴近真实使用场景，它越容易被找到。如果安装后技能一直没生效，大概率是 description 写得太抽象，或者路径不对。别急着怀疑是下载包坏了，先按这个顺序排查。

另外提醒一下，官方市场的技能有时会自动更新，社区下载的技能不会。所以如果你自己从网上下载技能包，建议记录版本号，或者干脆用 Git 管理。我见过有人复制粘贴了一个旧版技能文件夹，结果新项目里一直用着一年前的规则，改了很久才发现是技能没更新。版本管理这件事，在技能数量少的时候看不出来，等你有十几个技能的时候，没有版本管理就是一场灾难。

3. 手写一个自己的 Skills：设计、开发、调试

现成的技能包再多，也总有场景覆盖不到。所以 skills 的最终形态必然是“自己动手做”。整个过程不难，但有几个设计上的坑，我想单独拿出来讲。

3.1 Skill 的最小结构：SKILL.md 是灵魂

做技能前先记住一个原则：SKILL.md 决定 Agent 的思考方式，scripts 决定 Agent 的执行能力。如果只写一个“技能说明文档”，没有脚本，技能也能工作；但如果你塞进去一堆脚本，却没有清晰的操作指令，技能会变成一堆没人调用的死代码。

一个标准的 SKILL.md 长这样：

--- name: frontend-code-review description: 用于对前端项目进行代码审查，按照可访问性、性能、结构三个维度输出问题清单。适用于 React/Vue 项目评审场合。 --- # Frontend Code Review ## 步骤 1. 读取 package.json，确认技术栈和依赖版本。 2. 运行 npm run lint，记录错误数量。 3. 依次检查 src 下所有组件，关注可访问性、性能隐患、命名规范。 4. 输出 Markdown 报告，包含问题等级、文件路径、修改建议。 ## 检查清单 - [ ] 图片是否都有 alt 属性 - [ ] 列表是否使用了正确的语义标签 - [ ] 是否存在 render 阶段不必要的复杂计算

注意 description 里我写了“React/Vue 项目评审场合”，这句话决定了 Agent 会不会在你提及“查一下前端代码”的时候调用它。技能正文没有要求写得特别长，但步骤要具体，最好带上“运行什么命令、看什么文件、输出什么格式”。抽象的描述对模型来说等于没有描述。

3.2 一个实战例子：前端代码审查助手

我第一次完整开发技能，做的就是前端代码审查。需求来自团队日常：每个人写代码风格不一致，code review 全靠人肉盯，效率很低。后来我把检查规则整理成上面那个 SKILL.md，还在 scripts 目录放了一个 check.sh，里面跑 lint、圈复杂度、检查 TODO 标记。当 Agent 发现 lint 报错，它会去读报错信息，结合技能里的检查清单生成报告。

实际效果比我预想的好。它不会替代人工 review，但能把“低级问题”全筛一遍。比如图片缺 alt、console.log 残留、未使用的 import，这些问题以前要人在 PR 里追着问，现在技能一跑就出来。开发过程中我踩了一个坑：第一次写 description 时用了“审查前端代码”，后来发现 Agent 在有歧义时经常拿不准要不要触发。改成“按照可访问性、性能、结构三个维度输出问题清单”之后，触发准确率高了很多。原因很简单，模型是通过语义匹配决定技能的，描述越贴近用户需求，匹配越准。

这个例子还说明了一个问题：技能包的“开发”和“打磨”是两个阶段。第一版能跑通只是开始，真正有价值的是你在真实项目里不断调整描述、补充规则。我把这个过程理解为“教 Agent 学会团队规范”，你必须像带新人一样，把隐性知识一点点写进技能文件里。带新人的耐心，在技能开发上一点都不少。

3.3 开发流程里的三条调试经验

开发技能不要一上来就写大而全的脚本。我的流程是先写一版最小 SKILL.md，只包含一个步骤，跑通后再逐步加规则。因为技能一旦复杂，排查问题时你不知道是思路错了还是脚本错了。先小步验证，比一次写到位稳得多。

第二，技能里的脚本要保持独立可测。所谓独立可测，就是这个脚本单独在终端里跑也能出结果，不依赖 Agent 的对话上下文。我在开发时会把脚本命令先手动执行一遍，确认输出格式，再让 Agent 去调用。如果脚本在终端里都报错，Agent 拿到一堆乱报错信息，根本没法继续推理。

第三，善用“让技能自己解释”这个调试手段。出问题时，直接在对话里问 Agent：“你读取了哪些技能？为什么选择这个技能？”多数 Agent 会把决策依据说出来，这时候你就能看到 description 的哪些词造成了误匹配。这个办法听着原始，但比我见过的一些可视化调试工具都管用。模型是自己的执行者，也是自己的解释器，这种双重角色是 Agent 调试和传统工程调试最不一样的地方。

4. 拿到就能用：几个贴近实战的 skills 场景

Skills 是个通用机制，但我发现最容易体现价值的场景就那么几类。挑三个我真实用过的写一下，分别是前端开发、论文写作、自动化检查。

4.1 前端开发：从分镜脚本到组件生成

前端开发者玩技能有天然优势，因为技能可以绑定脚本，脚本可以直接改文件。我除了代码审查，还做过一个“分镜脚本生成”技能，给短视频团队用。输入是一段文案，输出是镜头列表，内容包括景别、运镜、画面内容、台词、字幕。这个技能里没有复杂脚本，主要靠 SKILL.md 里的模板格式和示例约束模型输出。实际用下来，生成本科级的分镜脚本完全够用，人类导演微调一下镜号顺序就能开拍。

这类技能的设计要点是“输出模板要非常具体”。如果你只说“生成分镜”，模型会给你一套通用镜头语言；但你在技能里列好“景别/运镜/画面/台词/字幕”表格，再加上两三个不同风格的示例，它输出的东西就基本可以直接进拍摄脚本。所以做内容生成类技能时，重点不是教模型“什么是分镜”，而是给模型一个“填空语法”。

前端领域的另一个高频技能是组件生成。你可以把团队组件库的目录结构、命名规范、常用 props 写进技能，让 Agent 按规范生成新组件。这比单纯靠 prompt 要稳定得多。我试过把一个项目的组件规范写进技能后，让 Agent 生成一个带有 loading 状态的表格组件，出来的代码风格和团队旧代码几乎一致，同事看了以为是我写的。

4.2 论文写作与结构化输出

论文写作是另一个高频场景。我见过不少人用 Agent 写摘要、改引言，但效果起伏很大。后来我意识到，问题不在模型，而在缺少一个“学术写作规范”技能。这种技能会规定：摘要要包含背景、方法、结果、结论四个要素；引用格式要符合指定标准；术语首字母缩写第一次出现时要给出全称。这些规则你让模型每次都遵守，它偶尔会忘，但做成技能后每个段落都会对齐。

我还给技能加了一个检查环节：输出初稿后，技能要求模型逐段对照检查清单，把不满足的项标出来并修改。这是模拟人工审稿的“自检”步骤，对提升质量很有帮助。类似的思路用在技术文档、产品文案上都成立。结构化的关键不是模型不够聪明，而是你没有给它一份足够明确的作业标准。

用这套方法，我后来还写了一个“Codex 写论文”的技能变体。因为不同的代码模型对 Markdown 的解析习惯不太一样，所以同一个技能在不同产品里可以微调之后复用。技能内容不用重写，只需要把说明里偏产品特性的地方改掉，其他部分可以原样保留。这也说明 skills 天然具有跨平台迁移的属性。

4.3 自动化检查与“挖洞”思维的合规用法

社区里有人把自动化漏洞挖掘做成技能，还起了个很唬人的名字叫“自动挖洞 skills”。我试过之后，更愿意把它理解成“自动安全检查清单的机械化”。它做的事情是：扫描配置文件里是否有硬编码密钥、检查依赖版本有没有已知漏洞、探测常见的错误认证配置。这些手段本身是中性的，但使用边界极其重要。我只建议在授权范围内的测试环境、或者自己维护的代码仓库里跑这类技能，千万别拿去对别人的线上服务做测试，那不是技术问题，是法律问题。

这类技能的开发思路是：把渗透测试工程师的检查步骤拆成可执行的脚本和固定提问模板。比如先读取配置，再正则搜索密钥，再根据结果调用公开漏洞库接口比对版本号。模型在这里扮演的是“按图索骥的执行者”，真正的判断标准还是人定的。这一点想清楚，你就能安全且高效地把很多重复性安全检查交给 Agent 了。

安全场景和内容生成场景最大的不同在于，它需要技能给出“终止条件”。我在技能里会写：如果发现疑似敏感信息，不要直接在对话里输出完整内容，只报告路径和类型；如果某个检查需要外部授权，必须停下来问用户确认。把安全边界写进技能本身，既是对模型的一种保护，也是对自己的一种保护。

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

最后这部分，我把使用和开发 skills 过程中遇到的问题按频率排了个序。如果你刚接触，建议先把这一节存下来。

5.1 为什么技能没有被触发

这是最常见的头号问题。技能装好了，目录也对，但 Agent 就是不调用。我总结下来主要有三个原因，按优先级排查：

• description 写得太抽象或太宽泛，模型无法判断“当前请求是否属于这个技能”；
• 技能目录没有放在 Agent 扫描的路径范围内，比如改了项目级目录却期待全局生效；
• 会话没有重启，新技能没有进入索引。

排查方法很简单：先重启会话，再换一个更口语化的请求，最后直接问 Agent 是否识别到该技能。多数情况下，改描述比改代码更有效。我还遇到过一种情况，就是两个技能的 description 高度重叠，结果模型随机选了一个。这时候要尽快把技能的定位差异化，否则每次触发都像抽签。

5.2 上下文爆掉与输出不稳定

技能会把 SKILL.md 全文读入上下文，如果技能里塞了大段参考文档，token 消耗会明显上升。一个 200 行的技能文件，实际给模型带来的上下文开销可能翻倍。我的解法是把长资料从 SKILL.md 里拆出去，放到 assets 文件夹，技能正文里只保留关键规则和路径，让模型按需读取。这在 Agent 框架里对应“按需加载”，能显著降低阻塞和成本。

输出不稳定也常和技能内示例不够有关。模型在对话中会模仿示例风格，如果你希望输出稳定为表格，就在技能里给出一个完整的表格示例；如果你希望输出稳定为 JSON，就在技能里贴一个 schema。没有示例的技能就像一个只有口头描述没有样品的工厂，产品残次率当然高。

我自己在写技能时，现在都会在 SKILL.md 最后放一个“示例输出”区块。哪怕是三行摘要，也能让模型的输出风格一下子收敛很多。这个方法适用于所有类型的技能，不只是生成类。

5.3 版本管理、依赖与安全

Skills 是纯文本加脚本，天生适合用 Git 管理。我建议每个技能单独一个仓库，或者至少在一个 monorepo 里分目录管理，方便回滚。技能里如果依赖 Python 或 Node 包，一定要在技能目录中单独声明 requirements.txt 或 package.json。不要假设运行环境已经装好所有依赖，否则换一台机器技能就会变得不可用。

依赖安装之后，记得验证一次脚本是否可以在技能目录下独立执行。有的技能脚本里写了相对路径，Agent 在不同工作目录下调用时会出现“找不到文件”的问题。解决方式是在 SKILL.md 里显式说明“所有脚本需要以技能目录为根路径执行”，并在脚本开头用 cd 切换到自身所在目录。这是一个很小的细节，但能省掉大量排查时间。

安全方面再多说一句。只要是社区来源的技能，安装前都要检查脚本内容。用文本编辑器打开 scripts 目录，看有没有奇怪的下载命令、环境变量读取或者隐藏的网络请求。不要为了图方便跳过这一步。技能机制给了 Agent 执行能力，也给了风险面，保持透明和克制，它才是好工具。踩过几次坑之后，我现在凡是新装一个社区技能，第一件事一定是先看脚本再丢给 Agent 测试。这个习惯看起来很保守，但在技能来源鱼龙混杂的当下，是成本最低的安全保障。