企业官网建设流程全解析

最近半年我一直在折腾智能体项目，发现一个词在技术社区里出现的频率越来越高：skills。中文圈的开发者把它翻译成“技能”，听起来平平无奇，但在实际开发里，它基本决定了你做的那个AI助手到底是“一个聪明的聊天框”，还是“一个真正能独立干活、能稳定交付结果的数字员工”。

我见过太多项目死在同一个坑上：调试的时候用精心撰写的提示词，效果惊艳得不得了；一放到真实的、嘈杂的用户输入里，AI就开始自由发挥，步骤能省则省，格式随心所欲。问题的根源不在模型本身，而在我们的交付逻辑——我们给了AI一个“目标”，却没有给它一套“可以稳定复现目标的流程”。技能化要解决的，就是这个问题。

这篇文章我会从概念定位、内部结构、实操流程到问题排查，完整拆一遍“skills”到底怎么落地。适合正在做Agent应用的开发者、准备把AI助手接进业务流程的产品和技术负责人，以及所有想把提示词升级成“可复用资产”的人。

1. 为什么现在大家都在给AI助手加“技能”

1.1 从“提示词”到“技能”，开发范式变了

很多人心里有个疑问：提示词不也能让AI做特定任务吗？为什么还要多搞一个“技能”的概念？

我的理解是，提示词解决的是“一次对话”的问题，技能解决的是“一类任务”的问题。传统做法里，你写一段精心设计的提示词，发给用户，用户复制粘贴给AI，AI输出结果。这套体验的脆弱之处在于：第一，提示词和业务逻辑耦合在图文的自然语言里，没人维护；第二，输出质量完全依赖上下文的“临场发挥”；第三，任务里一旦需要多次判断、多个分支，单纯靠提示词描述流程，模型极容易“走捷径”，跳过中间步骤直接给结果。

技能的出现，把开发重心从“写一段好的提示词”转移到了“设计一套可复用的任务流程”上。一个技能不只是一段文字，而是一个包含了元信息、执行步骤、参考模板、参数定义、甚至是本地脚本的完整模块。它告诉你：什么时候该用这个技能，用的时候需要什么输入，先做什么再做什么，最后输出成什么格式。这本质上是一次把“经验”编码成“程序”的过程。

1.2 技能化解决的三个实际问题

我把技能化带来的收益总结成三点，这三点都是我在实际项目里切身感受过的。

第一是可控性。没有技能的Agent，输出质量像开盲盒：同样的需求，昨天还干得好好的，今天换个对话开头，结果就完全跑偏。有了技能之后，执行路径是固定的，模型是在“流程框架内”做填充和判断，而不是凭空生成。哪怕模型换版本，只要流程文件不变，输出基本稳定。

第二是复用性。我后来把技能文件抽象成了通用的业务模块——客服退款审核一个技能、周报生成一个技能、会议纪要一个技能。新项目接入时，直接把这些技能目录放到对应位置，不需要把提示词重新复制粘贴一遍。时间一长，这些技能就变成了团队内部真正的“经验资产”。

第三是可迭代性。提示词的修改过程是没法追踪的，你今天改了一个字，明天又改回来，最后变成一坨没人能解释的“神奇咒语”。但技能文件放在版本控制里，什么时候新增的字段、哪一次改动了触发条件、为什么加了一个边界规则，全部有记录，可回滚、可评审。

1.3 不是所有功能都适合做成技能

这一点经常被人忽略。技能不是万能的，我在项目里吃过不少教训之后，总结出一套判断标准：高频、流程固定、有明确输入输出、有可观测的执行节点——这四个条件至少要满足前两个。

高频很好理解，用户每天都会触发的事情，值得为它写一个技能。流程固定意味着任务的执行步骤是稳定的，不会因为需求不同而出现大范围分叉。明确输入输出是指技能能清楚地说出“我需要什么，我产出什么”。可观测的执行节点是指过程中的关键判断能被记录和验证，比如“这个请求应该走退款流程而不是售后流程”。

相反的，那些偶发的、纯创意的、需要大量自由探索的任务——比如“帮我想一个品牌宣传语”“给这个项目起个名字”——就不适合用技能去约束。做技能是在“限制模型的自由度”，如果任务本身需要的就是创造力，那加一堆条条框框只会适得其反。

2. 拆开一个技能看内部结构

2.1 技能目录：不只一个Markdown文件

很多人以为技能就是一个写得很好的提示词文本，这是一个误解。一个合格的技能，在工程上应当是一个有结构的目录。我在实际项目里，规范化的技能目录大致长这样：

skills/ ├── meeting_minutes/ │ ├── SKILL.md │ ├── templates/ │ │ └── minutes_template.md │ ├── examples/ │ │ ├── input_1.txt │ │ └── output_1.md │ └── scripts/ │ └── extract_speakers.py ├── weekly_report/ │ ├── SKILL.md │ └── templates/ │ └── report_template.md └── refund_handler/ ├── SKILL.md └── references/ └── refund_policy_v3.md

SKILL.md 是核心文件，它记录技能的所有“元信息”和“执行流程”。templates 目录放输出模板，examples 目录放真实的输入输出样例，references 目录放外部参考文档，scripts 目录放可被调用的本地脚本。这种结构的好处是：主体文件和资源分离。主文件保持简洁，模型每次读取的成本低，不会被一堆细节淹没；模板、参考文档、样例则按需加载。

举个例子，一个会议纪要技能，如果所有内容都堆在主文件里，模型收到转写文本的同时还要处理几百行无效信息，注意力很容易被分散。把模板外置成单独文件，模型只在需要填充的时候才去读模板结构，效率和准确率都会明显提升。

2.2 元信息字段：决定技能能不能被正确唤醒

SKILL.md 的开头通常是一段结构化元信息，我用过很多种格式，最顺手的还是 YAML 风格的 frontmatter。它长这样：

--- name: meeting_minutes description: 将会议录音转写文本整理为结构化会议纪要，提取决议、待办事项和责任人 when_to_use: 当用户提供会议转写文本或明确要求生成会议纪要时使用 parameters: transcript: 会议的原始转写文本，必填参数 min_confidence: 最小决议可信度阈值，默认0.7 ---

这几个字段里，水分最大的就是 description。我见过不少初学者的技能，description 洋洋洒洒写一百多字，重要信息全在后半截，结果模型在判断要不要唤醒这个技能时，只会看前面的几句话，导致技能长期“沉睡”。

description 的写法有门道：第一句话必须直接点明技能功能和触发场景，后面再补充“不适用的情况”。比如会议纪要技能，第二行可以写“如果用户只是要求闲聊或讨论想法，不要使用本技能”。这个“负向排除”特别重要——模型判断要不要调用技能，本质上是个分类问题，你给的类别边界越清晰，分类越准确。

when_to_use 的作用和 description 部分重叠，但它更偏向“条件判断”：什么情况下用，什么情况下绝对不用。我会在 when_to_use 里写得更口语化，因为模型对自然语言的触发表达理解得最好。parameters 是技能的输入接口，核心原则是——能写默认值就给默认值，能写示例就给示例。纯粹写一个“transcript: 文本”远不如“transcript: 以下是会议转写文本，或提供一个文件路径”直观。

2.3 正文步骤：把“做事的方法”翻译成机器能执行的语言

元信息下面是技能的正文部分，这是真正的“流程说明书”。我在设计这部分时坚持一个原则：每一步只能说“做什么”和“产出什么”，不要替模型做决定，也不要用含糊的词。

拿会议纪要技能举例，我初版的正文结构是这样的：

## 执行步骤 1. 通读整段转写文本，标记出现的所有发言人和时间节点。 - 如果无法识别发言人，使用“未标注发言人”代替。 2. 提取议题：按讨论主题对内容进行分组，每个议题标注讨论范围和结论。 3. 提取决议：将明确达成一致的结论写入“决议”部分。 - 只统计明确说“同意”“确认”“那就这么定”的内容。 - 存在分歧未达成一致的意见，写入“遗留问题”，不要写入决议。 4. 提取待办事项：找出包含“负责”“跟进”“在X之前完成”等表达的任务信息。 - 每条待办必须包含：事项描述、负责人、截止日期。 - 缺少截止日期的，标注“待确认”。 5. 将上述内容按 templates/minutes_template.md 的格式填充输出。

你看，每一步都有一个输出预期，同时给了模型判断“什么不算某类内容”的边界。这些东西，看着很简单，但都是我在真实调试中一点一点加进去的。一开始我没写“有分歧的内容写进遗留问题”，模型经常把讨论中的各种不同意见也当成决议输出，纪要的可信度大打折扣。加了这一条之后，准确率提升非常明显。

还有一个容易被忽略的点：步骤描述要有“默认兜底”。AI在执行时经常遇到信息缺失的情况，比如转写文本里没有明确负责人，模型就会卡住或者瞎编。在步骤里写清楚“缺失时用什么替代”，比让模型在决策时去猜要靠谱得多。

2.4 模板与资源文件：保持技能瘦身的关键

主文件是做流程控制的，模板是做呈现控制的，两者分离是我强烈推荐的做法。一个常见的反面教材是：技能作者把所有要求都塞进主文件，包括“输出格式第一行写什么、第二行写什么、用什么标题字号、要不要分点”。结果是主文件越来越长，模型在处理长指令时，后面的格式要求往往成为“被遗忘的角落”。

把模板放到单独文件里的好处是：模型只需要在最后一步读取模板并填充。模板本身可以是结构化的，字段占位符清晰可辨。比如会议纪要模板：

# 会议纪要：{会议主题} ## 基本信息 - 日期：{日期} - 参会人：{参会人列表} ## 议题讨论 {议题1}：{讨论结论} {议题2}：{讨论结论} ## 决议 {决议列表} ## 待办事项 | 事项 | 负责人 | 截止日期 | 状态 | |------|--------|----------|------| | {事项描述} | {负责人} | {截止日期} | 待办 | ## 遗留问题 {遗留问题列表}

模板的作用不仅仅是好看，它有“信息引导”的功能——模型在填充模板时，会主动去内容里寻找匹配字段的信息。只要你的模板字段写清楚了，提取的完整性就会有基本保证。

至于 scripts 目录，它解决的是“模型干不了的事”：比如你需要对输入做时间戳解析、需要调用外部接口获取数据、需要做一次复杂的字符串计算，这些都不该让大模型靠“思考”去完成，而是由脚本处理完后，再把结构化结果喂给模型。技能的本质是流程编排，不是让模型代替代码。

3. 从零到一：完整打造一个可用技能的实操记录

3.1 动手之前，先把需求问清楚

我最近在给团队搭建一个内部的“会议纪要技能”，这个案例的过程比较有代表性，我用它来完整走一遍从零到一的全流程。

第一步不是写代码，也不是写提示词，而是把需求问清楚。我和几个经常开会的人聊了一圈，发现嘴上说的“生成会议纪要”其实包含几个完全不同的需求：有人要的是会议结论的统一归档，有人要的是决策依据的记录，还有人要的是从纪要到待办任务的一个自动流转。如果这些需求不加区分，技能根本没法设计。

后来我们把范围收敛成一个明确的目标输入和输出：输入是会议录音的转写文本，输出是一份包含议题、决议、待办事项、遗留问题的结构化纪要文档。这就是一个标准的外部接口定义——输入是什么、输出是什么、边界是什么，都写清楚了，后面做技能才不会跑偏。

3.2 初版技能文件的完整写法

需求明确之后，就是搭建技能目录和写文件。我习惯先在本地建一个空目录，按上一章讲的标准结构把文件夹建好：

meeting_minutes/ ├── SKILL.md ├── templates/ │ └── minutes_template.md └── examples/ └── sample_transcript.txt

然后写 SKILL.md。这里我给出的是后来稳定运行的版本，它比最初版多了一些“血泪教训”式的补充：

--- name: meeting_minutes description: 将会议转写文本整理为包含议题、决议、待办事项的结构化会议纪要 when_to_use: 用户提供会议录音的转写文本，或要求将某段对话整理成会议纪要 parameters: transcript: 会议转写的原始文本，可以粘贴或提供文件路径 include_attendees: 是否尝试推断参会人列表，默认true --- ## 执行步骤 1. 通读全部转写文本，提取发言人和大致的时间顺序信息。 - 无法识别发言人时，全部使用“未标注发言人”。 2. 识别议题：将文本按讨论主题拆分，每个议题记录讨论的起始位置、参与人和主要观点。 - 议题名称应当简短，不超过10个字。 3. 提取决议：保留所有明确表达“同意”“确定”“拍板”等确认态度的内容。 - 如果只是提出想法但没有被确认，一律归入“提议”，不要写入决议。 4. 提取待办事项：查找包含“负责”“跟进”“推进”“在什么时间前完成”等表达的任务。 - 每条待办必须包含负责人、截止日期，缺失时写“待确认”。 5. 生成纪要文件：严格按照 templates/minutes_template.md 的结构输出，不得改变模板中的章节顺序。 6. 输出前自查：检查每一项决议是否都有对应的讨论依据，检查每一条待办是否包含负责人字段。

这版和初版的区别主要在三处：加了“不能识别发言人怎么办”的默认值；把“提议”和“决议”明确切开；最后加了一个“输出前自查”步骤，让模型在交付前自己检查一遍。这三条都是调试过程中反复出问题的点。

3.3 调试技能：五组输入测出问题

写完初版技能后，真正的硬仗才开始。我调试一个技能，从来不会只用一两个测试用例就搞定，而是准备五组不同类型的输入：

• 标准输入：一段格式规整、内容完整的会议转写。
• 同义表达：同样意思的转写，但对话风格极其随意、口语化，夹杂大量打断和跑题。
• 模糊输入：一段没有明确结论、没有待办事项的闲聊式会议记录。
• 异常输入：只有零星几句话，无法构成完整会议场景的碎料。
• 组合任务：转写文本里除了会议内容，还混入了不相关的内容，比如后面有一段讨论晚饭吃什么。

五组测下来，问题立刻暴露。标准输入顺利通过，同义表达的输入在“议题识别”上出了问题——模型把跑题的内容也识别成了正式议题；模糊输入的问题更大，模型居然强行编造了两个“决议”；异常输入时，模型没意识到自己做的不是一个“正常会议”，硬是生成了一份完整的纪要模板。

针对这几个问题，我把规则又过了一遍：在议题提取步骤里加了“如果讨论内容明显与主题无关，标记为闲聊，不进入正式议题”；在决议提取里补充了“如果整篇内容超过一半是闲聊或题外话，直接输出‘本次未能形成有效决议’，不要强行生成决议”；在元信息里的 when_to_use 也加了限定：“输入文本必须具有一定篇幅和讨论结构，否则不要使用技能”。

这些边界条件，不通过刻意测试根本发现不了。所以我的习惯是：任何一个技能上线之前，至少跑三十轮不同形态的测试，把能预想到的边界都扫一遍。

3.4 后续维护：技能不是写完就结束

技能上线之后，维护工作不能停。我现在的做法是每个技能都走版本管控，每一次改动都记录明确的原因。比如会议纪要技能，后来有一个新需求：用户希望能把“决议”自动同步到某个任务管理工具。这个改动涉及在技能里增加一个“输出之后的动作”——调用一个外部脚本，把决议字段写入任务系统的接口。

我把这一步写成了技能流程的“第7步”，在 references 目录里放了一个接口文档，在 scripts 目录里放了一个同步脚本。这种“步骤可插拔”的设计，让技能的维护成本变得很低——需求变化时，大概率只需要修改其中一个步骤，而不需要推翻整个技能。

另外，我还会定期回看真实的用户反馈日志，把“用户贴了转写文本，但AI没有自动触发技能”和“技能触发了但输出格式严重错误”这两类反馈单独收集起来。这两类反馈指向的问题是完全不同的：前者是技能唤醒的问题，最可能出在元信息写得不够清楚；后者是执行的问题，大概率是正文步骤或模板有问题。分开统计，一眼就能看出该改哪个部分。

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

4.1 高频问题速查表

我在好几个项目里用技能体系做Agent开发，结合自己和同行踩过的坑，整理了一个高频问题排查表，先给你们一份速查版本：

这张表只能帮你快速定位方向。具体情况要结合日志看，但大多数问题都能收敛到“唤醒”和“执行”两条线上，不用去怀疑模型本身——绝大多数时候是技能文件的问题，不是能力不够。

4.2 让技能失控的三个典型场景

第一个失控场景是“多技能互踩”。我同时做了一个“会议纪要”技能和一个“待办清单整理”技能，问题很快出现了：用户的一段会议转写文本里有明确的待办事项，AI面对两个技能，不知道先做哪个，最后两个都没执行好。

这个问题靠模型自己是解决不了的，必须在设计上做隔离。我给“待办清单整理”技能加了限定：只处理用户给出的、明确的待办列表内容；如果要整理的内容来自会议转写，必须调用“会议纪要”技能，然后从中提取待办。这就是技能的“组合而非竞争”设计。不要让两个技能在同一个输入上打架，而是定义好层级和顺序。

第二个失控场景是“技能主文件臃肿到模型读不动”。我见过一个同事写的技能，主文件包含大段的管理规定和背景说明文件，加起来将近两万字。模型每次处理这个技能都得读一大包文档，上下文窗口被占掉一大半，真正有用的步骤却被“稀释”了。技能文件应当保持精简，参考资料放到 references 目录中按需触发，而不是一股脑塞进主文件。

第三个失控场景是“步骤里要求不满足历史依赖”。有些开发者为了让步骤更“聪明”，会在技能里写“如果用户之前提到了X，就……”，这不是不能写，但会让技能失去独立性。技能必须具备完全脱离对话历史运行的能力——只要有了输入，就能产出正确结果。凡是依赖“上一次对话中说过什么”的技能，移出上下文之后几乎必挂。如果你发现自己写出了依赖历史的步骤，说明你的输入接口定义有问题，应当把那个“历史信息”明确为一个参数。

4.3 几个值得反复强调的避坑心得

第一，别把“必须”放在步骤的最后。模型在执行流程时是顺序处理的，越靠后的指令权重越低。真正关键的限制条件，一定要放在步骤开头或紧随步骤出现的位置。比如“必须将待办事项按截止日期排序”，这条应当紧跟在待办提取步骤之后，而不是像第五条规则一样写在技能文件的末尾。

第二，描述字段是第一印象，决定技能是“几乎每次都触发”还是“几乎只靠手动指定”。我的习惯是第一句话控制在20个字以内，说清楚功能，第二句写典型触发场景，第三句写“不要用本技能的场景”。你给模型的指令越像一段人类写给同事的交接文档，模型执行得越稳。

第三，给参数写示例，比写类型声明有用得多。与其写“attendees: 参会人列表，类型array”，不如写“attendees：例如['张三', '李四']，如果无法识别则写['未标注']”。模型从示例里学到的信息密度，远高于从类型定义里学到的。

第四，技能一定要做“独立可运行”验证。我每次写完技能，都会把它丢到一个全新的、空白上下文的会话里，只给一个输入，让它自己跑完整个流程。如果这一步成功了，基本能保证它在真实场景中不会因为“上下文缺失”而崩掉。如果这一步失败，问题一定出在技能文件自身，尽早修。

把技能当成产品去维护

我个人在实际操作中最大的体会是：做技能，不是写一份提示词，而是做一个小型产品。它有用户（你团队里的每个人和接进来的系统）、有接口（输入输出参数）、有版本（变更记录）、有生命周期（上线后要迭代）。那些能长期稳定运行、被团队反复调用的技能，一定不是一蹴而就的，而是在真实反馈里一轮一轮“磨”出来的。

我也见过另一种失败模式：技能建了很多，文档却没有，团队里的人根本不知道有这样一个技能存在。所以我现在会在技能目录里额外维护一份索引文件，用一句话描述每个技能能干什么、什么时候调用。这看起来是小事，但在几十个技能的规模下，它决定了这套体系能不能被团队真正用起来。

如果你也想在项目里引入技能体系，我的建议是：别急着做大而全的技能库，先从3-5个最高频、最痛的任务开始，比如自动生成周报、整理会议纪要、提取待办。把这几个技能的稳定性打磨到“放养”状态，再考虑扩展。毕竟，一个有边界的好技能，胜过十个功能重叠的万能技能。