企业官网建设流程全解析

最近我一直在捣鼓一套以“skills”命名的智能体技能库，起因是团队内部折腾了大半年的助手型应用，前期效果一直飘忽不定，换了好几个模型都差不多的表现。后来复盘发现，问题根本不在于模型选型，而在于给模型配置的“做事能力”太碎片化。这也让我下决心把整个技能体系重新梳理了一遍，从技能包的结构设计、目录约定、参数Schema，到脚本实现、测试回归、部署维护，完完整整走了一轮。今天这篇就是把这段实操过程里最关键的思路和踩过的坑整理出来，希望对正在做Agent落地或者被LLM应用工程化折磨的同行有点用。

全文围绕“如何设计一套高质量、可复用、可维护的Agent技能包”展开，适合三类人阅读：刚接触Agent开发、想给智能体配置工具能力的新手；已经在用Function Calling但觉得流程混乱、不好维护的开发者；以及负责智能体工程质量、想把团队技能资产规范化的技术负责人。

1. Skill是什么：先把技能包的定位彻底想清楚

1.1 会聊天的模型，怎么变成会干活的Agent

大模型本身的能力边界其实很清晰：它擅长的是文本理解、生成、推断和对话，但“做一件事”往往需要调用外部系统、处理文件、执行计算、读取数据库，这些能力大模型原生并不具备。所谓Agent技能，简单说就是把“完成某一类具体任务需要的知识、流程、参数规则、代码实现”打包成一个标准模块，交给大模型按需调用。

我用一个偏生活化的例子来解释：模型就像一个经验丰富但不会使用任何工具的实习生，他聪明、反应快、理解力强，但你要让他写一份报表，他需要你给他配好Excel模板、告诉他数据源在哪、甚至把公式都写好，他才可能把活干完。这里的“Excel模板+操作说明+公式文件”就相当于一个技能包，而“实习生”就是大模型。没有技能包，模型能力再强也只能泛泛而谈，一落到具体任务就露馅。

1.2 Prompt、Tool、Skill，边界到底在哪

很多同学会把Prompt工程、Tool调用和Skill三者混在一起。按我现在的理解，它们解决的问题层次完全不同：

• Prompt是告诉模型“用什么样的态度和口吻回答问题”，解决的是表达层的问题；
• Tool是给模型一个可调用的外部函数，解决的是“能调什么”的问题；
• Skill则是把“完成一类目标所需的一系列Tool调用、业务规则、数据处理逻辑、输出格式约定”组合成一套完整流程，它更像是业务流程的原子封装。

比如你要做一个“会议纪要整理”的功能，单个Tool可能只负责分词、提取关键词、生成摘要；而一个Skill会定义清楚：接收什么格式的原始文本、如何清洗、如何提取发言人、如何按议题归类、最终输出什么样的JSON结构、失败时怎么兜底，甚至还会附带测试样本。Tool是零件，Skill是装配好的部件，这个定位一定要想清楚。

1.3 一套合格的技能包该包含什么

在动手写代码之前，先界定技能包的边界。我实践下来，一套完整、合格的技能包至少应该包含四部分：

• 能力说明书（说明这个技能解决什么问题、什么场景下触发、输入输出约定）；
• 参数定义（结构化描述，包括类型、是否必填、默认值、取值范围）；
• 核心逻辑实现（真正执行任务的脚本或程序，要能独立运行）；
• 测试与样本数据（用于验证和回归，也方便其他人理解使用方式）。

这里特别提醒一句：不要把会话记忆、用户鉴权之类的状态管理塞进技能包里。技能包应该是无状态的，每次调用只针对当前输入做处理。一旦它依赖外部状态，排查问题和复用都会变得极其痛苦。

2. 技能包的目录约定：为什么每个目录都重要

2.1 SKILL.md是说明书，也是路由表

一个技能包最好是一个独立目录，目录里最显眼的就是SKILL.md文件。这个文件既是给人类看的说明文档，也是给大模型看的“路由表”。大模型需要根据用户请求去匹配技能包，它的判断依据主要来自SKILL.md里的描述信息。如果描述写得过于宽泛，比如“处理文本”，那模型会一脸茫然；如果写得过于狭窄，比如“仅处理2024年Q3销售会议纪要”，那稍微变化场景就匹配不上。

我自己的经验是，SKILL.md要包含几个关键字段：

• 技能名称，保持简短并且有区分度；
• 一句话说明，说清楚这个技能到底做什么；
• 适用场景，列举具体的前置条件和触发例子；
• 输入参数的定义，包括类型、必填、格式；
• 输出结构说明，包括成功和失败两种情况；
• 使用限制和依赖说明。

2.2 代码目录：逻辑只放脚本，不让模型自由发挥

技能包中的核心处理逻辑通常放在scripts子目录里。这里有一条重要的设计原则：宁可自己在脚本里写清楚每一步的逻辑，也不要指望大模型临时在对话里创作代码去执行。原因很简单，模型生成代码的不确定性太高，而且上下文窗口有限，复杂的逻辑放对话里容易截断或遗忘。

代码目录按功能模块拆分，不要把几十个功能揉在一个文件里。我习惯的拆法是：

• 入口脚本：只负责接收输入、调用处理函数、输出结果；
• 核心处理模块：负责特定的算法或业务逻辑；
• 工具函数模块：放一些日志、校验、文本清洗等可复用的基础能力。

这样拆分的好处是，后续加功能基本不动入口，只改对应模块，出问题也能快速定位到是哪一层出了问题。

2.3 样本与模板：评测和演示都靠它

很多开发者会忽略sample或examples目录，但实际做下来，这部分的价值非常高。每个技能包都应该带上两到三份代表性的样本数据，包括典型的输入和对应的期望输出。这里有两层意义：第一是在开发调试阶段，可以直接用样本跑通流程；第二是后续技能包升级时，样本可以作为回归测试的基准，防止改一处代码破坏了原有功能。

样本建议覆盖正常情况、边界情况和失败情况三类。比如一个“信息提取”技能，正常情况是一段结构清晰的文本；边界情况是文本特别短或特别长；失败情况是输入为空或完全不符合预期格式。有了这三类样本，不仅能验证脚本逻辑，还能观察模型在技能触发前的筛选行为是否准确。

3. 实操：把会议纪要整理做成标准技能包

3.1 先定好输入输出，再写第一行代码

我拿“会议纪要整理”这个典型场景来说。当时需求是：给Agent一段会议的文字记录，它能自动生成包含参会人、议题、决策、待办事项的结构化纪要，并输出为JSON格式给下游系统使用。

动手前，我先把输入输出定义清楚：

输入是一个字符串，内容是会议的逐字稿或速记文本，可能包含时间戳、发言人信息、临时插入的闲聊内容。输出是一个JSON对象，顶层字段包括会议概要、与会者列表、议题数组、决议数组、待办事项数组。定义完输入输出，整个技能的代码结构就变得非常清晰了。

3.2 从SKILL.md到核心处理逻辑，一步步落地

SKILL.md我写了这样一个简化但结构完整的版本：

--- name: meeting_minutes_extractor description: 从会议文字记录中提取结构化会议纪要，生成包含概要、议题、决议和待办事项的JSON输出。 applicable_scenarios: - 输入一段会议录音转写文本或速记内容，要求输出结构化会议纪要 - 输入包含多个议题讨论过程的文字记录，需要拆分议题并归类决议 inputs: transcript: type: string required: true description: 会议文字记录，建议传入完整原文而不是分段摘要 include_action_items: type: boolean required: false default: true description: 是否提取待办事项，默认开启 outputs: summary: type: object description: 结构化会议信息，包含overview、participants、topics、decisions、action_items等字段 dependencies: - python 3.10+ - 无第三方依赖库

然后开始写scripts/extract_meeting.py。核心处理逻辑长得像这样：

import json import re def clean_text(raw_text: str) -> str: # 移除多余空白行，保留段落结构 lines = [line.strip() for line in raw_text.splitlines() if line.strip()] return "\n".join(lines) def extract_participants(text: str) -> list[str]: # 通过发言前缀模式识别参与者，例如“张伟：”“李静：” pattern = r"^([\u4e00-\u9fa5]{2,4})\s*[:：]" participants = [] for line in text.splitlines(): match = re.match(pattern, line) if match and match.group(1) not in participants: participants.append(match.group(1)) return participants def split_topics(text: str) -> list[dict]: # 按“议题一/议题二”等标记切分段落 sections = re.split(r"议题[一二三四五六七八九十]", text) ... def build_action_items(text: str) -> list[dict]: # 识别“待办：”“跟进：”等位置，提取任务描述与负责人 ... def main(raw_text: str, include_action_items: bool = True) -> str: cleaned = clean_text(raw_text) result = { "overview": summarize(cleaned), "participants": extract_participants(cleaned), "topics": split_topics(cleaned), "decisions": extract_decisions(cleaned), "action_items": build_action_items(cleaned) if include_action_items else [] } return json.dumps(result, ensure_ascii=False, indent=2)

这段代码的作用是让技能包在离线环境下也能完成“文本转结构”的核心工作。哪怕后面接入的模型能力有变化，只要这段逻辑稳定，下游业务就不会受太大影响。这也是我把处理重心放在脚本、而不是让模型自由生成结果的最重要原因。

3.3 端到端测试与实际投入使用时遇到的坑

写完代码不代表完事，真正花时间的是端到端验证。我先用三段样本数据跑了一遍：一段正常会议记录、一段带有大量语气词和插话的记录、一段只有一句话的极简记录。正常记录跑下来效果符合预期；语气词记录导致参会人识别不准确，因为发言前缀里混入了“嗯嗯”“好的”之类；极简记录则直接让议题切分失效，最终返回空数组。

这几个问题让我意识到，技能包不能只处理理想输入。核心逻辑里必须加清洗规则和兜底逻辑：语气词和插话要在分词前提滤波除，极短文本则直接走摘要模式，不再强行拆解议题。调整完脚本后重新测试，三类样本全部通过。上线后发现，真正影响技能包能否被正确调用的，除了脚本本身，还有大模型是否能根据SKILL.md的描述准确判断何时使用这个技能。描述里如果缺少“逐字稿”或“速记文本”这类关键词，用户直接上传纯文字段落时，模型可能选择直接回答而不是调用技能包。这里需要反复调整描述里的适用场景关键词，让触发率稳定下来。

4. 设计模式与最佳实践，省得后面返工

4.1 拆分原子技能，控制循环与分支

技能包不能一味求大。有些开发者喜欢把十几种能力塞进一个技能包，想着“反正都是处理数据”。实际运行起来，技能包越大，SKILL.md的描述就越难写准确，模型误触发的概率也越高。我现在的习惯是把技能包拆成原子性的小单元，比如“提取参会人”、“拆分议题”、“生成行动项”各自独立，然后再做一个编排型技能包组合它们。

这样拆还有个好处是复用性大幅提升。比如“提取参会人”这个原子技能，不仅能用于会议纪要，还能用于招聘面试记录、客服对话分析等完全不同的场景。拆出来的原子技能越多，后续搭新业务流程就越快。

4.2 脚本幂等性与失败重试策略

技能包里的脚本会被人和模型反复调用，而且输入内容可能有细微差异。脚本设计必须做到幂等：同一输入不管执行多少次，输出都应该一致。我第一次写“会议纪要整理”脚本时，犯了个错误，在函数内用了带随机种子的摘要算法，结果每次运行生成的概述都不一样。后来我把随机种子固定在算法初始化参数里，才保证输出稳定可复现。

失败重试也是必须考虑的。技能包执行到一半如果报错，不能让模型假装成功。更合理的做法是脚本返回结构化错误信息，包括错误码和可读的说明，让模型知道发生了什么、可以怎么处理。比如：

{"status": "error", "error_code": "EMPTY_INPUT", "message": "输入文本为空，请提供会议文字记录"}

这样模型就能依据错误信息向用户做合理解释，而不是凭空编造一份会议纪要。

4.3 依赖与环境的标准化

技能包依赖的环境必须隔离且标准化。我踩过很痛的坑：脚本在本地跑得好好的，一到生产容器就报第三方依赖版本不兼容。后来所有技能包统一走虚拟环境管理，每个技能包目录下放独立的依赖锁定文件，并且明确声明运行的Python版本。任何脚本都不允许调用全局环境里未声明过的包。

如果公司内部有统一的基础镜像，最好把常用依赖预装进去；如果技能包要跨团队复用，那就尽量把第三方依赖降到最低。能只用标准库解决的问题，绝不引入额外包。我自己重写了一遍核心脚本，去掉所有外部依赖，维护成本直线下降。

5. 常见问题速查：开发中高频出现的故障与解法

5.1 技能包触发失灵，往往是描述写得太模糊

根据我一段时间的观察和实测，模型能否正确选择技能包，绝大部分取决于SKILL.md里描述语境的清晰度。如果描述里只写着“整理会议纪要”，那用户说“帮我把这段内容结构化一下”，模型可能就不知道用哪个技能。优化方法是在描述里显式写接触发条件和反例：“适用于输入完整会议记录文本的场景，不适用于摘要后的短文本，不适用于用户口述要点但无完整上下文的情况。”

给几个实测有效的小技巧：描述使用动词开头，比如“从……提取”“将……转换为”；写清输入内容的来源，比如“会议录音转写文本”“销售通话记录”；明确说不处理什么，这个比说什么更有约束力。

5.2 路径错误导致模型拿到错误结果

处理脚本如果涉及读取外部文件，路径不能写绝对路径，也不能假设当前工作目录。技能包运行时会从不同的目录发起调用，相对路径一旦错位，脚本直接崩溃。解决办法是脚本内部全部基于技能包根目录动态计算路径：

from pathlib import Path SKILL_ROOT = Path(__file__).resolve().parent.parent

这样无论从哪里调用，都能准确定位到技能包目录下的样本或资源文件。这是一个很小但能省掉大量排障时间的地方。

5.3 死循环和超时：必须有硬性限制

模型调用技能包时候，有时会因为参数生成不合法或者场景理解偏差，导致脚本陷入长时间循环甚至死循环。尤其是有重试逻辑的场景，模型可能会反复重试同一个失败请求，把系统资源耗尽。

现在我给所有技能包设了默认超时时间和最大重试次数，并且重试必须使用退避策略。超时阈值一般控制在10到30秒，根据任务复杂度动态调整。如果一次调用超过阈值，直接返回超时错误，不要让它拖死整个Agent响应链路。这个经验是从一次生产故障里换来的：当时一个技能包在凌晨被连续调用了上千次，每次都挂了很久才失败，直接把下游队列堵死了。

5.4 输出格式不稳定，下游解析崩溃

脚本如果输出JSON，规范里一定要固定字段顺序、类型，并且所有字段都要给默认值。有些同学只在正常路径里输出完整JSON，一旦某个字段为空就直接省略，结果下游解析器拿到的数据结构不一致。我踩过这类坑之后，现在无论是否为空，所有字段一律输出，空数组就输出空数组，空字符串就输出空字符串。这样下游系统永远拿到结构一致的数据。

6. 技能库的长期维护：版本、评测、内容治理

6.1 技能包全部纳入版本管理，语义化版本号

技能包代码和SKILL.md都必须纳入版本管理，不能散落在某台机器或某个对话历史里。我习惯把整个技能库作为一个单独的仓库维护，每个技能包独立建目录，目录名就是技能名。变更时统一使用语义化版本号，破坏性的变更升大版本，新增能力升小版本，小修小补更新修订号。

版本管理的好处不只是留档，还能支持随时回滚。如果一次技能包升级导致Agent行为异常，直接切回上一版本就能快速止血，不必在线上临时改代码。这个能力在生产事故处理中用到的频率远比我预想的要高。

6.2 用回归集检验每次修改是否破坏了原有功能

技能包维护最难的地方是：改了一个小逻辑，可能把之前正常工作的场景带崩。我建立了一个简单的回归集，每个技能包至少包含五个用例，覆盖正常、异常、极简、极长和带干扰项输入五类情况。每次修改技能之后，跑一遍回归集，对比输出是否符合预期，基本就能判断这次改动能不能合入主分支。

回归集同时也对模型触发效果进行验证：把一组典型用户请求发给Agent，看它是否准确选中正确的技能包。这一步其实是很多人忽略的环节，光验证脚本没问题还不够，模型能不能正确使用这个脚本同样关键。

6.3 技能数量增长后，如何防止技能库变成垃圾场

技能库是会随着业务需求膨胀的。最开始可能只有三五个技能，半年之后到几十个，如果每个技能维护不力，整个技能库就会变成无人敢动的“垃圾场”。我现在采取两个策略来控制复杂度：第一，每个技能包必须有清晰的Owner负责维护，Owner不在，则该技能不进入生产可用列表；第二，定期梳理技能包使用频率，连续一段时间没有被调用的技能包直接移入归档区，不再出现在Agent的技能候选列表里。

另外，技能包之间如果出现功能重叠，我会主动合并。功能重叠会严重干扰模型的技能选择，比如既有“提取待办事项”又有“列出行动项”，模型就很容易犹豫或误调。技能库的维护本质上是一个持续做减法的过程，而不是不断堆功能。我从实际运维中得到的体会是：一个工具库里真正好用的技能往往不多，但每一个都经过反复打磨和验证，这样的技能库才值得依赖。

最后再分享一个从实操中得出的经验：如果你刚开始搭Agent技能体系，不要一口气写几十个技能包，先挑两到三个核心业务流程，把技能包做深做透，跑通从触发到输出、从测试到回归的完整链路，再横向扩展。技能包数量少的时候，问题很容易定位；数量一旦上去，光靠排查根本忙不过来。想要技能库长期稳定，关键不在于数量多，而在于每个技能包的边界清晰、逻辑可靠、测试覆盖到位。等这些基础打牢了，后面加新技能就是顺水推舟的事了。