企业官网建设流程全解析

1. 从一次"技能包"翻车聊起：Agent Skills 到底解决了什么问题

去年年底我接手了一个自动化代码审查的活儿，需求很朴素：让模型读一遍 PR 的 diff，按团队规范挑毛病，输出一份带行号的报告。我第一反应是上 MCP——毕竟那阵子 MCP 火得一塌糊涂，各种 server 满天飞，接个文件系统、接个 Git、再接个数据库，看起来什么都能干。结果折腾了两天，我发现一个很尴尬的事实：模型确实能"拿到"文件内容，但它根本不知道我们团队的规范长什么样。你得把规范塞进 system prompt，塞进去之后又发现 prompt 越来越长，改一次规范就得改一次 prompt，改完还得重新测一遍模型会不会跑偏。

后来我换了个思路，把"团队代码规范 + 审查流程 + 输出格式"打包成一个文件夹，里面放一个SKILL.md描述这个技能是干什么的、什么时候用、怎么用，再配上几个脚本和模板文件。模型在需要的时候自己去读这个技能，读完按里面的流程走。整个过程我没动 system prompt 一个字，规范改了就直接改文件夹里的文件，下次调用自动生效。

这就是 Agent Skills 的核心价值：它把"模型该知道什么"和"模型该怎么做事"从 system prompt 里拆出来，变成一个可复用、可版本管理、可组合的文件包。而 MCP 解决的是另一个问题——模型能碰到什么，也就是工具和数据源的接入。

这两个东西经常被放在一起比较，但它们压根不在一个层面上。我见过太多人一上来就问"Agent Skills 和 MCP 哪个好"，这问题本身就问错了。真正该问的是：我现在的瓶颈是"模型够不着数据"，还是"模型不知道该怎么做"？前者上 MCP，后者上 Skills，两个都缺就两个都上。

这篇文章我会把 Agent Skills 拆开讲透：它的文件结构长什么样、SKILL.md里到底写什么、和 MCP 的边界在哪、为什么我觉得对大多数人来说它比 MCP 更值得先学。中间会穿插我自己踩过的坑，包括技能不触发、脚本权限报错、多个技能打架这些实际问题。不管你是刚接触 Claude 生态的新手，还是已经配过一堆 MCP server 的老手，应该都能从里面捞到点能直接用的东西。

2. Agent Skills 的文件结构：一个文件夹就是一项能力

2.1 为什么是"文件夹"而不是"一段配置"

先说个反直觉的点：Agent Skills 最聪明的设计不是它支持多复杂的逻辑，而是它选择了文件夹作为载体。你可能会想，不就是个技能吗，写段 JSON 配置不就行了？我一开始也这么觉得，直到我把一个技能从"单文件"改成"文件夹"之后，才明白这个选择的深意。

文件夹意味着三件事可以同时成立：渐进式披露、资源就近、版本可管理。渐进式披露是关键词——模型不需要一次性把所有技能内容都读进上下文，它只需要先看到每个技能的"名片"（也就是SKILL.md开头的元信息），判断这个技能跟当前任务相不相关，相关才去读全文。这跟 MCP 那种"一上来就把所有工具定义塞进上下文"的做法完全不同，后者工具一多，光工具描述就能吃掉几千 token。

资源就近是说，技能相关的脚本、模板、参考文档、示例数据，全都放在同一个文件夹里，模型读技能的时候顺手就能引用。你不用再费劲告诉它"那个脚本在/opt/scripts/xxx.sh"，它自己会在技能目录里找。

版本可管理这点对团队协作特别重要。技能文件夹可以直接扔进 Git，谁改了规范、谁加了新脚本，一目了然。system prompt 你没法这么管，改了就改了，回滚都费劲。

2.2 一个标准技能目录的解剖

我拿自己那个代码审查技能举例，目录结构大概是这样：

code-review-skill/ ├── SKILL.md # 技能主文件，模型首先读这个 ├── references/ │ ├── style-guide.md # 团队代码规范全文 │ └── common-issues.md # 高频问题清单 ├── scripts/ │ ├── parse_diff.py # 解析 diff 的脚本 │ └── format_report.py # 生成报告格式 └── assets/ └── report-template.md # 报告模板

SKILL.md是入口，也是唯一一个模型一定会读的文件。references/放的是"按需查阅"的长文档——规范全文可能几千字，模型不一定每次都读完，但需要的时候能翻到。scripts/放可执行脚本，模型可以调用它们做确定性计算，比如解析 diff 这种活儿交给脚本比让模型硬算靠谱得多。assets/放模板、示例这类静态资源。

这个结构不是强制的，你可以只有SKILL.md一个文件，也可以加更多子目录。但我的经验是，只要技能涉及超过 500 字的参考内容，就一定要拆到references/里，别全堆在SKILL.md。原因很简单：SKILL.md每次都会被读，堆太多内容等于每次都在烧 token；而references/是按需读取的，不读就不花钱。

2.3 SKILL.md 的头部元信息：决定技能会不会被触发

SKILL.md最上面那段 YAML 头信息，是整个技能里最容易被忽视、但最影响成败的部分。它大概长这样：

--- name: code-review description: 审查代码 diff，按团队规范挑出问题并生成带行号的报告。当用户要求审查 PR、检查代码改动、或提到 code review 时使用。 ---

name是技能标识，description是触发判断的依据。这里有个大坑：很多人把 description 写成功能说明书，结果技能死活不触发。比如写成"本技能用于对代码进行审查"，模型看了半天不知道什么时候该用它。正确的写法是同时描述"做什么"和"什么时候用"，尤其是"什么时候用"这部分，要尽量覆盖用户可能的各种说法。

我实测下来，description 里带上具体触发词（比如"PR""代码改动""code review"）之后，触发率能从一半提升到九成以上。这跟搜索引擎的关键词匹配是一个道理，你得让模型在扫过所有技能名片的时候，一眼看出"哦这个跟当前任务有关"。

提示：description 不要写太长，控制在两三句话。太长反而会稀释关键词的权重，而且每次技能列表都会带上它，太长也费 token。

3. 技能是怎么被"选中"的：触发机制与渐进式披露

3.1 模型看到的其实只是"技能名片"

理解 Agent Skills 的关键，是搞清楚模型在不同阶段到底看到了什么。我用一个具体的流程来说明。

假设你装了 20 个技能，现在让模型帮你审查一段代码。模型启动时，上下文里会有这 20 个技能的名片——也就是每个SKILL.md的name和description，加起来可能就几百 token。模型扫一遍，发现code-review这个技能的 description 里提到了"审查代码改动"，跟当前任务匹配，于是决定加载它。

加载的意思是，模型去读code-review/SKILL.md的正文部分。正文里写着审查流程：先解析 diff、再对照规范逐条检查、最后按模板生成报告。模型读完流程，发现需要解析 diff，于是去调scripts/parse_diff.py；发现需要对照规范，于是去读references/style-guide.md。

整个过程是层层递进的：名片 → 主文件 → 脚本和参考文档。每一层只在需要的时候才展开，不需要的内容永远不占上下文。这就是为什么 Skills 能做到"装几十个也不卡"——因为绝大多数技能在绝大多数时候，只贡献了一行名片。

3.2 触发失败的两类原因和排查方法

技能不触发是最常见的问题，我把它分成两类。

第一类是描述不匹配。用户说"帮我看看这段代码有没有问题"，但你的 description 写的是"执行代码审查流程"，模型可能就匹配不上。解决办法是把 description 写得更"口语化"，把用户可能用的各种说法都塞进去。我现在的习惯是，写完 description 之后，自己脑补五种不同的提问方式，看能不能都对上。

第二类是技能太多导致注意力分散。这个坑我踩过——有段时间我装了三十多个技能，结果发现模型经常选错技能，或者该用的时候不用。后来我做了个减法，把不常用的技能移出去，只留十来个高频的，触发准确率立刻上来了。这跟人一样，选项太多反而决策困难。

排查的时候有个笨办法但很有效：把技能列表打印出来，自己假装是模型，看能不能一眼判断出该用哪个。如果你自己都要想半天，模型大概率也会懵。

3.3 渐进式披露带来的一个隐藏好处

渐进式披露除了省 token，还有个隐藏好处：它让技能的维护变得局部化。举个例子，我那个代码审查技能里的规范文档，从 3000 字涨到了 8000 字。如果这些内容在 system prompt 里，我每次调用都得带着这 8000 字，成本直接翻倍。但在 Skills 里，规范文档只在模型真正需要对照检查的时候才被读取，平时它就静静躺在references/里，一分钱不花。

这个特性对"知识密集型"技能特别友好。比如你有个技能是"根据公司财务制度回答报销问题"，制度文档可能几万字，但你不可能每次对话都把它塞进上下文。放进references/，模型判断问题涉及报销时才去翻，翻的时候还能只翻相关章节（如果文档拆得够细的话）。

4. Agent Skills 和 MCP 的边界：一个管"怎么做"，一个管"能碰什么"

4.1 用一句话说清两者的分工

如果只能记一句话，那就记这个：MCP 负责让模型够得着外部世界，Agent Skills 负责让模型知道该怎么做事。

MCP 的全称是 Model Context Protocol，它定义了一套标准，让模型能通过统一的接口去调用外部工具和数据源——读文件、查数据库、调 API、操作浏览器，这些都是 MCP 的活儿。你可以把 MCP 理解成"给模型装的手和眼睛"，让它能碰到原本碰不到的东西。

Agent Skills 则是"给模型装的经验和流程"。它不提供新的能力，它提供的是"在什么情况下、按什么步骤、用什么标准去做事"。模型本来就能读文件、能写代码，但它不知道你们团队的代码规范是什么、不知道报告该用什么格式、不知道遇到某类问题该走哪个流程。这些"隐性知识"就是 Skills 要补的。

4.2 一个具体场景：两者如何配合

我拿"自动修复线上 bug"这个场景来演示两者怎么配合。

模型接到任务，先通过 MCP 连上日志系统，拉取最近的错误日志（这是 MCP 的活儿——够得着日志）。然后它加载"线上故障排查"技能，技能里写着排查流程：先看错误类型、再定位相关代码、再检查最近的部署记录（这是 Skills 的活儿——知道怎么排查）。排查过程中需要读代码，又通过 MCP 的文件系统接口去读（又是 MCP）。定位到问题后，技能里写着"修复必须附带回归测试"，模型就按这个要求去写测试（还是 Skills）。

你看，两者是交替出现的，不是二选一。MCP 提供"能力"，Skills 提供"章法"。没有 MCP，模型够不着日志；没有 Skills，模型拿到日志也不知道从哪看起。

4.3 为什么我说 Skills 更值得先学

现在回到标题里那个判断：为什么 Agent Skills 可能比 MCP 更值得学？我的理由有三条。

第一，Skills 的门槛低得多。配一个 MCP server，你得懂协议、懂传输方式、懂怎么起服务、懂怎么处理认证，中间任何一环出问题都够你查半天。而写一个 Skill，本质上就是写一个 Markdown 文件加几个脚本，会写文档就会写 Skill。我教过一个完全不懂后端的产品经理，她半天就写出了自己的第一个技能。

第二，Skills 的收益更普适。MCP 的价值高度依赖"你有没有值得接的外部系统"。如果你就是个普通开发者，日常就是读代码、写代码、查文档，那 MCP 能帮你的其实有限——文件系统 MCP 能干的事，模型本身也能干。但 Skills 不一样，任何"我希望模型按我的方式做事"的场景，Skills 都能用上。写周报、做代码审查、整理会议纪要、按固定格式回邮件，这些全是 Skills 的用武之地。

第三，Skills 是理解 Agent 工作原理的最佳入口。你写几个 Skill 之后，会自然理解"上下文是怎么被组织的""模型是怎么做决策的""为什么提示词工程有极限"。这些认知反过来会让你用 MCP 也用得更明白。我见过不少人 MCP 配了一堆，但对"模型到底怎么想的"毫无概念，结果工具越多越乱。

当然这不是说 MCP 不重要。等你真的需要接数据库、接内部系统、接第三方 API 的时候，MCP 是绕不开的。但对刚入门的人来说，从 Skills 起步，性价比高得多。

5. 动手写第一个技能：从"周报生成器"开始

5.1 为什么选周报作为入门项目

我推荐所有人拿"周报生成器"练手，原因很实在：需求清晰、输入输出明确、你自己就是用户。你知道自己每周干了什么、知道周报该长什么样、知道什么样的周报算合格。这种"自己就是领域专家"的场景，最适合写第一个技能。

而且周报这个场景天然需要"流程"——不是简单地把事情列出来，而是要有结构、有重点、有取舍。这正好能体现 Skills 相对于"直接问模型"的优势。

5.2 技能目录和 SKILL.md 的写法

先建目录：

weekly-report/ ├── SKILL.md ├── references/ │ └── report-style.md └── assets/ └── template.md

SKILL.md的内容：

--- name: weekly-report description: 根据本周的工作记录生成结构化周报。当用户提到写周报、总结本周工作、生成周报时使用。 --- # 周报生成技能 ## 使用流程 1. 先向用户确认本周的主要工作项，如果用户没提供，主动询问。 2. 读取 `references/report-style.md` 了解周报的写作风格要求。 3. 按 `assets/template.md` 的结构组织内容。 4. 每个工作项必须包含"做了什么"和"结果/影响"两部分。 5. 如果某项工作没有明确结果，标注为"进行中"并说明下一步。 ## 注意事项 - 不要罗列流水账，同一类工作合并成一条。 - 重点项放前面，琐事放后面或省略。 - 语气客观，不要用"非常""特别"这类主观词。

references/report-style.md里写你偏好的风格，比如"每条不超过三句话""用动词开头""避免被动语态"。assets/template.md里放周报的骨架：

# 本周工作（{日期范围}） ## 重点进展 - {工作项}：{结果} ## 其他工作 - {工作项}：{结果} ## 下周计划 - {计划项}

5.3 实测效果和调优过程

我第一次跑这个技能，模型生成的周报结构对了，但内容还是有点流水账。我回去改SKILL.md，加了一条"同一类工作合并成一条，比如三个会议合成'参加三场评审会'"。再跑，明显好多了。

后来又发现一个问题：模型有时候会漏掉"结果/影响"这部分，只写"做了什么"。我在SKILL.md里把这条从"必须包含"改成了"缺少结果的工作项一律标注为进行中"，用更硬的约束逼它补全。这个改动很有效，因为"标注为进行中"是个明确的动作，比"必须包含结果"这种模糊要求更容易执行。

提示：写技能的时候，能用具体动作描述的，就别用抽象要求。"标注为进行中"比"必须包含结果"好，"每条不超过三句话"比"保持简洁"好。模型对具体指令的执行力远高于抽象指令。

5.4 从周报技能能学到什么通用套路

这个简单的技能其实包含了写所有技能的通用套路：流程 + 参考 + 模板。流程告诉模型"按什么顺序做"，参考告诉模型"按什么标准做"，模板告诉模型"做成什么样"。三者齐了，技能基本就能用。

你把这个套路套到别的场景，比如"会议纪要生成""代码审查""竞品分析"，结构都是一样的。区别只在于流程的复杂度和参考文档的体量。我后来写的十几个技能，基本都是这个骨架的变体。

6. 那些文档里不会写的坑：我踩过的五个真实问题

6.1 技能不触发：description 写成了"功能说明"

前面提过，但值得再强调一次。我最早的 description 写的是"本技能用于生成周报"，结果模型十次有三次不触发。改成"当用户提到写周报、总结本周工作、生成周报时使用"之后，基本百发百中。description 的重点是"什么时候用"，不是"是什么"。

6.2 脚本权限报错：忘了加执行权限

技能里的脚本，模型调用的时候是按可执行文件调的。我有次写完脚本忘了chmod +x，模型调用直接报权限错误，而且报错信息很隐晦，我查了半天才发现是权限问题。现在的习惯是，脚本写完第一件事就是加执行权限，然后在SKILL.md里注明"脚本已具备执行权限"。

6.3 多个技能打架：触发条件重叠

有段时间我同时装了"代码审查"和"代码优化"两个技能，结果模型经常在该审查的时候去优化，该优化的时候去审查。原因是两个技能的 description 都提到了"代码"和"改进"。解决办法是在 description 里加区分词——审查技能强调"找问题、挑毛病"，优化技能强调"提升性能、重构"。技能之间要有明确的边界，重叠就是灾难。

6.4 参考文档太长：模型只读了个开头

references/里的文档如果太长，模型可能只读前面一部分就下结论。我有个技能参考文档写了上万字，结果模型经常漏掉后面的关键约束。后来我把长文档拆成多个小文件，在SKILL.md里指明"遇到 X 情况读 A 文件，遇到 Y 情况读 B 文件"，模型就能精准读取了。参考文档要拆，不要堆。

6.5 技能更新后不生效：缓存问题

改完SKILL.md之后，有时候模型还是按老版本执行。这通常是缓存没刷新。我的做法是改完技能后，新开一个对话测试，别在旧对话里测。旧对话的上下文里可能还留着老版本的技能内容，会干扰判断。

7. 从单技能到技能组合：进阶玩法与边界

7.1 技能可以互相引用

当你有多个技能之后，可以让它们互相引用。比如"项目复盘"技能里可以写"如果复盘涉及代码质量，调用 code-review 技能"。这样模型在处理复杂任务时，会自动串联多个技能。我实测下来，这种组合能处理相当复杂的流程，而且每个技能还是保持独立、可单独维护。

7.2 什么该做成技能，什么不该

不是所有东西都适合做成技能。我的判断标准是：如果一个任务有明确的流程、需要反复执行、且你对"怎么做"有特定要求，那就值得做成技能。反过来，一次性的、没有固定流程的、你怎么做都行的任务，直接问模型就好，做成技能反而是负担。

还有个边界：技能不适合做实时性强的操作。比如"查当前股价"这种，应该用 MCP 接数据源，而不是写个技能去描述怎么查。技能是"知识"和"流程"，不是"连接"。

7.3 技能和 system prompt 的关系

最后说个容易混淆的点。Agent Skills 不是要取代 system prompt，而是把 system prompt 里那些"又长又稳定"的部分搬出来。system prompt 应该保留的是"角色设定"和"全局约束"，比如"你是一个严谨的助手""不确定的时候要说不确定"。而具体的流程、规范、模板，全部下沉到技能里。这样 system prompt 能保持精简，技能能独立演进，两边都清爽。

我现在维护的 system prompt 不到 200 字，剩下的全在技能里。改规范不用动 prompt，加能力不用动 prompt，整个系统稳定得多。这个拆分思路，我觉得是 Agent Skills 带给我的最大启发——把"你是谁"和"你会什么"分开管理，前者稳定，后者灵活，各司其职。