企业官网建设流程全解析

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

第一次看到“skills”这个标题，很多人会以为是某个泛泛的能力清单，或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、npx、GKE、claude agent skills、codex skills 这些词，基本可以确定，这里说的 skills 不是人类的能力，而是给 AI Agent 用的技能包——一套可安装、可调用、可复用的能力模块。

打个比方，大模型本身像一个刚毕业的高材生，脑子好使，但没上过班，不知道你们公司的报销流程、代码规范、部署方式。Agent Skills 就是给这个高材生发的“员工手册 + 工具箱”，让它知道遇到某类任务时该调用哪个流程、哪个脚本、哪个模板。它解决的核心问题是：把一次性的提示词工程，沉淀成可版本管理、可分发、可组合的标准化能力单元。

这套东西适合谁？三类人最该关注。第一类是天天写 prompt 的前端和全栈开发者，你已经受够了每次都要复制粘贴一大段上下文；第二类是搞 AI 应用落地的工程师，需要把模型能力接进真实业务流程；第三类是技术博主和工具党，喜欢折腾新东西，想第一时间搞清楚 Agent Skills 的安装、开发和分发逻辑。这篇文章我会从设计思路、核心机制、实操安装、开发流程到踩坑排查，完整讲一遍，尽量让你看完就能自己动手做一个 skill。

需要先说明一点：Agent Skills 目前还在快速演进，不同平台（Claude、Codex、Google Cloud 相关工具链）的实现细节有差异。下面涉及具体命令和目录结构的部分，我会以最常见的约定为主，同时标注哪些地方需要你按自己所用平台的文档核对。这是基于常见实践的合理补全，不是唯一标准答案。

2. Agent Skills 的整体设计与思路拆解

2.1 为什么需要 Skills 而不是继续堆 Prompt

先说一个我自己的真实感受。早期做 AI 应用，所有逻辑都塞在 system prompt 里，一个 prompt 写到三千字，改一个标点都要重新测一遍回归。后来发现，这种做法的根本问题是耦合：知识、流程、工具调用、输出格式全搅在一起，没法单独维护。

Agent Skills 的设计思路，本质上是软件工程里的“关注点分离”搬到了 AI 能力层。一个 skill 通常包含几块东西：一段描述这个技能干什么的元数据、一份指导模型如何思考和操作的指令、若干可选的脚本或资源文件。模型在运行时，先看有哪些 skill 可用，判断当前任务该不该触发某个 skill，触发后再加载对应的详细指令。

这样做的好处很直接。第一，上下文按需加载。你不需要把所有能力都塞进每一次对话的上下文里，只在需要时才把某个 skill 的完整内容拉进来，省 token 也更聚焦。第二，能力可组合。一个负责“读取数据库”的 skill 和一个负责“生成报表”的 skill 可以串起来用，各自独立演进。第三，可分发。skill 可以打包、可以放到市场、可以用 npx 一键安装，这就从“个人技巧”变成了“团队资产”。

2.2 一个 Skill 的典型结构长什么样

虽然不同平台细节不同，但一个 skill 的骨架高度相似。通常是一个目录，里面有一个主描述文件（常见命名是 SKILL.md 或类似的清单文件），加上可选的脚本、模板、参考文档。主文件一般分两段：前面是元信息，比如名称、描述、触发条件；后面是给模型看的操作指令。

我拿一个“生成周报”的 skill 举例。元信息里写清楚：这个 skill 叫 weekly-report，当用户提到“周报”“本周总结”“汇报”这类词时考虑触发。指令部分则告诉模型：先读取本周的 git commit 记录，再按“完成事项 / 进行中 / 风险”三段式组织，最后输出 Markdown。如果还需要调用脚本去拉 commit，就放一个 scripts 目录，里面塞一个取日志的脚本。

这里有个关键设计点值得展开：描述字段的写法直接决定 skill 会不会被正确触发。写得太窄，模型永远想不起来用它；写得太宽，什么任务都往里套，反而干扰判断。我的经验是，描述里要同时包含“做什么”和“什么时候用”，并且用具体的名词而不是抽象概念。比如写“处理数据”就不如写“把 CSV 文件转换成统计图表并输出 PNG”来得有效。

2.3 和 MCP、插件、函数调用是什么关系

热搜里出现了 claude mcpservers npx 这类词，说明很多人会把 Agent Skills 和 MCP（Model Context Protocol）搞混。我用一句话区分：MCP 解决的是“模型怎么连上外部工具和数据源”，Skills 解决的是“模型知道该怎么做事”。

MCP 更像一根标准化的数据线，让模型能安全地访问文件系统、数据库、第三方 API。而 skill 是操作规程，它可能用到 MCP 提供的连接能力，也可能只是纯文本的指令。举个例子，MCP 让模型能读到你本地的文件，但“读完之后按什么格式整理成会议纪要”这件事，是 skill 负责的。两者是互补关系，不是替代关系。

至于传统的函数调用（function calling），它更底层，是模型输出一个结构化调用的机制。skill 可以封装一组函数调用，把它变成一个有语义的完整能力。你可以理解为：函数调用是螺丝刀，MCP 是电源插座，skill 是“如何组装这台机器”的说明书。

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

3.1 安装方式：npx 一键装与手动放置的区别

热搜里 npx 出现频率很高，还有“npx playwright install 失败”这种具体报错，说明大家最关心的就是怎么把 skill 装起来。目前主流的安装方式有两种。

第一种是命令行一键安装，典型形式是npx some-skill-cli install <skill-name>。这种方式的好处是自动处理依赖、自动放到正确的目录、自动更新清单。坏处是它依赖网络和 npm 生态，一旦网络抖动或者包本身有问题，就会卡住。playwright install 失败就是典型例子，它其实是在下载浏览器二进制，跟 skill 本身关系不大，但会让人误以为是 skill 装不上。

第二种是手动放置。你从 GitHub 或者某个 skills 市场下载一个压缩包或目录，解压后放到约定的 skills 目录里。这个目录的位置因平台而异，常见的是项目根目录下的.skills/或者用户主目录下的配置文件夹。手动装的好处是完全可控，坏处是容易放错位置、漏掉依赖。

我个人的建议是：先用一键安装跑通流程，再研究它到底把文件放哪了。你可以在安装后去对应目录看一眼结构，这样既省事又长知识。如果一键安装失败，再退回手动方式，反而更快。

3.2 目录约定与命名规范

不管你用哪个平台，有几条命名和目录的约定是通用的，踩过坑的人都知道这些细节有多重要。

• skill 名称用小写字母加连字符，比如weekly-report、csv-to-chart，不要用空格、下划线或大写，很多加载器对大小写敏感。
• 主描述文件的命名要严格按平台要求，有的要求SKILL.md，有的要求skill.yaml，写错了直接不识别。
• 脚本目录建议统一叫scripts，模板叫templates，参考文档叫references，这样别人接手时一眼能看懂。
• 如果 skill 需要读取外部文件，路径尽量用相对路径，并且明确说明相对于哪个基准目录。

注意：目录名里千万不要出现中文或特殊符号。我见过有人把 skill 目录命名成“周报生成”，结果加载器直接报找不到，排查了半小时才发现是编码问题。

3.3 描述字段与触发条件的写法

这是整个 skill 开发里最考验功力的一环。模型判断要不要用某个 skill，主要靠描述字段的语义匹配。写得好，模型该用的时候用、不该用的时候不碰；写得差，要么永远不触发，要么到处乱触发。

我的写法套路是“三段式”：能力范围 + 触发场景 + 边界说明。举个例子：

name: csv-to-chart description: 把 CSV 数据文件转换成统计图表。当用户提供 CSV 文件路径并希望得到可视化图表、趋势图或对比图时使用。不适用于实时数据流或需要交互式图表的场景。

这里“不适用于”那句就是边界说明，能有效防止模型在错误场景下硬套。很多人写描述只写正面能力，结果模型在完全不相关的任务上也尝试调用，反而添乱。

3.4 指令部分的组织：给模型看的“操作手册”

指令部分是 skill 的灵魂。它不是写给人类看的文档，而是写给模型看的操作指南。所以写法上要步骤化、具体化、可执行。我一般按这个结构组织：

1. 先说明这个 skill 的目标和最终产出是什么。
2. 列出执行步骤，每一步说清楚输入、操作、输出。
3. 给出输出格式的模板或示例。
4. 列出常见错误和应对方式。

关键技巧是：多用祈使句，少用描述句。写“读取文件”比写“模型应该读取文件”更有效。另外，如果某一步需要调用脚本，要明确写出脚本路径和参数格式，比如运行 scripts/fetch_commits.sh，参数为起始日期。

4. 从零开发一个 Skill 的完整实操

4.1 环境准备与依赖确认

动手之前，先把环境理清楚。你需要的东西不多，但每一样都要确认版本。

• Node.js 环境，因为很多安装工具是 npm 包，建议用 LTS 版本。用node -v确认。
• 一个可用的 AI Agent 运行环境，比如支持 skills 的客户端或 CLI 工具。
• 一个代码编辑器，VS Code 就够。
• 如果要写脚本，确认对应的运行时，比如 Python 或 Bash。

我建议单独建一个工作目录来开发 skill，不要直接在正式项目里改。因为开发过程中会反复安装、卸载、测试，混在一起容易污染项目配置。建好目录后，先跑一次npx <对应工具> --version确认工具链可用，再开始。

4.2 创建 Skill 骨架

假设我们要做一个“把 git 提交记录整理成周报”的 skill，名字叫git-weekly-report。第一步是建目录结构：

mkdir -p git-weekly-report/scripts cd git-weekly-report touch SKILL.md

然后写 SKILL.md 的元信息部分。这里要注意，不同平台对字段名要求不同，常见的有name、description，有的还要求version、author。我一般会先查一下所用平台的模板，照着填，避免字段名写错导致加载失败。

元信息写完后，开始写指令部分。我会先写一个最简版本，只包含“读取 git log、按三段式整理、输出 Markdown”这三步，先跑通再说。不要一上来就追求完美，先让 skill 能被触发、能产出东西，再迭代细节。

4.3 编写核心脚本与参数处理

如果 skill 需要执行实际操作，比如拉取 git 日志，就要写脚本。我用 Bash 写一个最简单的：

#!/bin/bash # scripts/fetch_commits.sh # 参数1：起始日期，格式 YYYY-MM-DD START_DATE=$1 if [ -z "$START_DATE" ]; then echo "错误：请提供起始日期" exit 1 fi git log --since="$START_DATE" --pretty=format:"%h %s" --no-merges

这个脚本做了三件事：接收日期参数、校验参数非空、输出格式化的提交记录。参数校验这一步很多人会省，结果模型传了个空值进来，脚本默默输出全部历史，周报就变成了年度总结。所以脚本入口一定要做参数校验，这是血泪教训。

然后在 SKILL.md 的指令里明确写：调用scripts/fetch_commits.sh，传入本周起始日期。模型看到这条指令，就会在合适的时候去执行。

4.4 本地测试与触发验证

写完骨架后，最关键的一步是测试。测试分两层：能不能被触发，和触发后做得对不对。

第一层测试，我会在对话里输入几种不同的说法，看模型是否在正确的时机调用这个 skill。比如输入“帮我整理一下这周的提交记录”，应该触发；输入“今天天气怎么样”，不应该触发。如果该触发没触发，多半是描述字段写得太窄；如果乱触发，多半是描述太宽或者边界没写清楚。

第二层测试，看输出质量。我会故意给一些边界情况，比如本周没有任何提交、提交信息里有特殊字符、日期格式不对。观察 skill 是优雅处理还是直接崩掉。这一步能暴露大量问题，比事后在真实场景里翻车强得多。

提示：测试时把每次的输入和输出记下来，形成一个小的测试用例集。以后改 skill 时，拿这套用例回归一遍，能避免改好一个场景、弄坏另一个场景。

4.5 打包与分发

测试通过后，如果想让别人也能用，就要考虑打包。最简单的分发方式是把整个目录压缩，别人解压放到 skills 目录即可。更规范的方式是发布到 npm 或者某个 skills 市场，让别人用 npx 一键安装。

发布到 npm 的话，需要在 package.json 里配置好 bin 字段，让安装命令能正确执行。这一步的坑在于：包名要全局唯一，而且要考虑别人安装时的目录权限问题。我建议先在本地用npm pack打包，再用npm install <本地包路径>模拟安装一遍，确认没问题再发布。

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

5.1 安装类问题速查

安装环节是报错重灾区，我把常见问题和排查思路整理成表，方便对照。

playwright install 失败这类问题，本质是二进制下载环节的问题，跟 skill 逻辑无关。遇到这种，先确认是不是网络或镜像源的问题，不要急着怀疑 skill 本身。

5.2 触发类问题：该用的时候不用，不该用的时候乱用

这是最让人头疼的一类问题，因为它没有明确报错，只能靠观察。我的排查顺序是：

先看描述字段。把 description 单独拿出来读一遍，问自己：如果我是模型，看到这段描述，能判断出什么时候该用吗？如果答案模糊，那就是描述的问题。

再看指令部分有没有冲突。有时候两个 skill 的描述高度重叠，模型就会犹豫或者随机选一个。这时候要么合并，要么把边界写得更清楚。

最后看上下文长度。如果对话已经很长，模型可能“忘记”了还有这个 skill 可用。这种情况可以考虑把 skill 的触发提示放在更靠前的位置，或者精简其他上下文。

5.3 输出质量不稳定的应对

同一个 skill，有时候输出很好，有时候一塌糊涂，这种波动很常见。原因通常有三个：指令不够具体、缺少输出示例、模型本身的随机性。

我的应对办法是加示例。在指令部分给出一个完整的输入输出示例，模型照着模仿的准确率会明显提升。另外，把输出格式用模板固定下来，比如明确要求“必须包含三个二级标题，分别是完成事项、进行中、风险”，比笼统说“按三段式组织”要稳得多。

如果还是不稳定，可以考虑在脚本层面做更多处理，把格式约束从“靠模型自觉”变成“靠代码保证”。比如让脚本直接输出结构化数据，模型只负责润色，这样波动就小很多。

5.4 几个我踩过的坑

第一个坑是路径写死。早期我在指令里写了绝对路径，结果换台机器就找不到文件。后来全部改成相对路径，并且明确说明基准目录，才解决。

第二个坑是忽略编码。脚本输出的中文在某些环境下会乱码，导致模型读到的是乱码，输出自然也是乱的。解决办法是在脚本里显式设置 UTF-8 编码。

第三个坑是过度依赖模型判断。我一开始觉得模型很聪明，什么都能自己判断，结果发现它在边界情况上经常出错。后来我把能确定的逻辑都下沉到脚本里，模型只做它擅长的语言组织和判断，稳定性立刻上来了。

6. Skills 的进阶玩法与生态观察

6.1 组合多个 Skill 完成复杂任务

单个 skill 能力有限，真正的威力在于组合。比如一个“竞品分析”任务，可以拆成三个 skill：一个负责抓取公开信息，一个负责结构化整理，一个负责生成对比报告。模型按顺序调用，每个 skill 各司其职。

组合的关键是接口约定。前一个 skill 的输出格式，要正好是后一个 skill 能接受的输入格式。这跟微服务之间的接口设计是一个道理。我一般会在 skill 的指令里明确写出“输出为 JSON，字段包括 xxx”，这样下游 skill 就能稳定解析。

6.2 从 GitHub 和社区获取现成 Skill

热搜里 github skills、skills 大全、skills 推荐这些词说明大家很想要现成的。目前社区里确实有不少开源 skill 集合，覆盖代码审查、文档生成、数据分析等场景。获取渠道主要是 GitHub 仓库和各类 skills 市场。

我的建议是：先看再改，不要直接用。别人的 skill 是针对他的场景写的，直接拿来可能水土不服。正确做法是下载后读一遍指令和脚本，理解它的设计意图，再按自己的需求调整。这个过程本身也是学习 skill 开发的好机会。

6.3 安全与权限的边界意识

skill 能调用脚本、能读文件，这就带来了权限问题。一个来路不明的 skill，理论上可以执行任意脚本。所以只安装可信来源的 skill，安装前看一眼脚本内容，这是基本的安全习惯。

另外，涉及敏感数据的 skill，要确认它的数据处理方式。比如它会不会把数据发到外部服务，会不会在本地留下缓存。这些在正式使用前都要搞清楚。我个人的做法是，涉及内部数据的 skill，一律自己写或者经过代码审查后再用，不直接装第三方的。

6.4 这个方向接下来会怎么走

从目前的趋势看，Agent Skills 正在从“个人技巧”走向“标准化资产”。未来可能会出现更统一的描述规范、更完善的依赖管理、更细粒度的权限控制。对开发者来说，现在投入时间学 skill 开发，相当于早期学 Docker 或者早期学 npm，回报是比较确定的。

我自己的判断是，skill 的编写能力会逐渐成为 AI 应用开发者的基本功，就像今天写函数、写接口一样自然。早点上手，早点积累自己的 skill 库，这个复利效应会越来越明显。

最后分享一个我自己的小习惯：每当我发现自己在对话里重复写某段提示词超过三次，我就会停下来，把它抽成一个 skill。这个习惯帮我攒下了一套真正用得上的能力库，而不是一堆装了没用的摆设。skill 这东西，贵精不贵多，能解决你实际问题的才是好 skill。