企业官网建设流程全解析

agent-skills 这类项目，核心价值不是多了一个仓库，而是把 AI 代理的能力组织方式从一个模糊概念变成了可落地工程实践。如果你最近在折腾 AI 代理、做复杂提示词，或者让大模型反复执行同一类任务，你会很快遇到一个问题：提示词越来越长，改一处就影响全局，换一个任务又要重写。skills 的思路，就是把代理要用的能力拆成一个个可复用、可描述、可版本管理的技能单元。先给结论：这个方向值得深入，但不要把它理解成“提示词模板合集”，它更像一套代理能力管理的工程方法。下面按我实际使用的顺序拆开讲。

1. agent-skills 解决的真实问题：代理不是聊天框，是干活系统

很多人在调大模型时会有一个错觉：只要提示词写得足够详细，模型就能稳定完成任务。这个说法在小场景里成立，一旦任务变多、输入变复杂、输出要对接业务系统，纯提示词方式很快就会失控。

1.1 为什么“提示词堆在一起”会越来越难用

先看一个实际场景：你让代理负责整理一次运营会议记录，包括抽取行动项、按负责人归类、生成待办列表。第一次写提示词可能只要几百字。跑通之后，你发现还要处理语音转写文本的噪声，要处理同一个负责人有多个称呼的情况，要处理会议里出现的数字格式不统一的问题。每加一条规则，主提示词就长一截。

再过两周，这个提示词已经到了三千字。你改一个环节，发现另一个环节的输出格式变了；你增加一种输入格式，发现原来的规则被冲掉。最麻烦的是，你根本说不清楚这一次失败是因为模型能力不行，还是因为你的提示词内部有冲突。

skills 的思路就是在这一步出现：把“抽取行动项”和“处理名称统一”，甚至“把数字格式标准化”，各拆成一个独立技能，每个技能有明确的输入、约束和输出格式，代理按需加载，而不是把所有知识都塞进一段上下文。

1.2 技能库到底把什么结构化了

技能库结构化的不是“回答”，而是“做事方式”。它包含几个关键部分：

• 技能的名称和描述，用来让代理判断什么场景该用
• 执行步骤或规则，告诉代理这件事怎么做
• 输入输出的约定，定义格式、字段、约束
• 示例，给代理一个可对照的参考
• 边界和注意事项，说明哪些情况不该用这个技能

这样一来，“让代理完成任务”就从一段线性提示词，变成了一套按需调用的能力集合。每个技能可以单独测试、单独修改、单独复用，不乱。

2. 技能、工具、提示词：先把三类概念拆清楚

接触 agent-skills 时最容易混淆的是：技能、工具和提示词到底什么关系。我在项目里调试时经常看到有人把三者混在一起，导致技能库结构混乱、代理误匹配。

2.1 三类东西的边界

工具是可执行的函数或接口，比如读取文件、调用 API、执行 shell 命令。它做的是“能做的事”。

提示词是给模型的自然语言指令，限制它“怎么说”。它做的是“约束表达”。

技能则是把“能做的事”和“该怎么做”包在一起。它可能包含一段提示词、一个工具调用流程、一套输入输出约定和若干示例。它解决的是“某一类任务如何稳定完成”。

2.2 什么时候该用技能而不是工具

如果只是让代理调用一个计算函数，用工具就够，不需要技能。技能适合以下情况：

• 任务需要多步骤，比如“读取会议记录、抽取行动项、按负责人归类、输出表格”
• 任务依赖业务规则，比如“凡是 2023 年之前的项目，不用标注‘当前’”
• 任务需要稳定格式，比如输出给下游系统解析的 JSON
• 任务需要示例引导，比如文本分类、信息抽取这类模型表现容易波动的工作

判断标准很简单：如果你发现同一个任务需要反复写相似的长指令，而且每次写完结果还不一致，这就是该做成技能的信号。

3. 搭建技能库：目录、格式和一个最小示例

下面这部分是实操。我建议你先不要追求完整框架，而是先搭一个最小技能库，把“一个技能从定义到被代理调用”的链路跑通，再逐步扩充。

3.1 先定目录结构

常见的做法是每个技能一个目录，目录里放一个主说明文件，再按需放示例和脚本。目录命名优先用短横线分隔的小写英文，方便代理在匹配时快速识别。

skills/ meeting-action-extractor/ SKILL.md examples/ input.txt output.json name-normalizer/ SKILL.md rules.md digit-formatter/ SKILL.md

这里不是必须叫 SKILL.md，但建议保持统一。因为代理读取技能库时，通常会先按文件名扫描，统一的命名能减少匹配歧义。

3.2 SKILL.md 的常见写法

一个技能说明文件通常包含开头描述、正文规则和结尾示例三块。开头描述最重要，因为代理选不选这个技能，主要看描述和目标任务的匹配度。

--- name: meeting-action-extractor description: 从会议记录文本中抽取行动项，按负责人归类，生成待办列表。 --- ## 适用场景 - 输入是会议纪要或语音转写文本 - 需要输出负责人、行动项、截止时间 ## 执行步骤 1. 识别文本中明确提到负责人的行动句 2. 去掉“可能”“应该讨论”等不确定表达 3. 按负责人生成待办条目 ## 输出格式 JSON 数组，每个元素包含负责人、行动项、截止时间三个字段。 ## 边界 - 如果文本中没有负责人，输出到 "unassigned" - 如果截止时间缺失，字段值为空字符串

这里有个容易被忽略的点：技能文件里的描述不是写给用户看的，是写给代理看的。描述越具体，代理在误匹配时越容易判断“这个技能不适用”。如果写得太宽泛，比如“处理会议文本”，代理会把什么都不相关的任务也套进来。

3.3 最小可用示例

我建议每个技能至少配一个输入示例和一个期望输出。这个示例不只是给人类看的，更是给代理做比对的。调试时，你可以把示例直接喂给代理，看它的输出和期望差多少。

[ { "owner": "张明", "action_item": "本周五前完成发布检查清单", "due_date": "2025-06-13" }, { "owner": "李婷", "action_item": "和设计团队确认新版页面交互稿", "due_date": "" } ]

有了示例，你在跑真实数据时就能快速判断：代理是不是理解了这个技能，还是只靠运气输出了相似结构。

4. 代理怎么找到技能：加载、匹配和执行链路

技能库建好之后，关键是让代理在合适的时机找到并加载合适的技能。这块在项目里最容易出问题，因为很多人以为把技能文件塞给代理就可以了。实际链路要分成几步。

4.1 技能匹配的核心是描述写得准

代理选择技能的逻辑一般是：先读取所有技能的名称和描述，再根据当前任务判断哪个技能最合适。所以匹配质量的第一决定因素不是代码写得多好，而是描述写得准不准。

这里要遵守几个原则：

• 描述里写清楚输入类型，比如“会议记录文本”而不是“文本”
• 描述里写清楚任务目标，比如“抽取行动项并生成待办列表”而不是“处理会议”
• 避免用模糊词，比如“智能分析”“高效处理”这类词对代理匹配没有帮助
• 同名或相似技能之间，描述要刻意做出区分

我实际测试时发现，代理经常在两个相近技能之间犹豫，比如“会议行动项抽取”和“会议摘要生成”。解决方法是各自描述里明确写“本技能不负责生成摘要，只抽取行动项”，边界信息反而是最好的筛选条件。

4.2 一种简单的加载流程

如果你的代理没有现成的技能加载机制，可以先按这个流程实现：

1. 启动时扫描技能目录，读取所有技能的名称和描述
2. 把技能清单以结构化文本形式注入到系统消息
3. 代理根据用户任务选择候选技能
4. 选中的技能文件内容加载进上下文
5. 代理按技能内的步骤执行，输出按约定格式返回

[系统消息] 你可以使用以下技能： - meeting-action-extractor：从会议记录文本中抽取行动项，按负责人归类 - name-normalizer：统一人名称呼，处理简称和别名 当任务与技能描述匹配时，调用对应技能；如果都不匹配，直接给出普通回答。

这个流程看起来简单，但实际运行中要靠日志确认每一步：代理有没有选中技能、选中了哪个、加载文件是否成功、输出是否符合格式。不要跳过日志，否则你只能看到一个错误结果，完全不知道是匹配错了还是执行错了。

5. 技能质量怎么判断：不说“效果不错”，而是看这四件事

技能库写多了之后，你会发现一个新的问题：有的技能看起来很完整，但实际跑起来就是不稳定。这时候不能靠感觉判断，要给每个技能建立可验证的质量标准。

5.1 可复现性

同一个输入，连续跑三次，输出差异大不大。这是最基础也是最重要的指标。如果一个技能在同一份输入下每次输出结构都不一样，那下游解析一定会出问题，这种技能不能上线。

可复现性差的原因通常是：没有把输入格式边界写清楚，或者示例不够，或者技能内步骤里留了大量让代理自由发挥的空间。修的时候不要加更多规则，先补示例，再收紧步骤描述。

5.2 失败可观测

技能执行失败时，是直接返回错误，还是默默输出一个残缺结果？我们更希望它明确失败。比如会议记录里没有负责人，技能应该标记 unassigned，而不是自己编一个负责人名字。这需要你在技能描述里写清楚“遇到缺失字段怎么办”，而不是让代理自行发挥。

好的技能应该做到：能处理的场景稳定处理，不能处理的场景明确说明。含糊糊地输出，等于把问题留给下游。

5.3 边界清晰

边界清晰的技能很克制。它知道自己只负责哪一段，遇到不属于自己的任务会主动拒绝，而不是硬套。比如 name-normalizer 只处理人名，不会跑去整理日期格式。技能之间边界重叠是代理误匹配的主要原因。

测试边界的方法是故意给代理一些不匹配的输入，看它会不会强行使用技能。如果会，说明描述里的边界信息不够明显。

5.4 可维护性

技能是要长期维护的。三个月后你回头改一个技能，能不能在十分钟内定位到规则、示例、边界分别在哪里？如果做不到，说明文件结构有问题。我建议把“长规则”拆到单独文件，主描述只保留触发条件和执行概览，避免一个 SKILL.md 撑到几千行。

6. 实际落地避坑：先单技能，再技能库

最后聊几条我踩过之后觉得最值得说的经验。如果你的项目也打算引 agent-skills 这套思路，这几条能帮你少走弯路。

6.1 不要一上来就做成框架

很多人看到技能库，第一反应是先写一个通用加载器、做一个后台、再做管理界面。我建议先别急。先用一个技能、一个代理、一条真实任务跑通链路，确认匹配、加载、执行、输出四步都稳定，再去考虑批量化和框架化。

如果你连基础链路都没验证过就搭框架，最后大概率会发现框架限制比帮助大。灵活的系统不是一开始设计出来的，是从一个可用版本慢慢演化出来的。

6.2 技能多了之后的管理问题

技能一多，匹配冲突就会出现。我有一次为了让代理处理不同格式的发票，连续建了五个技能，结果代理经常选错。后来我把五个技能合并成一个，靠内部条件分支处理不同格式，匹配反而稳定了。

所以技能拆分不是越细越好。判断标准是：代理能否在只看描述的情况下准确选择。如果它频繁选错，先别急着优化描述，先考虑是不是拆得太细，或者两个技能本身该合并。

技能库也需要版本管理。每个技能的改动要留记录，因为代理的行为会随技能内容变化而波动，没有版本记录，你很难知道某次输出变差是不是因为改了一个技能文件。

6.3 我建议的推进路径

• 第一步：选一个你反复在做、结果一直不稳定的任务
• 第二步：把这个任务写成单一技能，配一个输入示例和一个期望输出
• 第三步：用同一份输入连续跑十次，记录成功率和输出一致性
• 第四步：确认稳定后，再把这个技能接入批量任务或接口
• 第五步：技能数量超过五个时，再考虑目录管理、加载器和日志系统

踩过几次之后我发现，很多问题不是模型能力不够，而是技能描述和输入输出约定没有处理干净。先单技能跑稳，再技能库扩容，这个顺序能帮你把问题控制在可控范围内。agent-skills 这类项目真正的价值，是逼着你把“让代理干活”这件事当成工程来对待，而不是继续依赖一段越来越长的提示词。