企业官网建设流程全解析

Agents 的能力这两年卷得很厉害，但我发现很多人对Agent Skill的理解还停留在"给 Prompt 加个文件"的层面。我最近在调一个 agent 项目时，把一份几十页的产品手册直接塞进系统提示词，结果上下文窗口被吃干抹净，回答问题时经常把 A 模块的规则套到 B 模块上；后来换成SKILL.md的方式，按技能包拆开、按需加载，同样的模型瞬间就靠谱多了。这篇文章我想把 Skill 这东西从头讲透：SKILL.md 到底是什么、渐进式披露（Progressive Disclosure）是怎么工作的、它和 Agent / 工具（MCP）的边界在哪，最后分享一批我实测过、真正能提升效率的 Skill 清单。无论你是刚开始接触 Agent 开发的小白，还是已经被 Prompt 工程折磨过一阵子的老手，这篇都能给你一套可落地的参考。

1. 为什么需要 Skill：从"临时提示词"到"可复用的技能包"

1.1 先还原一个我踩过的坑

上个月我在做一个内部文档问答 Agent，最开始的方案非常朴素：把所有产品操作手册、FAQ、历史故障记录全部拼进 System Prompt，觉得"信息给的越多，模型回答越准"。结果上线后状况百出——上下文被塞满，模型不仅越来越"健忘"，还经常把不同业务的规则混在一起回答。最典型的一次，用户问退款流程，模型居然引用了发票开具章节里的操作步骤。

后来我把手册拆成了十几个功能模块，每个模块对应一个 Skill 目录，目录里写清楚适用场景和使用步骤。改造之后模型表现立刻稳定了很多。这件事让我意识到一个关键问题：给 Agent 喂信息的方式，比信息本身更重要。你一股脑塞给它的信息，它根本不知道什么时候该用哪一部分；但当成技能包挂载后，它自己会判断"当前问题激活哪个技能"。

1.2 Skill 要解决的是"知识复用"和"注意力的按需分配"

如果你写过大模型应用，应该能感受到一个矛盾：既能给模型无限的背景知识，又希望它把有限的上下文窗口花在刀刃上。Skill 本质上是一套"知识打包 + 按需加载"的工程方案。

我用一个生活化的类比来解释。你面前放着一本 800 页的菜谱，你找"红烧肉"的做法时，不会把整本书背下来，而是先翻目录找到页码，再跳到那一页只读菜谱内容。Agent 处理 Skill 也是这个思路：

• 你在 Agent 环境里挂载了一堆 Skill 包；
• Agent 接到用户问题时，先读每个技能包的简短描述（相当于菜谱目录）；
• 它判断哪个技能包可能匹配当前任务，再打开那个技能包的 SKILL.md，看里面的具体步骤和示例；
• 只读取实际用到的细节，其余内容继续留在磁盘上，不占上下文。

这套机制的直接收益有两个。第一，知识可以复用了，同一份技能包可以在无数个对话任务里反复挂载，不需要每次手写一长串 Prompt；第二，上下文更省了，模型只在需要时读取细节，推理质量自然比"满屏信息噪音"高出不少。

1.3 Skill 不是提示词模板，也不是普通文档

很多人把 Skill 看成"复杂版的 Prompt 模板"，这个理解不准确。提示词模板是一次性粘贴给模型看的文本，它没有"入口描述"和"内部结构"的概念；而 Skill 是一个结构化的知识单元，至少包含两层信息：

• 对外入口：一段很短的描述，告诉 Agent "我是什么、适合做什么"，Agent 据此决定是否唤起这个技能；
• 对内细节：一份拆成若干小节的 SKILL.md，按需读取。它就像是一个带目录和索引的小型技术文档，而不是平铺直叙的一堆文本。

另外，普通文档是给人读的，可以自由组织语言；SKILL.md 是给模型读的，它要让模型在"低开销扫描"和"高精度执行"之间找到平衡。写法和排版都有讲究，这才是 Skill 设计真正有技术含量的地方。

2. SKILL.md 到底长什么样：文件结构解剖

2.1 一个 Skill 包的标准目录

Skill 的实现方式在不同框架里略有差异，但核心构成基本一致。我以目前比较常见、社区认可度也比较高的 Claude Agent Skills 规范为例，一个标准的 Skill 包通常长这样：

my-skill/ ├── SKILL.md # 技能描述文件，Agent 主要读取这个 ├── scripts/ # 辅助脚本，按需执行 │ └── format.py ├── templates/ # 模板文件，生成内容时引用 │ └── report_template.md └── references/ # 深度参考文档，只在特定场景读取 └── database_schema.md

SKILL.md是这个技能包的门面，文件名固定、放在根目录下。Agent 框架通常会扫描技能包目录，读取SKILL.md的头部信息，作为技能索引。其余的scripts/、templates/、references/都是辅助资源，Agent 只有在真正需要它们的时候才会去触碰。

2.2 frontmatter 里的元信息为什么重要

打开任意一份SKILL.md，开头通常是一段 YAML 格式的 frontmatter：

--- name: sql-query-optimization description: 用于对慢查询进行性能分析和索引优化。当用户提供执行计划或怀疑 SQL 查询缓慢时使用。不要用于表结构设计。 ---

name是技能的唯一标识，通常用中划线连接的小写英文；description是 Agent 判断"什么时候该用这个技能"的唯一依据。这段描述写得好不好，直接决定整体效果。

我总结出两个容易踩的坑：

• 描述太宽泛。比如"用于 SQL 问题"，Agent 可能在写建表语句、生成 ORM 代码时也去激活这个技能，导致答非所问。正例应该写明"当用户提供执行计划或怀疑 SQL 查询缓慢时使用"这种触发条件。
• 描述没写边界。可以适当加一句"不要用于表结构设计"，防止 Agent 在相关但不该用的场景下乱调用。给模型划清边界，它反而会更听话。

一段时间之后你会发现，调模型很多时候不是在调模型本身，而是在调这段 description 的措辞。它就像插件市场的简介文案，直接影响"能不能被用户在合适的时机搜到"。

2.3 body 内容怎么写才算合格

frontmatter 后面的正文部分，是模型真正执行时参考的"手艺手册"。正文写作有几个关键原则：

• 按场景分小节，每个小节一个 H2 或 H3 标题。比如"### 2.1 识别慢查询来源""### 2.2 索引选择建议""### 2.3 改写 SQL 示例"。模型扫描时会先看标题，再决定进哪个小节细读，这正好契合渐进式披露的机制。
• 步骤要具体，给出"输入 -> 操作 -> 输出"链路。不要写"对查询进行优化"这种废话，要写"从 EXPLAIN ANALYZE 输出中识别 seq scan 操作，若命中且表行数超过 100 万，考虑添加覆盖索引"。
• 给示例，而且给带输入输出的示例。模型对示例的模仿能力远强于对抽象规则的理解，这一点和人类学习很相似。
• 控制单文件体量。我建议一份 SKILL.md 控制在 200 行以内，如果超过，说明内容过载，考虑拆成多个 Skill 或者把深层内容移到 references/ 目录。

2.4 附带脚本、模板、参考文档的正确组织方式

当技能包里的知识量比较大时，不要硬往 SKILL.md 里塞代码表或完整模板，利用辅助目录是更优做法：

• scripts/：放可执行的脚本，比如数据处理脚本、文本格式化脚本。注意脚本尽量不要有交互式输入，否则 Agent 调用时容易卡住；把参数通过命令行传入更稳妥。
• templates/：放输出模板，比如周报模板、SQL 生成模板、代码提交说明模板。Agent 生成内容时会把模板读出来填充变量。
• references/：放深度参考文档，适用于"大部分时候用不到但一用就要命"的场景，比如完整数据库 Schema、历史故障复盘。这类内容体积大、使用频率低，放在子目录里让 Agent 按需读取，能有效绕开上下文窗口的限制。

我在实际项目中见过很多人把几千行的完整开源项目代码塞进 SKILL.md，这基本是灾难。模型为了看其中一个小函数，就不得不把上下文大部分空间让给无关代码。更好的做法是：SKILL.md 里只写"如何定位相关文件、如何修改"，具体代码用脚本去检索。

3. 渐进式披露：让 Agent 只看到该看到的东西

3.1 渐进式披露的核心理念

渐进式披露（Progressive Disclosure）是 Skill 设计中最核心、也最容易被忽略的部分。这个词最早来自 UX 设计领域，意思是"用户界面不应该一次性展示所有信息，而是根据用户当前需要，逐层暴露更多细节"。

放到 Agent Skill 的场景下，它的含义是：Agent 不应该一次性把技能包里的所有内容全部吞进去，而是应该从简短摘要开始，一层一层深入，直到拿到解决当前问题所需的信息。这和人类上手新工具的逻辑一致——先看说明书目录，再翻到对应章节，只在必要时阅读故障排除部分。

3.2 一次调用中的完整披露流程

我试着模拟一下，Agent 处理带 Skill 的任务时，内部大致走了这么几步：

1. 用户提问："我这条 SQL 查了 3 秒，怎么优化？"
2. Agent 扫描已挂载技能包的 description 索引，发现sql-query-optimization的描述命中"查询缓慢"关键词。
3. Agent 打开这个技能包的 SKILL.md，先读一遍所有 H2/H3 标题，形成"这个技能里有识别慢查询、索引选择、SQL 改写这几个部分"的整体印象。
4. Agent 判断当前任务是"识别慢查询来源"，于是只精读"### 2.1 识别慢查询来源"小节，拿到具体的 EXPLAIN 分析步骤。
5. 执行完第一步后，如果需要改索引，它再回头读"### 2.2 索引选择建议"小节。
6. 所有操作完成后，SKILL.md 的其他小节内容可能从头到尾都没被读取，也就没浪费任何上下文窗口。

这个"扫描 -> 定位 -> 精读"的过程，就是渐进式披露在运行时的真实流转。它能成立的前提是：SKILL.md 本身必须结构清晰，所有标题和信息点都能被快速扫描。

3.3 一个档案袋式的例子：文献检索 Skill

为了把这个概念讲得更落体，我举一个文献检索技能包的例子。假设我们有一个academic-paper-research的 Skill，它的 SKILL.md 开头是：

--- name: academic-paper-research description: 用于中英文学术文献检索与综述整理。当用户需要查找论文、总结研究进展、梳理某个领域学术脉络时使用。不要用于写代码或日常信息查询。 --- # 学术论文检索与研究助手 ## 1. 检索策略设计 - 根据用户给定主题，提取 3-5 组检索关键词 - 优先使用期刊数据库和预印本平台（如 arXiv、CNKI、Web of Science） - 按"标题/摘要/全文"三级匹配度筛选 ## 2. 文献筛选标准 - 优先近 3 年文献，历史经典文献单独标注 - 按被引次数、发表期刊影响因子、作者团队相关性排序 ## 3. 综述写作框架 - 背景：该领域为什么重要 - 进展：近五年有哪些代表性工作 - 争议：当前研究存在哪些分歧 - 展望：下一步可能的方向

当用户说"帮我调研一下大语言模型推理加速的最近进展"时，Agent 第一轮会读到"检索策略设计"，然后产出几组关键词并开始检索；搜到的文献列表出来后，它再回到 SKILL.md 读"文献筛选标准"小节，对结果排序；等到需要产出一份综述时，它才去读"综述写作框架"。

整个过程中，这个 SKILL.md 文件始终只有几十行，对 Agent 来说简直是轻量级负担。但如果你把检索策略、筛选标准、综述框架一次性堆进一个很长的 Prompt，模型反而容易在执行到一半时把任务目标给忘了。

3.4 披露粒度怎么把握

实践下来，我总结了几个关于披露粒度的经验：

• SKILL.md 的总长控制在 60~200 行之间。太短则信息不够，技能无法真正落地；太长则模型扫描成本太高，失去了渐进式披露的意义。
• 用 H2/H3 标题把内容切成若干独立小节。每节只回答一个问题，标题用动宾短语，便于 Agent 快速定位。
• 内容有依赖关系时明确写出来。比如"在进入第 2 节之前，必须先完成第 1 节的步骤"，避免 Agent 跳过必要前置步骤。
• 不要把关键信息藏在很深的嵌套里。比如"### 3.2.4 注意事项"这种层级看起来有条理，但对模型来说反而难以定位，尽量控制在两层以内。

4. Skill、Agent 与工具（MCP）的边界：别再混为一谈了

4.1 三者各干各的活

现在社区里讨论 Agent 开发时，经常把 Skill、Agent、工具（MCP / Function Calling）混在一起说，很多新手被绕得晕头转向。我尽量用一句话划清边界：

• Agent 是调度大脑，负责理解用户目标、规划步骤、决定下一步调什么；
• Skill 是知识和方法论，告诉 Agent"某类事情应该怎么做、有什么规范"；
• 工具（MCP/Function）是执行手脚，真正去做外部动作，比如查数据库、发 HTTP 请求、操作文件。

用餐厅类比：Agent 是厨师长，Skill 是菜谱和管理规范，工具则是炉灶、锅铲和食材供应商。厨师长先看菜谱决定怎么炒，再操起锅铲动手，三者缺一不可。

4.2 什么场景用 Skill，什么场景必须上 MCP

这两种机制经常会让开发者纠结。我的判断标准很简单：

• 如果任务主要是**"按某种方法/流程产出内容"**，比如写周报、做代码审查、整理会议纪要、写论文综述，那优先用Skill。它本质上是给模型提供"怎么做"的指导。
• 如果任务是**"访问外部系统、执行真实动作"**，比如查询 API 数据、写文件、调用命令行工具、发送邮件，那必须用MCP 工具或 Function Call。模型需要真正执行一个动作并拿到结果，不能只靠读文档就完成。
• 大量复杂任务其实两者都需要。比如"读取数据库中的慢查询日志，然后根据优化规范输出调优建议"——数据读取靠 MCP 工具，优化规范和方法论靠 Skill。

我把这两者的区别整理成一个表：

4.3 实测项目里的组合玩法

我自己维护了一个内部数据分析 Agent，它同时挂载了 7 个 Skill 和 4 个 MCP 工具。用户输入"分析本月订单数据并生成周报"时，实际执行链路是这样的：

1. Agent 读取技能索引，激活>--- name: short-video-script description: 用于生成面向抖音、小红书、B 站的短视频脚本文案。当用户提供产品或主题并需要脚本创作时使用。不做视频拍摄建议和投放策略。 --- # 短视频脚本生成助手 ## 1. 素材整理 - 提取用户输入中的核心卖点，归纳为 1-3 句话 - 标注目标平台与受众人群画像 ## 2. 脚本结构 - 黄金前 3 秒：抛出反常识结论或痛点问题 - 痛点引入：具体化目标用户正在经历的场景 - 解决方案：给出 2-3 个可操作建议 - 案例故事：讲一个具体的用户/使用场景故事 - 转化引导：给出明确的下一步动作（关注、评论、购买） ## 3. 平台差异 - 抖音：节奏快、前 3 秒决定完播率 - 小红书：重干货总结，多使用清单体 - B 站：互动性强，适合做长铺垫和梗 ## 4. 编写禁忌 - 避免虚假夸大宣传 - 避免仅仅堆砌专业术语，要翻译成用户语言 - 每个脚本必须给出一句可直接口播的结尾钩子

   把这份 SKILL.md 放进short-video-script/目录，整个技能包就算成型了。第一次写不用追求完美，关键是先让它能用，再根据实际输出迭代。

   6.4 第四步：用 agent 跑一轮真实任务来调参

   写完 SKILL.md 后，直接拿真实任务测试。我的测试流程是：

   1. 输入一个简单需求："帮我写一个家用咖啡机的短视频脚本，目标是小红书用户"；
   2. 观察模型的输出是否严格遵循了 SKILL.md 中的五段式结构；
   3. 对照 SKILL.md 检查：是不是有哪个小节没被激活？description 的触发词是否足够？
   4. 如果模型输出完全偏离，优先检查description 是否写得足够精准，其次检查正文指令是否过于模糊。

   这个迭代过程一般要跑 3~5 轮才能趋于稳定。我见过不少人写一次技能就希望它表现完美，这不太现实；技能的调试本质上和写代码类似，需要基于反馈不断修正。

   7. 关于 Skill 生态与部署，我的几点经验

   7.1 不同 Agent 框架对 Skill 的实现差异

   不同 Agent 框架对 Skill 的底层实现不尽相同。Claude 系的 Agent Skills 是相对标准化的 SKILL.md 规范，社区贡献的技能包也多；Codex 则有自己的一套 prompt 和 skills 机制，更偏向在编码场景里"按需注入"；OpenCode 也实现了类似的 skills 功能，适合在本地终端环境里使用。还有一些新兴 Agent 框架，会把 Skill 与 workflow、MCP 工具统一成一套调度体系。

   这里我不准备展开讲每个框架的具体配置方式，因为更新迭代太快，只看文档容易过时。核心经验是：只要你理解了 SKILL.md 和渐进式披露的通用逻辑，在不同框架间迁移的成本不会太高，因为它们解决的本质问题是一致的。切换框架时优先看官方文档对 skill 目录规范和 description 字段的约束，就可以快速上手。

   7.2 新手最容易踩的 3 个坑

   把这些年用 Skill 的经验浓缩一下，新手最容易踩的坑主要集中在下面三个：

   • Description 写得像论文摘要。我见过有人花一整段话描述技能包的战略意义、项目背景，结果 Agent 根本抓不住触发条件。description 应该像"搜索关键词 + 触发条件"，而不是产品介绍。
   • 把所有知识塞进一个超大锦集 SKILL.md。有些朋友的技能包文件动辄几千行，以为内容越全越好。实际上上下文窗口就那么大，你塞得越满，真正有用的那部分能被模型利用得越少。超过 300 行的技能包就应该拆。
   • 忽略版本与更新管理。技能包会随着团队规范调整而变化，我在实战中吃过亏：旧的代码审查规范文件一直挂在 Agent 上，导致模型按过时标准检查代码。Skill 目录建议纳入版本管理，和项目的其他文档一起维护。

   7.3 给想深入做 Agent 开发的人一个建议

   如果你正准备在项目里引入 Agent 开发，我很建议从"先把团队现有的文档、规范、经验，拆成一组 Skill"开始，而不是一上来就追求复杂的 Agent 编排。把个人或团队的隐性经验结构化、挂载到 Agent 上，这个动作本身就会带来立竿见影的效率提升。

   我自己在从零搭建 Agent 系统的时候，最先做的永远是整理 Skill 清单，后做 Agent 逻辑。因为技能包决定了一个 Agent"会什么"，而 Agent 编排只决定"怎么调度这些能力"。先有足够多的靠谱技能，再去编排，整个系统才会稳。后续如果有机会，我再把自己在 MCP 工具设计、Agent 编排层踩过的坑单独拎出来写一篇，这次就先聊到这里。