企业官网建设流程全解析

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

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份简历上的技能罗列。但结合热搜词里反复出现的 Google Cloud、Agent Skills、GKE、Genkit，以及“claude agent skills”“codex skills”“skills开发”“skills安装包下载”这些词，可以确定这里说的 skills 不是人类的能力，而是给 AI Agent 使用的一套可插拔能力模块。简单说，它是一组结构化的指令、工具描述和资源文件，让一个通用的大模型在特定任务上表现得像一个受过训练的专才。

它解决的问题很具体：大模型本身什么都会一点，但什么都不精。你让它写代码，它能写，但不符合你团队的规范；你让它做数据分析，它能做，但不知道你公司的指标口径；你让它处理工单，它能处理，但不懂你的业务分类。skills 就是把这些“隐性知识”显性化、模块化，让 Agent 在需要的时候加载对应的能力包，而不是每次都在提示词里重复交代。

适合谁来参考？三类人最需要关注。第一类是AI 应用开发者，尤其是用 Genkit、LangChain 这类框架搭建 Agent 的人，skills 可以直接作为能力层复用。第二类是技术团队负责人，需要把团队内部的流程、规范、工具封装成 Agent 可调用的资产。第三类是重度 AI 工具用户，比如用 Claude、Codex 写代码或做研究的人，理解 skills 的结构后可以自己写一个专属技能包，把重复劳动压缩掉。

我自己的体会是，skills 这个概念之所以在最近半年集中爆发，是因为 Agent 从“能聊天”进入“能干活”阶段后，大家发现光靠提示词工程已经不够了。提示词是临时的、易失的、不可版本管理的，而 skills 是持久的、可复用的、可测试的。这个转变很像前端开发从写内联样式到组件化的过程，一旦你习惯了组件化，就再也回不去了。

2. 核心思路拆解：为什么是“技能包”而不是“大提示词”

2.1 从提示词堆砌到能力模块化

早期做 Agent 的人都有一个共同的痛点：提示词越写越长，最后变成几千字的“说明书”，模型还是经常漏掉关键步骤。原因很简单，上下文窗口是有限的，注意力也是有限的。你把所有规则都塞进一个系统提示里，模型在生成每个 token 时都要在全部规则里做一次隐式检索，噪声太大。

skills 的思路是把“什么时候用什么能力”和“这个能力具体怎么做”分开。主 Agent 只需要知道有哪些技能可用，以及每个技能的触发条件；具体执行时，再把对应技能的详细指令加载进来。这就像公司里的岗位职责和操作手册的关系：岗位职责告诉你找谁办事，操作手册告诉那个人具体怎么操作。你不会把全公司的操作手册发给每一个新员工，而是按需分发。

这个设计带来的直接好处是上下文利用率大幅提升。一个技能包通常只包含几十到几百行的指令，加上必要的工具定义和示例，加载后占用的 token 很少。而主 Agent 的系统提示可以保持精简，只保留路由逻辑和全局约束。实测下来，同样一个复杂任务，用技能包拆解后，模型出错的概率比单一大提示词低很多，尤其是在步骤超过五步的任务上。

2.2 技能包的三个核心组成

一个标准的 skill 通常包含三部分。第一部分是元数据，包括技能名称、描述、触发关键词、适用场景。这部分是给主 Agent 看的，用来判断是否加载这个技能。第二部分是指令正文，也就是这个技能具体怎么执行，包括步骤、注意事项、输出格式。第三部分是资源引用，比如需要调用的工具、需要读取的模板文件、需要参考的示例数据。

这三部分的分工很明确：元数据负责“被找到”，指令正文负责“被理解”，资源引用负责“被执行”。很多人在写 skill 时容易犯的错误是把所有内容都塞进指令正文，结果元数据写得含糊，主 Agent 根本不知道该在什么时候加载它。我的经验是，元数据里的描述要写得像一条搜索摘要，包含用户可能说的原话和同义词，这样路由才准。

2.3 与 GKE、Genkit 的关系

热搜词里出现 GKE 和 Genkit，说明 skills 的落地场景和 Google Cloud 的 Agent 生态有关。GKE 提供的是运行环境，Genkit 提供的是开发框架，而 skills 是跑在这个环境里的能力单元。你可以把 GKE 理解成厂房，Genkit 理解成生产线，skills 理解成一个个可替换的模具。模具设计得好，换产品的时候只需要换模具，不需要重建生产线。

这种分层的好处是技能可以独立迭代。今天发现某个技能的输出格式不对，只需要改那个技能包，重新部署即可，不影响其他技能。如果所有逻辑都写在一个大提示词里，改一处就可能影响全局，回归测试的成本极高。我在实际项目里吃过这个亏，一个提示词改了标点符号，结果另一个不相关的任务开始胡言乱语，排查了一整天才定位到。

3. 核心细节解析：一个 skill 到底怎么写

3.1 元数据的设计要点

元数据是 skill 的“门面”，决定了它能不能被正确调用。我通常会把元数据写成 YAML 格式，包含以下几个字段：name、description、triggers、version、author。name 用英文短横线命名，比如code-review-python，不要用空格或中文。description 用一句话说清楚这个技能做什么，以及什么时候用，最好包含用户可能说的关键词。

triggers 是一个列表，列出触发这个技能的典型用户输入。比如一个代码审查技能，triggers 可以写["review my code", "check this PR", "代码审查", "帮我看看这段代码"]。这里要注意中英文都要覆盖，因为用户可能混着说。version 字段很多人会忽略，但在团队协作里非常重要，技能更新后如果 Agent 还在用旧版本，输出会不一致。

提示：description 不要写成“这是一个用于代码审查的技能”，而要写成“当用户需要审查 Python 代码、检查代码规范、发现潜在 bug 时使用此技能”。前者是自我介绍，后者是使用说明，路由效果差别很大。

3.2 指令正文的结构化写法

指令正文是 skill 的核心，我建议用 Markdown 写，分成几个固定小节：目标、输入、步骤、输出格式、示例、边界情况。目标用一句话说明这个技能要达成什么。输入说明需要用户提供什么信息，如果缺失该怎么追问。步骤是最关键的部分，要写成有序列表，每一步都具体到可执行。

输出格式要明确，是 JSON、Markdown 表格还是纯文本。如果下游有程序解析，格式必须严格定义，包括字段名、类型、是否必填。示例部分给出一到两个完整的输入输出对，让模型有参照。边界情况列出这个技能不适用的情况，以及遇到时该怎么处理。很多人不写边界情况，结果模型在遇到异常输入时自由发挥，输出不可控。

我自己的习惯是在步骤里加入“检查点”，比如“完成第三步后，确认输出中是否包含所有必填字段，如果缺失则回到第二步补充”。这种自我校验的指令能显著降低错误率，尤其是多步骤任务。实测下来，加了检查点的技能，输出合格率能从七成提升到九成以上。

3.3 资源引用的组织方式

资源引用通常包括工具定义和静态文件。工具定义描述这个技能可以调用哪些外部函数，比如搜索、计算、读写文件。每个工具要写清楚名称、参数、返回值。静态文件包括模板、示例数据、参考文档，放在技能目录下的resources文件夹里，在指令正文中用相对路径引用。

这里有一个容易踩的坑：工具的参数描述要足够详细，否则模型会传错类型。比如一个日期参数，要写明格式是YYYY-MM-DD，而不是只说“日期”。我见过因为参数描述模糊导致模型传了“明天”这种自然语言，工具直接报错。另外，静态文件不要太大，单个文件建议不超过 100KB，否则加载时会占用过多上下文。

3.4 技能包的目录结构

一个可发布的 skill 包，目录结构建议如下：

my-skill/ ├── skill.yaml # 元数据 ├── instructions.md # 指令正文 ├── resources/ │ ├── template.md # 输出模板 │ └── examples.json # 示例数据 └── tools/ └── definitions.yaml # 工具定义

这个结构清晰，便于版本管理和分发。skill.yaml 是入口，instructions.md 是主体，resources 和 tools 是辅助。打包时整个目录压缩成一个文件，安装时解压到指定目录即可。热搜词里有人问“skills安装包下载”，其实指的就是这种打包好的技能包。

4. 实操过程：从零写一个可用的 skill

4.1 确定技能边界

动手之前先想清楚这个技能要解决什么问题，边界在哪里。不要写一个“万能助手”技能，那等于什么都没写。好的技能边界是：一个具体任务，有明确的输入和输出，执行步骤在十步以内。比如“把一段中文技术文档翻译成英文并保持 Markdown 格式”就是一个好边界，“帮我处理文档”就是坏边界。

我通常会用一句话测试边界是否清晰：如果我不能在三十秒内说清楚这个技能什么时候用、什么时候不用，那就说明边界还太模糊。模糊的技能会导致路由混乱，主 Agent 不知道该不该加载它，最后要么该用的时候没用，要么不该用的时候乱用。

4.2 编写元数据和指令

确定边界后，先写元数据。name 用英文，description 用中英文各写一遍，triggers 列出至少五个典型输入。然后写指令正文，按照目标、输入、步骤、输出格式、示例、边界情况的顺序。步骤要写得像给一个新同事的交接文档，假设对方很聪明但完全不了解你的业务。

写完后自己读一遍，问三个问题：第一步是否足够具体？中间步骤是否有检查点？输出格式是否可验证？如果任何一个答案是否定的，回去改。我一般会改三遍以上，第一遍写逻辑，第二遍补细节，第三遍删冗余。删冗余很重要，指令越长，模型越容易忽略后面的内容。

4.3 本地测试与迭代

写完后不要直接发布，先在本地测试。测试方法是构造十个典型输入，包括正常输入、边界输入和异常输入，看输出是否符合预期。正常输入检验基本功能，边界输入检验鲁棒性，异常输入检验错误处理。每次测试记录输出，对比预期，找出偏差。

迭代时优先改指令正文，而不是改元数据。因为元数据影响的是路由，指令影响的是执行。如果路由对了但执行错了，改指令；如果路由错了，改元数据。我见过有人执行出错就去改 triggers，结果越改越乱。定位问题要看是“没被调用”还是“调用了但做错了”，这两个问题的解法完全不同。

4.4 发布与版本管理

测试通过后，给技能打上版本号，比如1.0.0。版本号遵循语义化版本规范：主版本号变更是因为不兼容的修改，次版本号变更是因为新增功能，修订号变更是因为修复 bug。发布时把整个目录打包，附上变更日志。变更日志要写清楚改了什么、为什么改、影响范围。

团队协作时，建议把技能包放在 Git 仓库里管理，每个技能一个目录，用分支做开发，用标签做发布。这样任何人想用某个技能，直接 checkout 对应标签即可。热搜词里有人问“skills下载平台有哪些”，其实最可靠的方式就是团队自建一个 Git 仓库，内部技能内部管理，比去外部平台找更安全也更贴合业务。

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

5.1 技能不被调用怎么办

这是最常见的问题。表现是用户明明说了触发词，但主 Agent 没有加载对应技能。排查顺序如下：先看元数据里的 triggers 是否包含用户说的原话，如果不包含，加上；再看 description 是否太抽象，如果是，改具体；最后看主 Agent 的系统提示里是否给了技能路由足够的优先级，如果没有，调整路由指令。

我遇到过一次，用户说“帮我审一下这段代码”，triggers 里写的是“代码审查”，结果没匹配上。后来把“审一下”“看看代码”“检查代码”都加进去，问题解决。所以 triggers 要尽量覆盖口语化表达，不要只写书面语。

5.2 技能被调用了但输出不对

如果路由正确但输出不符合预期，问题通常出在指令正文。排查顺序：先看步骤是否足够具体，如果某一步是“处理数据”，那太模糊，要改成“读取 CSV 文件，按日期列排序，计算每日均值”；再看输出格式是否明确定义，如果没有，加上；最后看是否有检查点，如果没有，在关键步骤后加自我校验。

还有一种情况是模型能力不足。有些技能需要较强的推理能力，如果底层模型较弱，即使指令写得再好也执行不了。这时候要么换更强的模型，要么把技能拆得更细，降低单步复杂度。

5.3 多个技能冲突怎么办

当两个技能的 triggers 有重叠时，主 Agent 可能不知道该加载哪个。解决方法是给技能加优先级字段，或者在 description 里写清楚适用场景的差异。比如一个“代码审查”技能和一个“代码重构”技能，triggers 都包含“改代码”，那就需要在 description 里区分：前者用于发现问题，后者用于实施修改。

更彻底的做法是合并技能，把两个技能合成一个，在指令正文里用条件分支处理不同场景。但合并会让技能变复杂，所以只在冲突频繁发生时才这么做。我的一般原则是：宁可技能多一点、每个简单一点，也不要一个大技能包打天下。

5.4 常见问题速查表

注意：排查时不要同时改多个地方，一次只改一个变量，改完立即测试。否则你无法判断是哪个改动起了作用。

6. 进阶技巧：让 skills 真正产生复利

6.1 技能组合与编排

单个技能解决单点问题，多个技能组合起来才能解决复杂任务。组合的方式有两种：串行和并行。串行是前一个技能的输出作为后一个技能的输入，比如“数据清洗”技能输出干净数据，“数据分析”技能接收后生成报告。并行是多个技能同时执行，最后汇总结果，比如“竞品分析”技能同时调用“搜索”“摘要”“对比”三个子技能。

编排的关键是定义清楚技能之间的接口。输出格式要严格，字段名要一致，否则下游技能解析不了。我通常会在技能包里加一个interface.yaml，声明这个技能接收什么、输出什么，方便编排时做类型检查。

6.2 技能的市场化与复用

当团队积累了一定数量的技能后，可以建一个内部技能市场，让每个人都能搜索、安装、评价技能。市场化的好处是避免重复造轮子，一个人写好的技能，全团队都能用。评价机制能筛选出高质量技能，低质量技能自然被淘汰。

市场化要注意权限管理。有些技能涉及敏感数据或内部流程，不能对所有人生效。建议给技能加访问控制标签，比如public、team-only、private，安装时校验权限。热搜词里有人问“skills推荐”，其实最好的推荐来自团队内部的使用数据，哪个技能被安装最多、评价最高，就是最好的推荐。

6.3 技能的可观测性

技能上线后要能观测运行情况，包括调用次数、成功率、平均耗时、错误分布。这些数据能帮你判断哪个技能需要优化。调用次数高但成功率低的技能，优先优化；调用次数低但成功率高的技能，可能是 triggers 没写好，需要推广。

我一般会在技能包里加一个轻量的日志埋点，记录每次调用的输入摘要、输出摘要、耗时、是否成功。日志不要记录完整输入输出，避免隐私问题，只记录哈希值和长度即可。这些数据汇总后，能画出技能的健康度仪表盘，一眼看出问题所在。

6.4 从 skills 到 Agent 能力体系

单个技能是点，技能组合是线，能力体系是面。当技能数量超过二十个时，就需要考虑分类和分层。我通常按业务域分类，比如“研发效能”“数据分析”“客户支持”，每个域下再按任务类型分层。这样主 Agent 路由时可以先选域，再选技能，降低路由复杂度。

能力体系的最终形态是：主 Agent 只负责理解用户意图和路由，具体执行全部下沉到技能层。主 Agent 的系统提示可以控制在几百字以内，技能包各自独立迭代。这种架构的可维护性远高于单体提示词，也是我认为 skills 这个概念最有价值的地方。

7. 我踩过的坑与最后分享

最早接触 skills 时，我把它当成提示词模板来写，结果发现路由总是不准。后来才明白，skills 的核心不是“写得多好”，而是“被找到”和“被正确执行”这两件事。元数据决定被找到，指令正文决定被正确执行，两者缺一不可。很多人只重视指令正文，忽略元数据，最后技能写得再好也没人用。

另一个坑是过度设计。我一开始想写一个“全能技能”，把所有可能的情况都覆盖进去，结果指令正文写了三千字，模型反而抓不住重点。后来拆成五个小技能，每个三百字，效果反而更好。技能要像 Unix 工具，每个只做一件事，做好一件事，然后通过组合解决复杂问题。

最后分享一个小技巧：写技能时，把模型当成一个聪明但完全不了解你业务的新人。你不会跟新人说“处理一下数据”，你会说“打开这个 CSV，按日期排序，算每天的平均值，输出成表格”。技能指令也要写到这个粒度。我试过把同一份逻辑分别写成“粗粒度”和“细粒度”两个版本，细粒度版本的输出合格率高出四成。这个投入是值得的，因为技能写一次，后面会被调用无数次。