企业官网建设流程全解析

1. 从“skills”这个标题说起：它到底指什么

第一次看到“skills”这个标题，很多人会以为是泛泛而谈的能力清单，或者某个招聘网站上的技能标签页。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看，这里说的“skills”其实是一个很具体的技术概念——AI Agent 的可插拔能力模块。

你可以把它理解成给 AI 助手装的一个个“技能包”。一个 AI Agent 本身只会聊天、写代码、做推理，但当你给它挂上某个 skill 之后，它就能做特定的事情：比如自动操作浏览器、自动挖洞测试、自动生成分镜脚本、自动写论文、自动做代码审查。每个 skill 本质上是一段封装好的指令、工具调用逻辑和上下文约束，Agent 加载它之后就获得了对应的能力。

这个项目标题“skills”背后真正要解决的问题是：如何让一个通用 AI Agent 快速获得垂直领域的能力，而不需要重新训练模型。适合谁来参考？三类人：一是想给自己常用的 AI 编程助手扩展能力的前端或全栈开发者；二是想用 AI Agent 做自动化测试、自动化内容生产的技术人员；三是想搞清楚 Agent Skills 这套机制到底怎么运作、值不值得投入时间学习的技术决策者。

我接触这套东西有一段时间了，从最早的 MCP 协议到后来的 Agent Skills 目录规范，踩过不少坑。下面我把整个思路、实操细节和排查经验完整拆一遍，尽量让没接触过的人也能跟着做出来。

2. 整体设计思路：为什么是“技能包”而不是“大模型微调”

2.1 核心矛盾：通用能力和垂直能力之间的鸿沟

大模型的能力是通用的，但真实工作场景需要的是垂直能力。你让一个通用模型去写论文，它可能格式不对、引用不规范；你让它去做安全测试，它可能连基本的扫描流程都不清楚。传统的解法有两种：一是微调模型，二是写很长的提示词。

微调的问题在于成本高、周期长、每次新增能力都要重新训练，而且微调后的模型容易在其他任务上退化。长提示词的问题在于上下文窗口有限，你把所有领域知识都塞进去，模型反而抓不住重点，而且提示词维护起来极其痛苦。

Agent Skills 走的是第三条路：把能力封装成独立的、可加载的模块。每个 skill 是一个目录，里面包含指令文件、工具定义、示例和约束条件。Agent 在需要的时候加载对应的 skill，不需要的时候就不加载。这样既保持了模型的通用性，又获得了垂直领域的专业能力。

2.2 为什么选择 npx 作为分发方式

热搜词里出现了 npx、npx playwright install 失败这些词，说明这套 skills 生态和 npm 生态是深度绑定的。为什么用 npx 而不是别的分发方式？

npx 的好处是零安装、跨平台、版本可控。你不需要全局安装一个 CLI 工具，直接 npx 就能运行。对于 skill 这种轻量级的能力模块来说，用 npm 包的形式分发是最自然的——开发者已经熟悉 npm 的版本管理、依赖管理和发布流程，skill 作者只需要按照规范打包，用户 npx 一下就能用。

而且 npx 天然支持从 GitHub 直接拉取，这就解释了为什么热搜里同时出现 github skills 和 skills 下载平台。GitHub 是 skill 的主要托管平台，npx 是主要的运行入口。

2.3 方案选型的三个关键考量

我在选型时主要看三点。第一是加载速度，skill 不能太重，否则每次加载都要等很久，体验很差。第二是隔离性，一个 skill 出问题不能影响其他 skill 和主 Agent。第三是可组合性，多个 skill 能不能叠加使用，比如同时加载“浏览器操作”和“安全测试”两个 skill。

Agent Skills 的设计基本满足这三点：skill 是纯文本加轻量脚本，加载快；每个 skill 在独立上下文里运行，隔离性好；skill 之间通过标准接口通信，可以组合。这也是为什么它能在短时间内形成生态的原因。

3. 核心细节解析：一个 skill 到底由什么组成

3.1 目录结构和关键文件

一个标准的 skill 目录通常长这样：

my-skill/ SKILL.md # 核心指令文件，定义 skill 的能力和使用方式 manifest.json # 元数据，包含名称、版本、依赖、入口 tools/ # 工具定义目录 browser.js scanner.js examples/ # 示例目录，给 Agent 参考 example-1.md README.md # 给人看的说明文档

其中最重要的是 SKILL.md 和 manifest.json。SKILL.md 是给 Agent 读的，里面用自然语言描述这个 skill 能做什么、什么时候用、怎么用、有什么限制。manifest.json 是给运行时读的，定义技术层面的元信息。

我见过很多人写 skill 时把这两个文件搞混，把技术细节写进 SKILL.md，把自然语言描述写进 manifest.json，结果 Agent 读不懂，运行时也解析不了。记住一个原则：SKILL.md 面向 Agent，manifest.json 面向机器。

3.2 SKILL.md 的写法要点

SKILL.md 不是随便写写就行的，它直接决定了 Agent 能不能正确使用这个 skill。我总结了几条经验。

第一，开头必须明确说明这个 skill 解决什么问题。不要写“这是一个浏览器操作 skill”，要写“当用户需要自动打开网页、填写表单、截图或提取页面内容时，使用这个 skill”。

第二，要写清楚触发条件。Agent 需要知道什么时候该加载这个 skill。比如“当任务涉及网页交互、页面截图、表单提交时加载”。

第三，要给出具体的使用示例。示例比描述更有用，Agent 会模仿示例的格式来调用工具。

第四，要写明限制和禁忌。比如“不要用于需要登录态的页面操作”“单次操作不要超过 30 秒”。

提示：SKILL.md 里的指令要具体、可执行，避免模糊表述。写“提取页面标题”比写“获取页面信息”好得多。

3.3 manifest.json 的关键字段

manifest.json 里几个字段必须写对，否则 skill 加载会失败：

我踩过最坑的一次是 permissions 字段漏写了一个网络访问权限，结果 skill 在本地测试正常，一部署到云端就报错，排查了半天才发现是权限声明的问题。

3.4 工具定义和调用约定

skill 里的工具定义要遵循统一的调用约定。通常每个工具是一个函数，接收参数对象，返回结果对象。参数和返回值的结构要在 SKILL.md 里写清楚，这样 Agent 才知道怎么传参。

比如一个浏览器截图工具：

// tools/screenshot.js module.exports = { name: 'screenshot', description: '对指定 URL 截图并保存到本地', parameters: { url: { type: 'string', required: true }, outputPath: { type: 'string', required: true }, width: { type: 'number', default: 1280 }, height: { type: 'number', default: 720 } }, async execute({ url, outputPath, width, height }) { // 实际截图逻辑 } };

这种结构化的定义让 Agent 能准确理解工具的用途和参数，减少调用错误。

4. 实操过程：从零安装并运行第一个 skill

4.1 环境准备和依赖检查

在开始之前，先确认环境。你需要 Node.js 18 以上版本，npm 或 npx 可用。检查命令：

node -v npm -v npx -v

如果 npx 不可用，通常是 npm 版本太低，升级一下就行。另外，如果你要用到浏览器相关的 skill，还需要确保系统有 Chromium 或 Chrome 的可执行文件。

热搜里出现 npx playwright install 失败，这个问题很常见。原因通常是网络问题或者系统缺少依赖库。在 Linux 上，Playwright 需要一些系统库，可以用npx playwright install-deps安装。如果还是失败，检查一下磁盘空间和权限。

4.2 安装第一个 skill 的完整流程

假设我们要安装一个“网页内容提取”skill。流程如下：

1. 创建 skill 目录：mkdir -p ~/.agent-skills/web-extract
2. 进入目录：cd ~/.agent-skills/web-extract
3. 用 npx 初始化：npx create-agent-skill init
4. 按照提示填写名称、描述、版本
5. 编辑 SKILL.md，写入指令
6. 编辑 manifest.json，配置元数据
7. 在 Agent 配置里注册这个 skill 路径
8. 重启 Agent 或重新加载配置

每一步都有坑。比如第 3 步，如果 npx 拉取包失败，可能是 registry 配置问题，检查npm config get registry。第 7 步，不同 Agent 的注册方式不一样，有的用配置文件，有的用环境变量，要看具体文档。

4.3 参数配置和调试技巧

skill 运行时的参数配置很关键。以网页提取 skill 为例，几个核心参数：

• timeout：单次请求超时时间，默认 30000 毫秒。如果目标网站慢，可以调大，但不要超过 60000，否则 Agent 会等太久。
• retry：失败重试次数，默认 2。对于不稳定的网站可以调到 3 到 5。
• userAgent：请求头里的 UA，有些网站会检查。不要用默认的，容易被识别为爬虫。
• outputFormat：输出格式，支持 markdown、json、text。根据后续处理需求选择。

调试时我习惯先用一个简单的测试页面跑通流程，再换真实目标。这样能快速定位是 skill 本身的问题还是目标网站的问题。

4.4 一个完整的实操记录

下面是我实际安装并运行“分镜生成”skill 的记录。这个 skill 的作用是根据一段文字描述自动生成分镜脚本。

第一步，从 GitHub 找到 skill 仓库，复制地址。第二步，用 npx 直接运行：

npx agent-skill install github:user/storyboard-skill

第三步，安装完成后，在 Agent 里加载：

/load-skill storyboard

第四步，输入测试文本：“一个年轻人在雨中奔跑，突然停下，抬头看天。”

第五步，Agent 输出分镜脚本，包含镜头编号、景别、画面描述、时长建议。

整个过程大约 3 分钟，其中安装占 1 分钟，生成占 2 分钟。生成质量取决于 skill 的指令写得够不够细。我后来自己改了一版 SKILL.md，把分镜的格式要求写得更具体，输出质量明显提升。

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

5.1 skill 加载失败的排查顺序

skill 加载失败是最常见的问题。我的排查顺序是：

1. 检查 manifest.json 格式是否正确，用npx jsonlint manifest.json验证
2. 检查 entry 指向的文件是否存在
3. 检查依赖是否安装完整，npm ls看有没有 missing
4. 检查权限声明是否完整
5. 查看 Agent 日志，通常会有具体错误信息

大部分加载失败都是 manifest.json 的问题，尤其是 JSON 格式错误和路径错误。

5.2 工具调用超时或返回异常

工具调用超时通常有三个原因：目标服务慢、网络问题、skill 内部逻辑有死循环。排查时先看日志里的耗时分布，确定是哪个环节慢。如果是网络问题，加代理配置（注意这里说的是正常的 HTTP 代理，用于企业内网环境）。如果是逻辑问题，在 skill 里加超时中断。

返回异常则要看返回值结构是否符合约定。Agent 对返回值的格式很敏感，如果 skill 返回了非预期的结构，Agent 可能无法解析。

5.3 多个 skill 冲突的处理

同时加载多个 skill 时，可能出现工具名冲突或上下文冲突。解决办法是给工具名加前缀，比如browser_screenshot和scanner_screenshot。上下文冲突则要通过 skill 的优先级配置来解决，让 Agent 知道在冲突时优先用哪个。

5.4 常见问题速查表

5.5 几个独家避坑技巧

第一，skill 的 SKILL.md 不要写太长，控制在 2000 字以内。太长了 Agent 读起来费劲，反而抓不住重点。

第二，每个 skill 只做一件事。我见过一个 skill 同时做浏览器操作、文件读写和网络请求，结果哪个都做不好。拆成三个独立 skill，组合使用效果更好。

第三，测试时用真实场景，不要只用 toy example。很多问题只有在真实数据量下才会暴露。

第四，版本管理要严格。skill 更新后要改 version，否则 Agent 可能加载旧版本。

第五，保留一份 skill 的备份。我有次改 SKILL.md 改坏了，又没有备份，只能重写。

6. 进阶玩法：skill 组合与自动化流水线

6.1 把多个 skill 串成工作流

单个 skill 的能力有限，但组合起来就很强。比如“自动挖洞”这个场景，可以组合三个 skill：信息收集 skill、漏洞扫描 skill、报告生成 skill。Agent 先加载信息收集 skill 拿到目标信息，再加载扫描 skill 做检测，最后用报告 skill 输出结果。

组合的关键是定义好 skill 之间的数据接口。前一个 skill 的输出格式要能被后一个 skill 识别。我通常用 JSON 作为中间格式，结构清晰，解析方便。

6.2 用 skill 做内容生产流水线

热搜里出现“分镜 skills 下载”“codex 写论文的 skills”，说明内容生产是 skill 的重要应用场景。我搭过一条流水线：选题 skill 生成选题，大纲 skill 生成大纲，写作 skill 生成初稿，润色 skill 做修改，最后排版 skill 输出成品。

这条流水线跑下来，一篇 3000 字的文章大约 10 分钟完成，人工只需要做最终审核。效率提升很明显，但前提是每个 skill 的指令要调好，否则生成的内容质量不稳定。

6.3 skill 的二次开发和定制

现成的 skill 不一定完全符合需求，二次开发很常见。改的时候注意几点：不要改 manifest.json 里的 name 和 version，否则可能和原 skill 冲突；改 SKILL.md 时要保留原有的触发条件，只改具体指令；新增工具时要同步更新 tools 列表和权限声明。

我一般会 fork 一份原 skill，改完后用自己的命名空间发布，这样既保留了原版，又有自己的定制版。

7. 我对这套东西的真实看法

用了这么久，我的体会是：Agent Skills 这套机制的价值不在于单个 skill 有多强，而在于它建立了一个可复用、可组合、可分发的能力生态。以前每做一个新任务都要重新写提示词，现在找到对应的 skill 加载就行，省下来的时间很可观。

但它也不是银弹。skill 的质量参差不齐，有些 skill 的指令写得很粗糙，用起来还不如自己写提示词。而且 skill 的调试成本不低，尤其是涉及外部工具调用的 skill，环境问题能占掉一半时间。

如果你刚开始接触，我的建议是先从最简单的 skill 入手，比如一个纯文本处理的 skill，跑通整个流程，理解 SKILL.md 和 manifest.json 的关系，再逐步尝试复杂的。不要一上来就搞浏览器自动化或者安全测试，那些坑太深，容易劝退。

另外，skill 的生态还在快速变化，今天好用的 skill 明天可能就过时了。保持关注 GitHub 上的更新，定期清理不再维护的 skill，别让它们拖慢你的 Agent。