企业官网建设流程全解析

做 AI agent 的人，多半都经历过这种尴尬：同一个任务，第一次教模型怎么做，它完成得不错；第二次换个输入，它忘了前提；第三次你为它补了一大段规则，结果它开始在无关的地方"自由发挥"。问题往往不在模型本身，而在于我们一直在"每次重新教"，没让 agent 真正"学会做一件事"。

agent-skills 就是为解决这个问题出现的思路——它不是一个特定产品的名字，而是一套把 agent 的"可复用能力"沉淀成结构化技能的方法论和工程实践。简单说，就是把 agent 反复要执行的任务包装成有边界、有描述、有验证的"技能模块"，让 agent 像人一样"有手艺"，而不是"每次即兴表演"。

这篇文章不聊虚的。我会从自己折腾 agent 项目的实际经历出发，讲清 agent-skills 到底是什么、怎么设计、怎么写、怎么排坑。适合正在开发 agent 应用的工程师，想给产品接入 agent 能力的业务侧同学，以及刚开始接触 agent、想少走弯路的人。

1. 搞懂agent-skills：它是什么，为什么值得认真对待

1.1 从"每次重新教"到"一次学会"的范式变化

传统做法里，agent 的行为主要靠 prompt 驱动。你在系统提示词里写清楚角色、任务、步骤、注意点，然后让大模型自由发挥。这个方式的代价是：提示词越长，模型越容易抓不住重点；任务描述藏得越深，模型越容易在细节上偷工减料。更麻烦的是，一旦业务逻辑变了，你要去改一大段自然语言文本，还得重新测一遍所有可能出现的行为。整个流程非常脆弱。

agent-skills 的思路是把"任务怎么完成"从 prompt 里抽出来，变成独立的、可命名的技能单元。每个技能包含自己的描述、输入参数、执行步骤、工具调用和输出格式。agent 的主提示词只需要负责"决定当前该用哪个技能"，技能内部的细节由技能自身闭环处理。这样就把"思考"和"执行"拆开了：主模型负责选择和调度，技能负责稳定地干好一件事。

我举个例子。以前我做一个会议纪要 agent，prompt 里写了"请提取会议中的待办事项、负责人、截止时间"，结果模型有时候把讨论背景也当成待办，有时候漏掉截止时间不写。后来我把能力拆成一个技能集合：一个技能负责会议转写文本清洗，一个技能负责按角色提取议题与结论，一个技能专门负责待办与负责人匹配。每个技能只干一件事，输入输出都是结构化的。效果立刻稳定了很多，而且任何一步出问题，我都能单独定位和修。

提示：判断一个任务该不该做成 skill，最简单的标准是——这件事你是否已经在 prompt 里写了第二遍？如果同一个处理逻辑要被多个 agent 复用，或同一个任务反复出现且结果要求稳定，它就值得沉淀成技能。

1.2 skill与prompt、function calling、微调的本质差异

很多人会把 agent-skills 和几个相近的概念搞混。我直接做一张对比表，按自己的理解来说明，你看完就能分清它们各自的角色。

看这张表就明白了：function calling 解决的是"模型该调哪个 API"，prompt 解决的是"模型应该按什么风格和顺序做事"，而 agent-skills 在这个基础上多做了一层"组合与沉淀"。一个 skill 内部可以包含多个 function call、一段执行逻辑、若干人为总结的经验规则，甚至包含失败情况的兜底。它是介于"纯提示词"和"微调"之间的一种工程化能力封装。

我自己对 skill 的定位是：它是 agent 的"操作手册 + 工具清单 + 检查表"。手册告诉 agent 这件事按什么步骤做，工具清单告诉 agent 可以调哪些函数，检查表告诉 agent 做完之后怎么判断结果对不对。三者打包成一个单元，agent 只需要知道什么时候取出这个单元。

2. 设计一个skill之前，先把这三件事想透

2.1 边界：skill到底该管多宽

设计 skill 最容易犯的错，就是"什么都往里装"。我见过很多第一次写 skill 的人，把"数据分析"做成一个技能，里面既要做清洗、又要做统计、还要画图、还要写结论。结果就是技能描述写得极长，agent 根本搞不清楚什么场景该用它，用起来也经常在内部步骤里跳来跳去。

我现在的经验法则很简单：一个 skill 只负责一个可独立验收的结果。比如"从原始会议转写稿中提取全部待办事项，输出 JSON"就是一个合格的边界；"处理会议相关的一切事情"就是不合格的边界。边界越窄，描述越短，agent 的命中率和执行成功率越高。

判断边界是否合适，可以问三个问题：这个技能的输出能被一个明确标准验收吗？它的输入能不能用结构化参数描述清楚？它是否只依赖有限的几个工具？如果答案都是肯定的，边界基本就合理。

2.2 契约：输入输出怎么定，才不会被 agent 玩坏

skill 的输入输出契约，本质上是在和 agent 这个"不太守规矩的调用方"打交道。大模型生成参数时天然存在填错字段、多填字段、类型不对的风险。所以设计契约时我有几条硬规矩：

• 参数尽量少，最好不超过 5 个。参数越多，模型填错的概率越高。
• 每个参数都要有清晰的描述、类型和示例。你不写示例，模型就会自己编一个。
• 输出必须结构化，能 JSON 就 JSON，并固定字段命名。
• 必须定义失败输出。比如"未找到待办时，返回空数组而不是报错"，这样上层才能稳定处理。

我见过一个反面案例：某团队做了个周报 skill，入参是"原始素材"，结果 agent 有时候传一个文件路径，有时候直接把文件内容整个贴进去，还有一次传了个 URL。就是因为参数描述里没写清楚"本参数接受 Markdown 格式的文本内容，不接受路径与链接"。后来补了描述和示例，问题才彻底解决。

2.3 复用：为多个场景复用而设计

skill 的另一个价值是跨场景复用。同一个"信息抽取"技能，可以被客服 agent 用来抽用户诉求，也可以被运营 agent 用来抽活动评论关键词。为了支持这种复用，你在命名和描述上要刻意去场景化。

我的做法是：技能的内部名称用"动词+对象"的通用结构，比如extract_action_items、validate_csv_schema，不要在名字里带具体业务名。业务差异通过参数层面体现，而不是复制一个几乎一样的技能。这样维护成本会低很多，技能库也不会越来越膨胀。

当然，去场景化有个前提——技能内部不能隐含对某一类数据的强假设。比如"提取待办"就比"提取会议待办"可复用性高，但如果数据源差异太大导致内部逻辑完全不同，那就不要硬复用，拆成两个技能反而清晰。

3. 实操：从零实现一个可用的 agent skill

3.1 skill的目录结构与元信息定义

我以自己常用的结构为例。每个技能是一个独立的目录，放在统一目录下，结构大致如下：

skills/ extract_action_items/ skill.yaml instructions.md assets/ examples.json tools/ parse_timestamps.py tests/ cases.yaml

skill.yaml是技能的"身份证"，包含名称、描述、输入参数定义、输出格式声明。下面是一份我实际用过的元信息示例：

name: extract_action_items description: 从会议或聊天记录文本中提取所有待办事项。适合输入原始转写文本、聊天记录，输出结构化待办列表。当用户提到"记一下待办""有哪些要做的事"时使用。 version: 1.2.0 input: raw_text: type: string description: 原始会议转写或聊天记录，要求是 Markdown 纯文本，不接受文件路径 required: true example: "张三说：周五前给客户发报价。李四点了个赞。" owner_required: type: boolean description: 是否需要为每个待办匹配负责人；无法匹配时置为 unknown required: false default: false output: type: object schema: action_items: type: array items: task: string owner: string due_date: string source_line: integer

注意description的写法：它既要说明技能的能力边界，又要给出触发信号。你可以把这段描述理解为 agent 的技能检索入口，描述写得越贴近用户真实表达，agent 命中率越高。我见过不少技能功能本身没问题，但因为 description 里全是技术术语，在真实对话里根本没机会被触发。

3.2 核心逻辑与工具封装

元信息之外，真正干活的是instructions.md和配套工具。instructions.md给 agent 提供"怎么做"的指导，但它不是一篇论文，而是操作步骤加规则加例子。我的习惯是控制在 300 到 600 词以内，重点写清楚三个部分：处理流程、边界规则、失败处理。

下面是我给extract_action_items写的 instructions 关键内容：

# 待办提取执行指引 1. 通读 raw_text，先识别所有表示行动需求的句子，包括但不限于"需要、要、记得、安排、跟进、确认"等表达。 2. 对每个候选句子，判断是否满足全部条件：主语或明确负责人、动作、时间或优先级信息。缺少任意一项则视为置信度不足。 3. 排除纯讨论性内容。只记录"未来需要有人执行"的事项，不记录背景信息、已执行完成的事。 4. 时间表达规范化：将"周五""下周一"转为具体日期（使用今天日期推算），无法推断时保留原文并标记 null。 5. 输出严格按 output schema 生成 JSON，不得添加额外字段。若没有待办，action_items 返回空数组。

这里的重点不是让模型"发挥理解力"，而是给它一组明确可遵守的规则，减少随机性。第 4 条里涉及日期推算，这种操作我强烈建议不要靠模型心算，而是在工具层封装一个parse_timestamps()函数做规则转换。凡是"算得准不准影响结果"的事，尽量交给代码而不是模型。

工具封装方面，我的习惯是把外部依赖（如文件解析、日期处理、文档转换）都包成独立函数，并给每个函数写清楚参数和返回值。这样技能内部就像一个微型应用，模型只在关键决策点上做判断，其他都走确定性代码路径。

提示：不要指望模型在 skill 内部做复杂计算。凡是可以用正则、解析器、库函数完成的事，都先在工具层做掉，只把真正需要语义理解的环节留给大模型。

3.3 测试skill：如何确定 agent 真的会"用"它

技能写完之后，第一件事不是接进主流程，而是先做两个层面的测试。

第一层是"调用测试"：模拟 agent 的决策环境，给出一系列用户请求，看模型是否能在正确的时候选中这个技能、传入正确的参数。这层测的是元信息质量。我一般准备 20 到 30 条用户说法，覆盖正向触发、近似触发、不该触发三类。正向示例像"帮我记一下今天会上说的待办"，近似示例像"这个文档里有什么行动项吗"，不该触发示例像"帮我算一下这个月的预算"。

第二层是"执行测试"：用固定输入跑技能内部逻辑，验证输出格式和内容正确性。这一步我会准备一份cases.yaml，每个用例包含输入、期望输出字段、允许的偏差范围。比如：

- input: "张三说：周五前给客户发报价。李四点了个赞。" expect: action_items_length: 1 first_task_contains: "给客户发报价" first_owner: "张三"

执行测试跑过之后，再考虑接入真实 agent 流程。很多人跳过了这两层直接上生产，结果模型根本不知道怎么触发技能，还以为是模型能力问题，其实纯粹是元信息没写好。

3.4 注册与热加载：让 skill 进入 agent 的运行流程

技能写好了、测好了，最后一步是注册。不同 agent 框架的注册方式不同，但核心思路一致：把技能列表注入到 agent 的可用工具/技能集合中，让主模型在每次决策时都能看到它。

以常见的伪代码为例：

from agent import Agent from skill_registry import load_skills skills = load_skills("./skills") # 扫描目录，解析 skill.yaml agent = Agent( model="your-model", skills=skills, # 注入技能集合 memory_enabled=True ) # 运行时自动路由：用户请求 -> 模型决策 -> 触发对应 skill result = agent.run("帮我记一下今天会议里的待办")

这里有个容易踩的坑：技能列表不是越多越好。每个技能的描述都会占据上下文窗口，技能数量多了，模型反而看不过来，触发准确率会下降。我自己的经验是单个 agent 同时挂载的技能数最好控制在 10 个以内，超过了就要考虑做按场景分组的动态加载。比如按用户意图先粗分类，再加载对应分组下的技能，类似"先选工具箱，再从箱子里拿工具"。

另外，升级技能时建议保留版本号，并做灰度。不要今天改完 description 明天就全量上线，因为 description 一旦变了，模型的触发行为会发生整体偏移，可能会误伤其他技能的触发率。我一般会先在测试环境跑一轮调用测试，确认新描述下所有正向、近似的用户说法都被正确路由，才推到线上。

4. 常见问题与排查速查表

4.1 技能不被触发、触发错乱、上下文污染

我在实际项目中遇到的第一个大问题就是"技能不被触发"。排查下来多数原因集中在description上：要么描述太技术化，和用户真实说法对不上；要么描述太泛，模型觉得用户的问题不配用这个技能。解决办法是回到 3.1 里说的——把用户可能的表达方式写进 description 的触发信号里，并且用真实对话语料去验证。

第二个常见问题是"触发错乱"。比如用户想提取待办，模型却调了"会议总结"技能。这往往是两个技能的 description 有重叠，边界没划清。我的排查方法是把所有技能的 description 拉到一个表里逐条比对，凡是我自己都分不清边界的，模型一定也分不清。这时候就要调整表述，给每个技能一个排他性触发词。

第三个问题是上下文污染。有的技能会往对话历史里回写大段执行日志，导致后续轮次模型把这些日志当成用户内容，行为异常。我的做法是技能的输出尽量精简，只返回最终结果和关键中间量，执行细节放在日志里异步落盘，不要回灌给主模型。

4.2 性能、安全与可维护性坑点

性能方面，一个常见坑是技能内部的工具调用串行太多。比如先调一次转写 API、再调一次待办抽取、再调一次日历写入，每一步都是一次网络往返，延迟叠加后用户体感非常差。优化方向有两个：一是把能并行的调用改为并行；二是减少大模型在技能内部的调用次数，把可确定化的判断改成规则代码，能省一次模型调用就省一次。

安全方面要特别注意工具权限收敛。技能一旦可以自由调用外部工具，模型就可能因为指令注入，把用户输入里的恶意内容当成指令传给工具。我在技能里加了输入过滤和工具白名单：技能能访问的 API 列表在元信息里声明，运行时动态校验，不在白名单的直接拒绝。

可维护性方面，技能库很容易腐化。新增技能没人清理旧的、说明文档过期、测试用例没跟上，半年后技能库就变成了代码沼泽。我的建议是每个技能必须有 owner、version、测试用例，并在 CI 里跑一轮基础调用测试，保证元信息格式合法、输出 schema 不破损。

4.3 快速定位问题：一份排查清单

我整理了一份很朴素但非常有效的排查顺序清单，每次技能行为不对，就按顺序过一遍：

1. 技能是否被正确注册？先看运行日志里有没有技能被调用的记录。
2. description 是否清楚？把用户原话和 description 放到一个模型里，问它"你会在什么情况下用这个技能"，看输出是否一致。
3. 入参是否符合 schema？把模型实际传入的参数打印出来，和 yaml 定义比对。
4. instructions 是否被遵守？检查完整输出，看它有没有按你定义的步骤执行，还是跳步了。
5. 输出是否符合 schema？用校验脚本跑一遍，别靠肉眼。
6. 是不是上下文太长导致模型丢失规则？尝试把关键规则压缩到 1 到 2 条，放到最前面。

这份清单我贴在自己项目文档最前面，每次出事照着走，基本十分钟内能定位问题到底出在哪一层。

5. 最后分享一点个人体会

说实话，agent-skills 这条路我也是踩了一堆坑才摸到门道。最早我也觉得给 agent 写 prompt 就够了，后来发现凡是"稳定产出"的要求，最终都得靠结构化技能来兜底。现在我做 agent 项目的流程基本固定：先列出所有反复出现的任务，再逐个设计技能边界和契约，然后实现和测试，最后才考虑主流程怎么串联。技能库越来越像一个内部小工具库，agent 每次干活都像在调用经过验证的接口，而不是临时发挥一段文字。

如果这篇文章对你有一点帮助，建议你从手头最痛的那个重复性任务开始试：把它的执行步骤拆出来，写成第一个 skill，跑一遍调用测试。你很快就会感受到，把能力真正沉淀下来之后，agent 的稳定性会好很多。