企业官网建设流程全解析

1. 先看本质：agent-skills 到底解决的是什么问题

1.1 从聊天机器人到智能体，差的就是这套“肌肉记忆”

我最早做 AI 应用的时候，思路特别朴素：把大模型接上，写一段很长很长的系统提示词，然后祈祷它在各种奇怪的输入下都能稳定输出。结果大家都知道的——同一个问题换个说法，效果就飘忽不定；稍微复杂点的任务，模型会突然“忘了”你半小时前给它定的规矩；更别提多步骤任务做到一半，它自己就开始自由发挥了。

后来我接触了 agent-skills 这个概念，才意识到问题不出在模型本身，而出在我的使用方式。

把大模型比作一个刚毕业的高材生：底子很好，但你没法指望靠口头嘱咐两句，它就能把你脑子里的所有业务套路全部执行到位。而 agent-skills 是给这个高材生配了一整套“肌肉记忆”——拆解任务、调用某个具体能力、按固定流程走、输出固定格式，每一步都有明确的操作手册和专用工具。它干的活，就是把那些你反复重复、反复调整、反复踩坑才总结出来的最优做法，固化下来，让智能体下次直接调用。

换句话说，普通聊天式交互是“每次从零开始推理”，而带 skills 的智能体是“按需调用已经验证过的能力”。从零推理意味着不确定，而调用已验证的技能意味着稳定、可复现、可度量。这是智能体能不能真正落地的分水岭。

1.2 skill、tool、plugin、workflow，别把这几样东西混为一谈

很多人一上手就会发现另一个困扰：一会儿看到 tool，一会儿看到 plugin，一会儿看到 skill，一会儿看到 workflow，它们到底啥关系？我一开始也被绕晕了，后来用自己的话梳理了一遍，大概是这样的维度：

_skill 和 tool 最关键的区别在于：tool 只负责“执行某一步”，skill 负责“把整个事情做成”。** 我做会议纪要，不能只用一个“提取文本”工具——我需要判断哪些话是决策、哪些是闲聊，需要区分行动项、责任人、截止时间，需要按固定模板输出。这个“判断+调用+组织输出”的过程，才是 skill 真正存在的意义。

1.3 一个标准 skill 应该长什么样

我在实践中逐渐总结出一个靠谱的 skill 必须具备的四要素：

• 声明（Manifest）：这个技能叫什么、干什么用、接受什么参数、返回什么结果。就像函数签名，是给智能体看的“说明书”。
• 执行逻辑（Execution Logic）：要么是一段 prompt 模板，要么是一段可执行代码，要么是两者的组合。这是技能的核心动作。
• 示例（Examples）：最好有 2-3 个完整输入输出对。实测下来，示例对模型稳定性的提升比任何“强调语气”的提示词都管用。
• 兜底策略（Fallback）：技能失败、输出格式不对、参数校验不通过时怎么办。没有兜底的技能等于没有安全气囊。

这四样东西缺一不可。尤其是兜底策略，我一开始完全忽略了，直到一次线上调用时模型突然吐了一堆 Markdown 语法混乱的脏数据，直接导致下游解析程序崩溃。从那以后，每个 skill 我都强制要求带上“输出校验+失败重试+放弃降级”三层保险。

2. 设计一套 skill 库：动手之前先把结构想清楚

2.1 按“动作”划分，别按“场景”划分

我见过很多人一开始就按场景建技能，比如建一个“生成周报”的技能、一个“生成日报”的技能、一个“生成项目总结”的技能。结果做着做着就会发现，这些技能里 80% 的逻辑都在重复——都是“从一堆杂乱信息里提取关键内容，按模板组织成汇报格式”。

我自己摸索出来的经验是：_skill 应该按动作（动词）来划分，而不是按场景（名词）来划分。**

同一类动作，不管用在什么场景下，核心处理逻辑都是相近的。比如：

• extract：从非结构化文本里抽结构化字段
• summarize：压缩信息量，保留关键结论
• compare：多份内容之间的差异对比
• translate：跨语言/跨术语体系的转换
• search：在指定数据源里查找匹配内容

场景层面的差异化，交给参数和配置来处理，而不是靠复制一份新的 skill 来处理。也就是说，“生成周报”不是一个新的技能，而是summarize技能传入一个“周报模板”参数，再加上一个数据源配置。“生成日报”同理。

这样做的好处非常明显：技能数量可控、维护成本低、复用率高。我第二次重构技能库的时候，把原来 30 多个场景技能压缩到了 12 个动作技能，反而覆盖了更多业务场景。

2.2 原子技能与复合技能：两层结构最稳

在按动作划分的基础上，我还把整个技能库分成了两层，这件事我认为是整个设计里最重要的决定。

第一层是原子技能（Atomic Skill）。它做且只做一件小事，不依赖其他技能。比如“提取文本摘要”“从文本中识别日期”“计算两个时间点之间的工作日数量”。原子技能的特点是：输入输出都极其简单、边界清晰、容易测试。

第二层是复合技能（Composite Skill）。它不直接干活，而是负责编排：按顺序调用多个原子技能、判断中间结果、决定下一步走哪个分支。

举个例子：我做一个“会议纪要约人”的功能，看起来是一个操作，实际上需要这两个层级配合——

1. 用extract_action_items从会议转写里抽出行动项
2. 用extract_people识别每个行动项对应的负责人
3. 用format_schedule把负责人+任务+截止时间拼成日历邀请的文本
4. 最后用send_message把消息发出去

前三个是原子技能，第四个是外部工具。而把这三个原子技能加一个工具串起来的整体，才叫“会议纪要约人”这个复合技能。复合技能本身也像一个技能，可以被更高层的技能再调用。

这种两层结构极其好用，因为它让我的调试粒度变得很清晰。线上出问题的时候，我能快速定位到是哪个原子的环节出了偏差，而不必在三百行 prompt 里大海捞针。

2.3 命名规范和元信息：技能也得有“门牌号”

技能一多，没有规范就是灾难。我自己踩过这个坑：建了十几个技能之后，回头想找“从文档里提取表格数据”那个技能，发现它的名字叫data_parser_v2_final，我愣是看了半天才认出来。

从那以后，我定了一套规矩：

• 命名格式：动词_对象_产出，比如extract_table_from_doc、summarize_long_text、convert_json_to_yaml
• 时间/版本后缀一律不出现在正式名字里，版本信息放元数据字段
• 每个技能必须声明以下元信息：
  • 用途描述（200 字以内，说清楚什么时候该用这个技能）
  • 输入参数（参数名、类型、是否必填、取值范围）
  • 输出格式（结构化的 schema 或模板）
  • 适用条件（哪些情况下调用这个技能）
  • 不适用条件（哪些情况下千万别调它）
  • 成本级别（低/中/高，用于路由决策时排序）

这套元信息最一开始是给智能体看的，后来发现对团队协作的帮助更大——新同事接手的时候，不需要翻聊天记录就能搞清楚每个技能是干嘛的，这体验比什么都重要。

2.4 版本管理：技能不是写出来就完了，要持续迭代

很多做 agent 的人有个习惯：prompt 调好了就扔在那，直到线上出问题才想起来看一眼。但场景是会变的，同样的技能，上周效果好，这周模型接口升级了、数据格式变了，效果就可能明显下滑。

所以我后来把技能库当成代码库来管：

• 每个技能独立一个目录，里面包含声明文件、执行逻辑、测试用例、变更记录
• 每个技能都打语义化版本号（1.0.0 → 1.1.0 → 2.0.0）
• 重大变更（比如输出格式改了）必须走新的 major 版本，旧版本还能用
• 每次修改都要求在变更记录里写清楚“改了什么、为什么改、影响范围是什么”

听起来很繁琐，但一旦技能库超过 20 个技能，没有这套机制你会付出十倍的时间去还债。具体来说，我遇到过最崩溃的一次：某个底层原子技能改了内部处理逻辑，结果上层五个复合技能的输出格式全都跟着变了，而我因为没做版本隔离，排查了一整天才找到根因。

3. 完整实操：从零手写一个“会议纪要结构化”技能

3.1 需求拆解：先明确输入和输出，再想中间怎么写

理论说了那么多，还是上手写一个最实在。我以“把一段会议录音转写文本变成结构化会议纪要”为例，走一遍完整的实现流程。

需求描述：输入是一段口语化的会议转写文本（可能夹杂着口头禅、打断、跑题），输出是一份结构化 Markdown 纪要，包含：

• 参会人列表
• 讨论主题清单
• 决策项清单
• 行动项清单（每项包含负责人、动作描述、截止时间）
• 遗留问题清单

这个需求看起来很常规，但真做起来有几个难点：口语转写的文本里没有标点符号标准化；人名可能是“老张”“那个搞运营的”这种指代；时间点是“周五之前”“下周一下午”这种相对描述，而不是“2025-03-14”。

3.2 定义技能声明：写清楚“这个技能能干什么”

我先写一份技能声明。这个文件的作用，是让智能体在决定“该调哪个技能”的时候能快速匹配。

name: extract_meeting_minutes description: 将一段会议录音转写文本转换为结构化的会议纪要，提取决策、行动项和遗留问题。 version: 1.2.0 parameters: transcript: type: string required: true description: 会议转写原文，纯文本格式 participants: type: array items: string required: false description: 已知参会人名单，辅助人名识别 output_format: type: string enum: [markdown, json] default: markdown description: 输出格式 output_schema: type: object properties: participants: type: array items: string agenda_topics: type: array items: string decisions: type: array items: decision: string context: string action_items: type: array items: owner: string task: string deadline: string open_questions: type: array items: string false_positive_hints: - 如果输入文本明显不是一个会议的转写，请拒绝执行并说明原因 - 如果转写文本少于 200 字，大概率是片段而非完整会议

这份声明最核心的是description字段——不要太长，但要准确概括“什么场景用得上”。我把“会议”和“转写”两个关键词放进去，就是为了让路由匹配时命中率高一些。

3.3 编写执行逻辑：用“两步走”稳定输出

核心执行逻辑我选择了“代码+prompt 混合”的方式，而不是纯 prompt。原因是纯 prompt 处理格式化的稳定度不够，经常出现字段缺失、结构错乱的问题，而后处理代码可以做兜底校验。

import json import re def extract_meeting_minutes(transcript, participants=None, output_format="markdown"): # Step 1: 调用大模型做语义提取，返回结构化 JSON prompt = build_extraction_prompt(transcript, participants) raw = call_llm(prompt, response_format="json") # Step 2: 解析并校验 JSON 结构 try: data = json.loads(raw) except json.JSONDecodeError: # 兜底方案：用一次正则提取，补一个宽松的 JSON data = fallback_extract(raw) normalized = normalize_output(data, participants) # Step 3: 按需输出格式 if output_format == "json": return json.dumps(normalized, ensure_ascii=False, indent=2) return to_markdown(normalized) def build_extraction_prompt(transcript, participants): known = "、".join(participants) if participants else "未知" return f""" 你是一名会议助理。请从以下会议转写文本中提取结构化信息。 已知参会人：{known} 必须提取以下几类信息： 1. participants 参会人（如果有指代，结合上下文推断全名） 2. agenda_topics 讨论主题（每条不超过15个字） 3. decisions 决策项（每个决策要记录背景和最终结论） 4. action_items 行动项（owner，task，deadline三字段都要有；deadline无法确定时写"未明确"） 5. open_questions 遗留问题 要求： - 只输出 JSON 对象，不要输出任何其他文字 - 行动项中的 deadline，如果是"周五之前"，转换为最近的周五日期；如果是"下周"，转换为下周一的日期 - 不确定的信息，宁可写"待确认"，也不要编造 原始文本： {transcript} """

另一个关键函数是normalize_output，它做了三件事：缺失字段补默认值、deadline格式统一为YYYY-MM-DD（转不了的就挂“待确认”标记）、去重和排序。这些后处理逻辑虽然不复杂，却把输出的稳定性从“看模型心情”拉到了“99% 能被下游直接消费”的水平。

3.4 注册与调用：让智能体知道有这么个技能

执行逻辑写完之后，不是把代码扔进项目里就完事了，还需要把技能注册到 agent 的能力清单里。这个清单相当于一个“索引”，agent 每次接到任务时会先扫一遍，看看哪个技能匹配当前需求。

我一般用的注册方式是维护一个技能路由表：

skills_registry = { "extract_meeting_minutes": { "handler": extract_meeting_minutes, "manifest": load_manifest("extract_meeting_minutes"), "priority": 1, "capability_tags": ["meeting", "minutes", "extraction", "transcript"], }, "summarize_long_text": { "handler": summarize_long_text, "manifest": load_manifest("summarize_long_text"), "priority": 2, "capability_tags": ["summary", "condense"], }, }

agent 的调度逻辑大概长这样：来了一个任务 → 解析任务里的关键意图词 → 和每个技能的capability_tags做相似度匹配 → 匹配度超过阈值就进入候选列表 → 按优先级和成本排序 → 调用最高优先级的那个技能。

这个机制不复杂，但非常实用。它会自然形成“先精确技能、后通用技能”的调用偏好。比如“帮我总结上个月所有会议的要点”，就该让summarize_long_text来处理，而不是硬套extract_meeting_minutes——因为它需要的是跨多份材料的压缩，而不是单份文本的字段提取。

3.5 实测反馈：第一次跑通和第一次翻车

这个技能我第一次实际测试时，输入了一段 15 分钟的会议转写，大概 5000 字，模型吐出来的 JSON 结构基本正确，但有三个明显问题：

1. 参会人名称识别错了：一个人被抓成了两个不同的人，因为转写里有“小王”和“王组”两种叫法，模型认为是两个人。
2. deadline 换算错误：原话是“这周五前给我”，模型把“这周五”错误理解成了系统时间对应的日子，而不是会议语境里说的那个周五。
3. 行动项遗漏：有一段 30 秒的对话，两个人快速敲定了一个计划，模型没有把它识别为行动项，因为里面包含了大量口语插话，信息密度被稀释了。

这三个问题的解法各有不同：

• 问题一，我加入了一个“同义指代合并”的后处理步骤，结合已知参会人列表，对提取出来的名字做模糊匹配，合并置信度高的同指名字。
• 问题二，我在 prompt 里加了“deadline 换算必须基于会议发生的日期，而不是当前系统日期”，同时把会议日期作为一个参数传入。
• 问题三，我调整了 prompt 的句式，明确要求“判断标准是出现了谁在什么时候要完成某事，即使中间夹杂无关对话，也要提取这句话”，并在示例里加了一个包含插话的困难样例。

改完之后，这个技能的输出准确率从 75% 提升到了 90% 左右。而且这些经验都沉淀在了技能的变更记录里，下次其他技能遇到同类问题，我直接翻记录就能快速定位，而不用从头调试。

4. 真实环境里踩过的坑：问题排查与避坑实录

4.1 技能冲突：两个技能都想处理同一个输入

技能库建到一定规模后，最头疼的问题不是“技能不会干活”，而是“技能抢活干”。比如输入文本是一封邮件，extract_action_items会觉得里面有行动项，summarize_email会觉得应该提炼摘要，auto_reply_draft又觉得自己能生成回信草稿，三个技能同时被候选选中了。

我踩过这个坑后，在路由层加了两道保险：

• 第一道，在技能声明里写false_positive_hints，明确告诉路由这个技能“不适用”的场景是什么。这个反向约束的作用非常大，因为大部分技能描述只写了“什么时候适用”，但真正干扰路由的往往是“看起来适用但实际上不该用”的情况。
• 第二道，在候选列表里设置优先级权重：精确匹配的动词意图（比如“提取”）永远排在宽泛意图（比如“总结”）前面。我们还给每个技能配了一个“触发成本”——执行成本高的技能默认往后排，避免动不动就用一个重型技能处理轻量任务。

加完这两道保险，技能冲突率显著下降。而且我发现，很多“路由错误”本质上是技能边界模糊的问题。如果一个技能描述里出现了“也适合做……”“偶尔可以……”这类含糊表述，就会在路由匹配时制造歧义。所以我在重构时对自己立了个规矩：技能的边界描述宁窄勿宽，宁可有些输入匹配不上然后走通用兜底，也不要匹配错了用错技能去处理。

4.2 上下文污染：技能输出比预想的大十倍

还有个特别隐蔽的问题，我称之为“上下文污染”。

场景是这样的：我让一个复合技能先调用extract_action_items提取行动项，再基于结果生成跟进邮件。问题出在extract_action_items返回的结果里携带了大量模型推理的中间过程——它把“为什么认这段话是行动项”的分析也写进了返回内容。

这些中间推理没啥用，但占着上下文窗口。更糟的是，下游步骤在生成邮件时会把“上一轮的中间分析”误认为“本轮任务的额外指令”，导致邮件文案里莫名其妙多出来一段类似“基于以上分析，我认为这个行动项应该由小王负责，理由是……”的话，非常令人崩溃。

我的解决方案有三步：

• 每个技能的返回结果必须是“干净数据”，不允许携带任何推理过程和中间说明。这由后处理层的clean_response统一把关。
• 复合技能在调用子技能后，主动做一个上下文压缩：只保留子技能返回的结构化字段，丢弃全部原始推理文本。
• 为每个关键技能设置输出长度上限，超过阈值就自动降级为“结果摘要+完整结果落盘”，避免上下文被撑爆。

三步走完，这种污染问题基本绝迹。说实话，这个坑属于“不踩一次根本想不到”的类型，但它对智能体稳定性的影响远超我的预期，所以特别值得写出来提醒大家。

4.3 大模型输出不稳定的根源与对策

即便是同一个模型、同一个 prompt、同一份输入，输出也可能不一样——这我们管不住。但我们在实际运行中发现，“输出不稳定”很多时候并不是模型随机性导致的，而是输入里的无关噪声在干扰。

比如一份转写文本里，有一段参与者讨论午饭吃什么，模型就容易在提取“决策项”时把“午饭去吃火锅”也算成一次决策。这不是模型笨，而是因为提示词里的“决策”两个字不够具体——午饭吃什么确实是个决定，但显然不是我们想要的“跨部门决策”。

对策是重新定义对“决策”的判断标准：必须是影响项目方向、资源分配、流程变更或对外承诺的决定，才叫决策。我在 prompt 里加了一个排除清单：日常工作安排、个人偏好选择、无后续动作的闲聊，即使听起来像决定，也不提取。这个排除清单在减少垃圾输出上立竿见影。

另外，对于 JSON 输出，模型偶尔会漏掉必填字段或者多出一个未知字段，所以我在后处理里写了一个 schema 校验器：字段缺失时用null占位并记一条 warning；出现未知字段时直接剥离；如果整个 JSON 都解析失败，就触发一次带纠错提示的重试——所谓纠错提示，就是把上次的错误信息拼进 prompt 里，让模型自己看看错在哪再改一遍。实测下来，第一轮失败后重试成功的概率超过 80%，效果很理想。

4.4 成本与延迟失控：技能越多不一定越好

这个坑在把技能库扩展得太快时尤为明显。复合技能每多调一个子技能，就要多一轮模型调用，延迟和 token 成本都是线性甚至超线性地涨。我做过一个“舆情分析报告”技能，原本想着分五步逐步分析，结果单次完整调用消耗了近 5 万 token，耗时长达 3 分多钟——用户根本等不起。

后来我怎么优化的呢？

• 优先用“一个模型调用内完成任务”的方式，而不是动不动就拆成多步串联。这取决于任务的复杂度和模型的能力上限。
• 多个子技能之间没有严格依赖关系的，改成并行调用，而不是串行。比如提取行动项和提取参会人这两个任务完全可以同时进行，没必要排队。
• 高频调用同一个技能时，把结果缓存起来。尤其是summarize类的技能，输入没变就不需要重新计算。
• 给每个复合技能设定“成本预算”。如果预估调用链路过长，就先生成一份阶段中间结果，让用户确认后再继续，而不是一口气跑完。

延迟问题本质上是一个“技能编排的粒度”问题：拆得太粗，一步错步步错；拆得太细，成本直线上升。经验值大概是——一个复合技能内部串行调用的子技能最好不超过三个，超过三个就要考虑并行化或者合并成一步完成。

4.5 测试策略：没有自动化测试，技能库迟早要烂

我特别想说的一点是：技能也是代码，代码就得有测试。很多做提示词工程的人不写测试，是因为觉得提示词的“输出”没法断言。但我的经验是，可以换一个角度来测——不测“模型输出的具体句子”，而是测“结构化结果是否满足 schema 约束、关键字段是否非空、数值范围是否合法、特定规则是否被遵守”。

我维护的每个技能都有至少五组测试用例：正常样例、边界样例、特殊格式样例、明显不该调用该技能的样例、以及用于检测“幻觉”的对抗样例。对抗样例里我会故意放一些诱导性文本，比如“我不需要任何分析，直接随便编一份报告”，然后测试技能会不会拒绝执行。

不要小看这个测试设计。我已经不止一次通过回归测试救回了即将上线的版本——某次底层模型升级后，一个技能识别地名的能力突然退化，常规测试用例没测出来，但对抗样例里的一个“地名重复出现”用例稳稳地抓住了问题。从那以后，我每次更新技能或更换模型接口，都会先跑一遍全量测试集，全绿才敢继续。

5. 从个人技能库到团队基础设施

5.1 跨项目复用：技能的“公共底座”抽象

当技能库规模增长到一定程度，你会发现不同项目之间对技能的需求高度重合。比如不管做什么项目，都需要文本清洗、要点提取、格式转换这三类基础能力。

这时候就该做一层“公共底座”，把这几个高频原子技能抽成独立包，供所有项目共用。而各个业务方的差异化逻辑，通过配置参数和自定义模板来实现。比如你的项目要生成特定格式的周报，底层用公共的summarize技能，上层传一个你的周报模板进去就好。

这种做法和写代码时的公共库抽象本质上是同一件事。好处不多说了，最大的痛点是版本兼容——公共底座一旦升级，可能波及所有下游项目。所以我定了一个规则：公共技能的变更必须保持向后兼容，必须升级才能用新特性的，至少提前一个月公告，并提供一个迁移脚本。这一条在团队规模超过三个项目之后，能省下巨额的沟通成本。

5.2 可观测性：每个技能都要能被“复盘”

技能跑得好不好，不能靠直觉，得靠数据。我后来给技能库加了一套可观测性面板，每次调用都记录这些信息：

• 输入摘要（文本长度、格式类型、来源）
• 路由结果（命中了哪个技能、置信度多少、候选列表里都有谁）
• 执行时长和 token 消耗
• 输出校验结果（字段完整度、异常标记）
• 下游反馈（这个技能输出的内容，最终有没有被用户或下游系统采纳）

有了这些数据，就能回答很多凭直觉答不了的问题：哪个技能成功率最低？哪个技能最耗钱？哪个技能经常被路由误触发？哪个技能的修改造成了隐性副作用？

有一次我们优化某个技能，发现它的调用成功率在最近两周掉了 15%，可日志里根本看不到报错。后来翻了详细数据才发现，是某个数据源的内容格式变了，技能输出字段的老映射逻辑没跟上。这种问题，没有可观测性面板就是两眼一抹黑。

5.3 后续还能往哪些方向扩展

做完以上这些，技能库才算是一个能稳定运行的东西。再往后，有几个方向值得探索：

• 技能的自适应生成：让智能体根据一个从未见过的新任务，自动组合已有技能来应对。这本质上是从“按需调用”迈向“动态编排”的一步。
• 技能效果的持续评估：引入一组带标注的基准集，每次技能变更后自动跑分，用分数替代直觉判断。
• 跨组织技能共享：如果技能库足够成熟，不同团队之间可以用“技能市场”的形式共享已验证的能力，互相省一遍探索成本。

这些方向我没有全部落地，但单是“技能效果持续评估”这一个点，就已经让我意识到：技能库的建设不是一次性工程，它更像是一套持续投入的基础设施。初期把声明、测试、版本管理、可观测性这些骨架搭好，后期所有迭代才能稳步推进，而不是越改越乱。

我自己在两三个项目的实战里反复调整了快一年，最大的体会是：_agent 的可用性从来不取决于模型多聪明，而取决于你给了它多少确定性。** 技能库本质上就是在给智能体注入一种“职业素养”——知道在什么场合做什么事、按什么标准交付、出了岔子怎么补救。把这件事做好，你会发现原来飘忽不定的智能体，渐渐变得像一个真正懂业务、靠谱的同事了。