企业官网建设流程全解析

1. 从一次重复调教 AI 说起：为什么需要技能沉淀

先说个真实经历。去年我做运营数据周报，每周一都要让 AI 按固定口径分析销售表格，再把结果改写成老板能看的结论。最开始我把那套规则直接塞进对话里，每次都要重新粘贴一遍，AI 还经常理解得跑偏；后来我把规则写进了系统提示词，算是稳定了一阵子，但换个场景、换个工具又得重新来一遍，最崩溃的是某个参数口径改了一次，所有地方都跟着改，漏一处就出错。

被这件事反复折磨之后，我才意识到问题不在"提示词写得不好"，而在于我根本没有一套可以把复杂能力打包、复用、迭代的载体。这时候我接触到了 agent-skills 这个概念——把过去散落在对话里、系统提示词里、五花八门的工具脚本里的经验，沉淀成结构化的技能文件，让 Agent 在需要的时候自己调用。这个思路直接解决了我上面说的三个痛点：不用每次重复调教、不用在一个巨型提示词里堆砌所有规则、改一处只需改对应的技能文件。

这篇文章就是围绕 agent-skills 写的一份实战笔记。我默认你已经在做 Agent 相关的东西，可能是用 Claude、DeepSeek 这类模型写自动化脚本，也可能在用 LangChain、CrewAI 搭多智能体应用，或者只是在用各类带 Agent 功能的效率工具。本文的核心话题是：怎么把"让模型稳定干活的能力"抽象成可复用、可测试、可版本化的技能，以及这一套方法在不同框架下怎么落地。

需要先说清楚一个边界：技能（Skill）不等于工具（Tool），也不等于工作流（Workflow）。工具是确定性的代码函数，例如"调用这个 API 拿天气数据"；工作流是固定顺序的步骤编排，例如"先抓数据、再清洗、再入库"。而技能是一段带上下文、带示例、带约束的指令包，它依赖模型的推理能力去理解"什么时候该用、怎么用、用到什么程度"。三者的关系有点像工具是"肌肉"，工作流是"骨架"，技能才是"大脑里的反应模式"——它知道用哪些肌肉、按什么节奏做动作。

这篇文章适合两类人。第一类是正在做 AI 自动化，但发现自己换了模型、换了项目就要重写提示词的人，你需要一套技能化的沉淀方法；第二类是团队里已经有多人各自维护 Agent 配置，想把这些散落的经验统一管理、统一迭代的人，你需要一套技能库的组织规范。看完之后你至少能动手建出第一个技能文件，并知道用什么标准去衡量这个技能写得好不好。

2. 动手前先想清楚：我的 Agent 到底需要哪些技能

很多人第一次接触 agent-skills，第一反应就是"那我把我所有的工作流都写成技能文件"。千万别这么干。技能不是越丰富越好，而是越精准越好。技能库如果塞满了低质量技能，Agent 在调用时反而会因为选择过多而选错，或者在一个技能里硬套另一种任务的方法。

2.1 从高频重复、且规则相对稳定的任务开始

我建议你只做一件事：翻自己过去两周和 AI 的聊天记录，把出现过三次以上的任务类型列出来。注意，是"任务类型"而不是"具体任务"。比如"帮我把这段会议纪要整理成 To-do List"和"帮我把这段采访记录整理成行动清单"，本质上是同一个技能——"从非结构化文本中提取行动项"。再比如"帮我看看这个数据表里哪些渠道的收入异常"和"分析一下这周用户流失的原因"，底层都是"给一个数据源和业务背景，输出结构化分析报告"。

这类任务通常有几个共同点：第一，你已经摸清了稳定做法，不需要每次从头试；第二，模型容易在某个环节犯错，你已经在提示词里补过多次说明；第三，输出格式是你或团队反复调整过、已经定型的。这三个信号同时出现，就是技能化最合适的机会。

我自己还有个筛选标准：这个任务需要 500 字以上才能把规则说清楚吗？如果 100 字的提示词就能搞定，那它还不值得写成技能；如果超过 1000 字还在不断增加内容，那说明这个技能应该继续拆解。技能是给 Agent 当参考手册用的，不是让 Agent 背下来的命令行，它应该有合适的厚度。

2.2 用场景边界反推技能的分割粒度

技能设计最容易犯的错是把粒度搞错了。我见过有人写一个叫"数据处理"的技能，里面既包含 CSV 清洗、又包含 JSON 转换、还包含数据可视化建议，一个文件写了两千字。这种技能看起来全能，实际调用效果很差——因为模型在遇到具体输入时，不知道应该触发哪一段规则，经常把清洗规则套到可视化环节上。

正确的做法是按"输入的类型和输出目标"来划分边界。打个比方，就像你把菜刀和削皮刀分开挂，不是因为它们都叫刀所以要放一起，而是因为使用场景不同。如果两个任务使用同一份输入、但输出目标完全不同，它们是两个技能；如果两个任务输出目标相同、但输入格式完全不同，它们也是两个技能。以一个具体例子来讲，"把销售表格转成图表描述"和"把销售表格转成业务建议"，输入一样，输出不同，所以是两套技能；"处理 CSV 报表"和"处理 PDF 合同文本"，虽然都叫"提取关键信息"，但方法差异太大，也应该拆开。

命名风格我推荐用"动词+对象"的结构，比如"制定周报分析框架""提取表格关键字段""审查文档逻辑一致性"。命名的时候把 description 字段写得像搜索引擎的摘要一样：说清楚这个技能适用于什么输入、产出什么、以及最重要的——什么情况不该用它。

2.3 技能目录的结构规划

我建议把技能库按"领域"和"通用能力"两层来组织。领域层对应你的业务场景，例如"销售分析""内容创作""客户支持"；通用能力层是跨场景的，例如"信息摘要""结构化改写""质量审查"。这样做的好处是，通用能力技能可以被领域技能引用，形成组合，而不是每个领域都各自写一份摘要方法，改起来重复劳动。

这一步想明白之后，就可以开始建第一个技能文件了。不要追求一上来就完整覆盖所有场景，先把最痛的那个高频任务做透，你会在使用过程中自然摸索出更合适的粒度。

3. 第一版 Skill 从零到跑通：一个完整的技能文件模板

现在进入实操环节。目前主流的 agent-skills 实现方式基本都采用"一个技能一个目录，目录里有 SKILL.md 主文件，可选附带参考资料、示例、脚本"的结构。无论你用的是 Claude 的 Agent Skills、CrewAI 的 Skill，还是自己写的加载器，这套结构的底层逻辑是通用的：用文本描述能力，用文件组织依赖，用目录结构支持扩展。

3.1 最小组件：SKILL.md 的必备字段

一个最小可用的技能文件，至少要包含以下四块内容：

description 是最容易被忽略、但实际影响最大的字段。因为在大部分 Agent 架构里，模型是通过 description 来决定是否调用技能的，而不是把 SKILL.md 全文都读一遍。如果 description 写得太泛，比如"用于处理周报"，那模型遇到任何跟周报沾边的任务都可能调用它，包括"帮我把周报发送到群里"这种根本不需要分析能力的事。更好的写法是带上输入条件和输出目标，比如"输入为销售/运营数据表格，输出为面向管理者的结构化周报分析，不适合用于原始数据清洗"。

instructions 部分是技能的核心，要写的是执行逻辑，不是流程口号。我给下面示例里用的"步骤式+分支式"混合写法，是经过大量测试相对稳妥的格式：主流程用步骤编号，关键判断点用"如果...则..."分支，避免模型自作主张跳步。

3.2 一个能直接抄的示例：销售周报分析技能

直接上代码块，这个是我实际在用的简化版本，你可以体验一下整体结构：

--- name: sales-weekly-analysis description: > 适用于输入销售明细表或渠道汇总数据，输出包含核心结论、异常点、 下步建议的周报分析结果。不适合处理非数据类文本，也不适合做预测建模。 --- # 销售周报分析 ## 适用场景 - 输入：销售明细 CSV、渠道汇总表、GMV 走势数据 - 任务目标：识别本周变化、定位原因、给出下一步动作建议 ## 执行步骤 1. 先读数据，确认字段含义和统计口径。 - 如果字段中有"渠道、订单量、GMV"，按渠道维度做汇总。 - 如果字段中只有"订单量、GMV"没有渠道，按时间维度做趋势分析。 - 如果数据量小于 5 行，不要强行做趋势分析，直接列出明细并标注"样本不足"。 2. 和上周做环比。 - 先算出每个渠道 GMV 的环比变化率，标注出增长/下降超过 15% 的项。 - 增长率计算时用 (本周值 - 上周值) / 上周值，保留一位小数。 3. 对超过阈值的变化做原因排查： - 优先在数据中找支撑性证据，例如某一渠道订单量剧增，看是否对应明显促销记录。 - 找不到明确证据时，输出"原因待确认"，禁止编造业务归因。 4. 按以下结构输出结论： - 本周概述：2-3 句话概括整体表现。 - 核心数据：用表格列出渠道、GMV、环比、变化率。 - 异常点：列出超过阈值的变化项以及推测原因。 - 下周建议：最多 3 条，必须基于前面分析，禁止泛泛而谈。 ## 注意事项 - 不要使用 2020 年之前的默认历史数据做基准，除非用户明确指定。 - 输出中使用用户原始表格里的货币单位，不自行转换。 - 当某渠道本周无数据时，写"无数据"而不是 0，避免误导环比计算。 ## 示例 输入：渠道汇总表（本周 GMV: 淘宝 120 万，京东 80 万；上周: 淘宝 100 万，京东 95 万） 输出： 本周概述：整体 GMV 环比增长 5.26%，主要受淘宝渠道拉动。 核心数据： | 渠道 | 本周 GMV | 上周 GMV | 环比 | |------|---------|---------|------| | 淘宝 | 120 万 | 100 万 | +20% | | 京东 | 80 万 | 95 万 | -15.8% | 异常点：京东渠道下滑 15.8%，已超过 15% 阈值，数据中未见促销或大促记录，原因待确认。 下周建议：1. 排查京东渠道流量来源变化；2. 关注淘宝增长是否可持续；3. 对下滑渠道做用户回访。

你可以看到，这套结构的核心不是"教模型写周报"，而是"限制模型在关键环节不要乱猜"。比如第 3 步里我明确写了"禁止编造业务归因"，第 4 步规定输出格式，这两个约束直接避免了 Agent 最常见的幻觉问题。

3.3 为什么使用 Markdown，而不是代码脚本或 JSON 配置

很多人会问：技能为什么要用 Markdown 文件，直接写 Python 脚本调用不好吗？这个问题我当时也想了一阵。答案是：技能的消费者是模型，而不是程序。模型是文本推理器，自然语言对它来说是最低成本的"可执行代码"。一个 100 行的 Markdown 文件，模型读一遍就能理解全部约束；如果用代码脚本，每个脚本还需要额外配注解、参数说明、异常处理，最后效果未必比自然语言稳定，但维护成本高得多。

退一步说，Markdown 文件本身就是文本，天然支持 Git diff，你改了一个字段、加了一句注意事项，在版本历史里都能看得到。这在团队协作场景里太重要了，因为技能是会进化的，你总想知道"上一次还能用，这次怎么突然不行了"，而答案往往就藏在 diff 里。

你可以在技能目录里额外放脚本文件或数据文件，只要在 SKILL.md 里说明它们的用途和使用方式。但主文件一定得是纯文本、模型可直接阅读的。这个原则要坚持住。

4. 把技能"做厚"的关键细节：指令、示例和检查清单怎么写

基础版技能能跑通，但距离"稳定"往往还差得远。我发现大多数人的技能文件写出来之后，第一次实测的错误率还是很高的，原因基本都出在三个地方：指令太僵硬、示例太少、缺少输出前的自查机制。这一节我把这三个坑逐个说透。

4.1 指令要面向推理，而不是面向流程

先说指令的写法。新手最常犯的错误是写手把手流水账："第一步，打开文件。第二步，读取数据。第三步，计算增长率。第四步，输出报告。"这种写法有两个问题：一是模型每一步都缺少判断依据，遇到"文件打不开"或者"数据缺失"时就卡住了；二是太过线性的步骤，容不下真实场景里的分支情况。

更好的写法是"给出目标、给出约束、给出分支判断条件"。你在第 3 节的示例里已经看到，我在每个步骤里都埋了 if-then 分支。这些分支不是凭想象写的，而是来自我对真实数据的观察。比如电商周报里经常出现"某渠道这周没数据"，如果不提前在技能里说明这个情况应该写成"无数据"还是"0"，模型每次会随机选择一个，结果周环比计算就跟着错。

另外一个小技巧：在步骤后面加一行"为什么这么做"，用一两句话解释这个步骤的目的。模型的指令遵循能力很强，当它理解了目的之后，遇到指令没有覆盖到的边界情况，会按照目的去合理推断，而不是死板地按字面执行。我在调研技能里写过"输出分类标签时不要给置信度过低的预测，目的是防止下游误判，宁可漏报不要误报"，模型在遇到模糊输入时就会主动选择更稳妥的分类方式，效果非常明显。

4.2 示例的三层作用：格式、语气、边界

示例在技能文件里的重要性，怎么强调都不过分。很多文档只写指令不写示例，模型的输出会变得五花八门。我给技能写示例时，会刻意放三类内容：

第一类是标准成功案例，这告诉模型"输出长什么样"。第二类是带边界情况的案例，比如"输入数据量过小"或"缺少关键字段"时应该如何处理，这类示例对模型的引导作用比任何指令都强。第三类是"不该怎么做"的反例，我会把常见错误写法直接放在示例里，并标注"这是错误示范，禁止这样输出"。

说个我自己的教训。有一版技能里我只放了一个成功示例，模型在遇到另一种渠道名格式时，就固执地套用了示例里的种子风格，甚至把"京东"写成了"淘宝"。后来我加了第二个示例，里面特意用了个冷门渠道名，并注明"渠道名应以输入数据为准，优先级最高"，这个问题就再没出现过。你仔细体会一下：模型不是在"理解"规则，而是在"匹配"模式。示例就是模式的锚点，多点几个锚，模型才能找到正确的位置。

4.3 检查清单：给 Agent 装上事中刹车

我在技能里必加的一段内容是"输出前自查清单"，放在执行步骤的最后。这段不是给用户看的，是给模型自己在生成最终回答前逐项核对用的。我常用的清单项有：是否使用了与用户输入一致的单位？是否所有关键字段都有数据支撑？是否存在超过阈值的异常点没被解释？输出结构是否严格按照目标格式？

本质上，检查清单相当于把"事后纠错"提前到了"事中巡检"。模型是生成式模型，它输出完一段话之后往往不会主动回顾自己的逻辑链有没有漏洞。你在技能里写"按以下清单重新检查你即将输出的内容"，等于强制要求它把自己的回答当作输入再读一遍，这个动作能挡掉相当一部分低级错误。

自检清单怎么设计才有效？我的经验是不要超过 5 条，每条都要可以机械判断，例如"环比公式是否使用 (本周-上周)/上周"，而不是抽象地问"数据是否准确"。"数据是否准确"这种条目模型无法自查，问了等于没问，因为它并不知道正确答案；而"是否有任何增长超过 15% 的渠道没写进异常点"是可以数出来的，模型能执行。

4.4 信息过载时怎么办：把技能拆成多文件

最后说一个规模问题。技能文件如果超过 200 行，模型到后面会开始丢失前面指令的权重信息，尤其是"注意事项"里的约束和正文步骤里的指令冲突时，模型通常会按前面的步骤执行，把注意事项抛到脑后。遇到这种情况，我建议你做两件事：

第一，把技能拆成"主文件+参考文件"。SKILL.md 只保留核心执行逻辑和触发条件，把领域知识、详细背景、额外案例放到同目录下的 references 文件里，在主文件的合适位置用"遇到 X 情况时，先阅读 references/xxx.md"来引用。模型会按需取用，而不是一上来加载全部内容。

第二，把"步骤"当作硬约束、"注意事项"当作软约束来区分写法。步骤部分用最明确的祈使句，注意事项部分则说明条件场景。模型对"必须""禁止"这类词的权重响应很高，用这些词时要谨慎，只有在真正不可违背的规则上才用。留一些"缓冲地带"给模型发挥，反而能提升整体可控性。

5. 实测和调优：验证技能效果的完整链路

技能文件写完只是起点，真正让它稳定的关键在于测试。很多人在这一步偷懒，直接把技能丢进生产环境，等出了问题再改。这样也不是不行，但你会发现每次改动都不知道到底改好了没有，因为缺少一个可对照的基线。我后来养成了一个习惯：每个技能都配一个小型测试集，每轮修改都跑一遍测试，用输出结果的差异来指导下一步优化。

5.1 离线测试：先跑通主流程

离线测试指的就是不接真实业务数据，用你自己的测试输入来验证技能。我建议每个技能目录下留一个samples/文件夹，放 3-5 组典型输入。这里有个原则：测试样本要包含正常样本、边界样本和错误样本，而不能只放你最希望遇到的那种正常情况。

跑测试的过程很简单：把技能文件加载进 Agent 环境，用样本输入触发调用，然后把输出保存下来。目标是建立一套基线输出。比如周报分析技能，第一版跑出来的结果可能把环比算错、漏掉某个异常渠道、格式也不对，这些就是后续迭代要解决的问题清单。第一次基线难看没关系，关键是把它保存下来，这样你才能看到每一次改动到底带来的是变好还是变坏。

你还需要一个手段来快速加载技能进不同环境。我目前用的是把技能目录放到 Agent 的配置目录下，例如 Claude 生态里常见的.claude/skills/，或者自己写一个简单的加载函数，把 SKILL.md 读进系统提示词。开源项目里普遍支持这种目录约定，用起来成本很低。

5.2 边界测试：故意喂不完整的数据

边界测试是最能暴露技能短板的一步。我踩过的坑基本都集中在边界情况里。举几个真实的例子：渠道数据为空时，模型把 0 当作数值参与环比，导致出现 -100% 这类荒谬结论；输入数据是英文时，模型擅自把单位从"万美元"改成了"美元"，而没有按技能里"单位与用户保持一致"的约束执行；数据量只有 3 行时，模型仍然强行生成了 5 个渠道的对比表，编出了一堆不存在的渠道。

遇到这些问题，不要第一时间想着"再加一条注意事项就能解决"。你需要分析这个错误是说明性问题还是结构性缺陷。如果属于"模型不知道该怎么办更好"，那就加分支指令；如果属于"模型在多种规则之间产生了冲突"，那你得调整优先级，明确哪条规则优先于哪条。

我测试的时候特别喜欢用"删字段"的办法：把样本里的某个关键字段删掉，看看模型会不会报告"数据缺失"而不是硬着头皮改出一个值。一个好的技能在这个场景下应当是表现出"知道自己不知道"——这是技能稳定性的一个重要指标。

5.3 回归对比与版本迭代

技能修改到最后，最怕的是修好了边界情况，却把正常情况弄坏了。这就是回归测试的价值。每次改完技能文件，我把 5 组样本全部重跑一遍，然后把新的输出和基线输出做对比。如果某组正常样本的输出出现了不合理的偏差，那就说明刚才的修改副作用太强，需要拆掉或者调整。

版本管理建议直接走 Git。技能的变更日志不必像软件工程那样讲究，但最好在技能的 frontmatter 里维护一个简单的version字段和updated日期。这样当你发现某个技能行为突变时，能立刻知道是不是因为自己改了文件导致的。

迭代的节奏上，我一般遵循"一次改一个变量"的原则。有些时候你觉得技能效果不好，可能同时存在指令不清晰、示例不足、约束冲突三个问题，但你一次全改完，根本不知道是哪条改动起的作用。忍住，一次只改一个点，跑一遍测试，记录结果，再动下一个点。这个方法笨但可靠。

5.4 实测中常见的三个"技能失效"场景

最后分享几个我实际遇到过的技能失效案例，你可以把这些当成检查方向，遇到问题先对照一遍：

第二个场景我想多说一句。模型是概率生成，当技能里出现超过 10 个并列的分支时，它经常会在分支判断上产生混淆，选了一个不是最优的路线。碰到这种情况，我通常会把多个分支统合成一个"先判断、再选择"的步骤，而不是把分支写成一串 if 条件链。人看着很清晰的结构，模型读起来可能已经绕晕了。

6. 技能库的进阶玩法：跨项目复用、团队共享与组合

技能一旦积累到 10 个以上，就会进到一个新的阶段：它不再只是你个人的小工具集，而是可以成为团队协作的公共资产。这个阶段需要考虑的问题不再是某个技能怎么写，而是整个技能库怎么组织、怎么共享、怎么演化。

6.1 把技能库变成一个可审查的仓库

我强烈建议把技能库单独放在一个 Git 仓库里，目录结构大致如下：

skills/ analysis/ sales-weekly/ SKILL.md samples/ references/ user-retention-analysis/ SKILL.md content/ meeting-note-to-action/ SKILL.md common/ structured-summary/ SKILL.md quality-review/ SKILL.md

这个结构的好处是，每个技能自包含，不依赖全局环境；目录层级表达了领域归属，让新成员能快速找到相关技能；Git 历史记录了每次改动的来龙去脉，可以做 Code Review 式的技能审查。在团队场景里，我要求每个人提交新技能或修改已有技能时，必须附带两条说明：改动解决了什么真实问题、影响到了哪些旧输出。这两条不可妥协。

共享方式上，不同的 Agent 工具生态有不同的加载约定，但本质都是把技能目录映射到某个路径。你可以直接把这个仓库 clone 到每个人的本地目录，也可以写一个简单的同步脚本，从仓库拉取最新文件复制到对应位置。如果有 CI 环境，再加一条自动化检查：校验每个技能的 frontmatter 必需字段是否齐全、示例文件是否存在、描述是否超过 20 字。这种检查的价值在于，它能在技能还没进入 Agent 环境前就拦截掉低质量提交。

6.2 技能的组合：让多个技能协作而不是堆叠

技能之间是可以组合的。比如我有一套内容生产流程，用了三个技能的组合："信息提取"把原始材料整理成结构化摘要，"内容生成"把摘要扩展成初稿，"质量审查"对初稿做逻辑和格式校验。每个技能本身都很轻，组合起来却能完成一个完整的复杂任务。

组合的方式并不需要专门写一个编排引擎，大部分情况下在技能的 instructions 里引用其他技能名字即可，例如在"内容生成"技能里写一句"输入材料已经由信息提取技能处理为结构化摘要，直接基于摘要开始扩展"。模型在上下文中会保留前面技能处理的输出，自然就知道该怎么衔接。这种设计也让技能之间保持了解耦：你想替换"信息提取"的实现方式，根本不会影响"内容生成"的技能。

不过组合技能时我有一条铁律：每个技能只对自己的输入输出负责，不要在技能 A 里假设技能 B 一定做了什么事情。比如"内容生成"技能，仍然需要在自己的 instructions 里定义"如果输入不是结构化摘要，应先将输入整理成结构化摘要再执行"，而不是直接摆烂说"没有摘要我生成不了"。技能之间的依赖越弱，整个技能库越稳定。

6.3 技能库演化过程中的两个常见问题

技能库规模上来之后，还有两个问题值得提醒。第一个是技能漂移：你不断给某个技能打补丁、加边界规则，加的多了之后，模型对技能中心目标的响应反而会减弱，因为注意力被大量边缘情况稀释了。一个技能如果不定期"减肥"，很快会变成一个臃肿而混乱的规则堆。我给自己定的规矩是：技能文件超过 150 行，就要审视是否需要拆分；超过 200 行，直接拆分，不做犹豫。

第二个问题是技能冲突：两个技能的 description 覆盖了高度相似的任务，模型在触发时可能随机选择一个，导致输出风格和逻辑对不上。避免的办法是，每新增一个技能，都要在技能库里搜索一下已有技能的 description 是否有重叠。如果重叠度很高，但你又确实需要区分，那就必须在它们的 description 里明确写出彼此的适用边界，例如一个写"适合处理月度汇总数据"，另一个写"适合处理每日明细数据"。这是把话说死的做法，但很有效。

技能这个东西，我从开始摸索到现在，最大的体会是：它比工具灵活、比工作流通用、比提示词可维护。但它的难点也在"度"上——写得太细则僵化，写得太粗就没约束；技能太多则难选，技能太少则不够用。好在他是一个可以渐进演进的系统，你不用一开始就搭出一个完美的框架，先从一个最痛的任务开始，把第一个技能用好，再慢慢扩展。所有的调优经验、踩坑记录都会沉淀到技能本身，这也算是另一种意义上的复利。