企业官网建设流程全解析

做Agent开发这件事，有个很反直觉的现象：工具越多，Agent越容易“犯傻”。早期我做模拟项目X时，一口气给Agent接了十几个工具，结果它在日志里反复横跳，明明该调A工具，却偏偏选中了B，最后输出一堆格式错乱的内容。后来接触了Agent Skills这套思路，才意识到问题不在模型，而在于我把工具当成了“一次性螺丝刀”，没有把它封装成“可复用的技能包”。

Agent Skills的核心，是把工具调用从“函数列表”升级为“带说明书的能力单元”。一篇技能不仅包含执行函数，还包含触发条件、输入协议、输出规范和异常兜底。模型看到的不是一个孤立的函数名，而是一份能自我说明的“岗位说明书”。这样做的好处非常直接：模型决策准确率上来了，项目组其他人也能轻松复用同一个技能，不再需要反复读我的源码猜意图。

作为系列教程的第5篇，前四篇我们聊过Prompt工程、上下文窗口管理、Function Calling的底层逻辑、以及主Agent框架的选型对比。这篇我打算把所有线索收拢到一点：怎么把零散的工具调用，封装成一套真正可用的Agent Skills，以及封装完之后如何编排、如何排错、如何继续演进。内容偏工程实践，示例都是我改过多轮的真实代码，配合踩坑记录一起看，可以少走不少弯路。

1. Skill不是新的函数封装，而是一套“能力封装协议”

1.1 技能化前后，同一个任务的处理差异

先看一个具体场景：让Agent读取一批文件，生成一份统一的项目周报。没用Skill之前，我的做法是在系统Prompt里写一大段说明：“当用户需要总结多个文档时，请依次调用read_file、extract_key_points、generate_report三个函数，注意先排序再处理，输出格式为Markdown。”

问题立刻出现了。模型在长上下文里很容易“遗忘”这段规则，尤其是当对话轮次变多，用户中途又插入新需求的时候。某个开发者朋友遇到过更夸张的情况：模型把generate_report的参数从字符串传成了对象，后端直接抛异常，整个任务中断。

技能化之后，同样的规则被写进Skill描述里，和函数体绑在一起：

{ "skill_id": "weekly_report_skill_v1", "name": "多文档周报生成", "description": "当用户要求汇总多份文档并生成周报时，先读取文件内容，提取关键进展，再按时间倒序输出Markdown格式的周报。如果文档之间存在冲突，以最新修改时间为准。", "input_schema": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string" }, "description": "待处理的文件路径列表" }, "include_risks": { "type": "boolean", "default": true, "description": "周报中是否包含风险提示小节" } }, "required": ["paths"] } }

模型在决策时看到的不是一个光秃秃的函数名，而是一段“任务说明书+参数协议”。触发判断变得非常轻：描述里写了“汇总多份文档并生成周报”，模型只要语义匹配到，就直接把参数填进schema，剩下的执行逻辑全部交给后端。这个转变的本质是：把判断职责从“模型记忆”转移到“技能描述”，模型只需要做选择题，不需要背规则。

1.2 为什么说它是“可复用”与“可演进”的

普通的Function Calling是“一次性”的：函数绑定在某个Agent实例里，换了项目、换了对话，就要重新写一遍Prompt。Skill不一样，它把能力的边界、输入输出、异常处理全部固化成一个独立单元，任何Agent都可以通过注册机制加载。

可复用体现在两个层面：

• 跨项目复用。我在模拟项目X里写好的“跨文档摘要”技能，直接复制到另一个商业分析项目里，改一下文件读取路径的解析规则就能跑。
• 跨模型复用。同一个Skill定义，无论是让一个轻量模型跑，还是让一个百亿参数模型跑，只要它们都支持相同的工具调用协议，技能描述就能直接生效。这让我在切换模型时省了至少两天的Prompt适配时间。

可演进则体现在版本迭代上。技能不是一成不变的，每次业务规则调整，我不需要去改主Agent的Prompt，只需要升级技能版本号。旧对话继续用旧版本，新对话自动加载新版本，灰度起来非常顺。

1.3 它和Plugin、Prompt模板的边界在哪里

很多开发者会混淆这四样东西：Prompt模板、Function Calling、Plugin、Skill。我用一句话区分：

• Prompt模板解决“怎么说”的问题，是静态文字。
• Function Calling解决“怎么调”的问题，是函数注册。
• Plugin解决“怎么装”的问题，是外部扩展包。
• Skill解决“什么时候用、参数怎么传、坏了怎么办”的问题，是能力封装协议。

Skill把前三者的优点集于一身：它内部有一段描述（Prompt模板的逻辑）、有一个执行函数（Function Calling的逻辑）、有一套独立的打包和加载方式（Plugin的逻辑）。但Skill多了一层关键设计——自描述与自校验。技能知道自己适合什么场景、需要什么参数、可能出什么错。这一层设计，是普通Plugin和Function Calling都不具备的。

2. 先想清楚这三个底层原则，再动手写Skill定义

2.1 单一职责是第一红线

我第一次写Skill时，犯了一个典型错误：把“统计报表生成”和“告警推送”塞进了同一个技能。理由是它们经常一起触发，省得写两个。实测后才发现这是个馊主意。

原因在于模型决策。当一个技能覆盖两件事，它的描述就很难写聚焦。我写了“生成报表并推送告警”，模型在用户只需要报表时，也可能把推送逻辑带上；在用户只需要告警时，又会纠结要不要先出报表。结果就是参数校验经常失败，返回数据也混乱。

后来我把它们拆成两个技能：report_generator管报表，alert_dispatcher管推送，再用一个编排层让它们按顺序执行。拆分之后，每个技能的描述都可以控制在一句话以内：“当用户需要XX时使用本技能。”模型决策准确率从82%提升到94%。

拆分的判断标准很简单：如果你发现自己写描述时用了“并且”“以及”“同时”，那就说明这个技能混了多个职责，应该拆。

2.2 描述是写给模型看的，不是写给文档读者看的

Skill描述是影响触发率的第一要素。很多从传统API开发转过来的工程师，写描述时习惯用词严谨、缩写规范，比如“调用本方法可生成某格式的聚合摘要结果”。这种描述给人类看没问题，给模型看效果很差。

模型是语义匹配，不是关键词匹配。我对比过两种写法：

• 写法一：“生成聚合摘要结果。支持输入多个文本路径。”
• 写法二：“当用户希望把多份文档汇总成一份摘要时，使用本技能。用户可能会说‘帮我总结这几份文件’或‘把报告合并成要点’。”

写法二的触发率明显更高，因为模型在预训练阶段已经大量接触过“总结”“汇总”“合并”这类表达。写法一里的“聚合摘要”是书面语，模型需要多做一层语义转换，匹配概率就下降。

我现在的习惯是：写完描述后，拿5句用户可能说的口语化指令去测，看技能是否都能正确触发。测不过就改写描述，用更口语、更贴近用户的表达。

2.3 默认参数与最小惊喜原则

一个Skill的输入schema，应该是“模型只需要填少数关键参数，其余全部有默认值”。这样做有两个原因：

• 模型填的参数越少，出错概率越低。
• 用户在对话里往往不会主动提供所有细节，太多必填参数会逼着模型去“猜”，一猜就容易错。

我在做“跨文档摘要”Skill时，把“摘要风格”“目标字数”“是否包含结论”全部设了默认值。用户只说了“总结一下这些文件”，模型只需要传file_paths一个必填参数，其余用默认值。少数用户有更细的要求，比如“详细一点”“不要结论”，模型才会在schema里追加对应参数。

最小惊喜原则还有另一层含义：技能的副作用要克制。不要在技能里偷偷写日志、偷偷改全局配置、偷偷发消息。我曾经在一个技能里埋了一条“处理完成后自动发送邮件”的逻辑，结果演示时当着客户的面发了一封测试邮件，场面一度尴尬。从那以后我定下规矩：技能只做描述里承诺的事，任何额外动作必须显式暴露在参数里，由模型决定要不要触发。

3. 从零手写一个“跨文档摘要”Skill：定义、执行、注册全流程

3.1 场景选型：为什么拿“跨文档摘要”当示例

跨文档摘要是一个特别适合演示Skill价值的场景，因为它有三个典型特征：

• 输入不固定：用户可能传PDF、Word、Markdown、纯文本，每种格式读取方式都不一样。
• 输出有强约束：摘要长度、风格、是否带结论，这些都需要可配置。
• 执行链路长：读取、分块、分段摘要、合并、裁剪，涉及多个步骤。

如果用普通Function Calling，这些步骤会暴露成五六个函数，模型需要自己决定调用顺序和参数传递，极容易出错。封装成Skill之后，模型只需要调用一次，内部链路全被隐藏。技能对外表现为一个独立的、可控的“能力原子”。

3.2 技能定义：从自然语言到结构化协议

先看完整的Skill定义：

{ "skill_id": "cross_doc_summarizer_v2", "name": "跨文档摘要生成", "version": "2.0.0", "description": "当用户要求对多个文档生成统一摘要时使用。用户可能会说“总结这几份文件”“把报告合并成要点”“帮我提炼核心内容”。支持PDF、Word、Markdown、纯文本格式。", "input_schema": { "type": "object", "properties": { "file_paths": { "type": "array", "items": { "type": "string" }, "description": "待摘要的文档路径列表，必填" }, "summary_style": { "type": "string", "enum": ["brief", "detailed"], "default": "brief", "description": "摘要风格，brief为要点式，detailed为段落式" }, "target_length": { "type": "integer", "default": 800, "minimum": 200, "maximum": 2000, "description": "最终摘要的目标字数" }, "include_conclusion": { "type": "boolean", "default": true, "description": "是否在摘要末尾附一段总结性结论" } }, "required": ["file_paths"] }, "hooks": { "on_start": "load_documents", "on_finish": "tidy_output", "on_error": "return_structured_error" } }

这里有几个设计细节值得说明：

• description里包含了触发短语示例，不是给模型背的，而是帮助语义匹配。模型看到“总结这几份文件”，会更容易联想到这个技能。
• summary_style用enum约束，避免模型自由发挥传一个“中等风格”之类的非法值。
• target_length设了上下限，防止模型传一个离谱的数字导致摘要生成时间过长。
• hooks字段声明了生命周期回调。on_start负责加载文档，on_finish负责整理输出格式，on_error负责把异常包装成结构化错误返回给Agent。

3.3 核心执行逻辑：分块、分段摘要与合并

执行逻辑是Skill的真正内核。我的实现思路是：先把文档切成固定大小、有重叠的块，对每个块做一次独立摘要，然后把这些分段摘要递归合并，直到长度满足目标。

from typing import List import re def extract_text(path: str) -> str: if path.endswith(".pdf"): return extract_pdf(path) if path.endswith(".docx"): return extract_docx(path) with open(path, "r", encoding="utf-8") as f: return f.read() def split_into_chunks(text: str, chunk_size: int = 2000, overlap: int = 200) -> List[str]: paragraphs = re.split(r"\n\s*\n", text) chunks, current = [], [] current_len = 0 for para in paragraphs: current.append(para) current_len += len(para) if current_len >= chunk_size: chunk_text = "\n\n".join(current) chunks.append(chunk_text) tail = chunk_text[-overlap:] current = [tail] current_len = len(tail) if current: chunks.append("\n\n".join(current)) return chunks def summarize_chunk(chunk: str, style: str) -> str: prompt = f"请对以下内容生成{ '要点式' if style == 'brief' else '段落式' }摘要，保留关键数据：\n\n{chunk}" return call_llm(prompt, max_tokens=512) def merge_summaries(summaries: List[str], target_length: int) -> List[str]: while len(summaries) > 1 and total_chars(summaries) > target_length * 1.5: merged = [] for i in range(0, len(summaries), 2): if i + 1 < len(summaries): pair_text = f"摘要A：\n{summaries[i]}\n\n摘要B：\n{summaries[i+1]}" merged.append(call_llm("合并上面两个摘要，去掉重复信息，控制在200字内：\n" + pair_text, max_tokens=256)) else: merged.append(summaries[i]) summaries = merged return summaries def run(file_paths: List[str], summary_style: str = "brief", target_length: int = 800, include_conclusion: bool = True) -> str: chunks = [] for path in file_paths: text = extract_text(path) chunks.extend(split_into_chunks(text)) partial = [summarize_chunk(c, summary_style) for c in chunks] merged = merge_summaries(partial, target_length) final_text = merged[0] if merged else "" if include_conclusion: final_text += "\n\n结论：" + call_llm("基于以上摘要写一段总结性结论，30字以内：\n" + final_text, max_tokens=64) return final_text

两个容易出错的细节：

• 分块时的overlap不能省。直接按固定字数硬切会产生“把一句话拦腰截断”的问题，导致摘要丢信息。我的经验是overlap取chunk_size的10%，既能保证上下文连贯，又不会造成太多重复计算。
• merge阶段必须设一个“超过目标长度1.5倍才继续合并”的阈值。如果不设，合并次数过多，信息会被反复压缩，最后可能只剩一两句干巴巴的结论，丢失细节。

3.4 注册与触发优化：让模型在正确时机选中它

定义写好了，执行函数也写好了，接下来是关键一步：注册。不同Agent框架的注册方式略有差异，但核心逻辑一致：把Skill的JSON定义注入到模型可见的工具列表中。

注册时我踩过一个坑：把技能塞在很靠后的位置，结果模型在决策时“忘记”了它。后来发现多数框架在选择工具时，会受列表顺序影响。解决办法有两个：

• 调整技能在工具列表中的排序，把高频技能放在前面。
• 在系统Prompt里加一句提示：“当涉及文书汇总类任务时，优先考虑跨文档摘要技能。”

第二种方法更有效，因为模型决策时不仅看技能描述，也会参考系统提示里的“优先级建议”。我用这招之后，技能触发率提升了好几个百分点。

另外，注册之后一定要做“空跑测试”：用一个不包含任何关键字的指令去试探，比如用户说“今天天气如何”，模型应不会触发该技能。如果误触发了，说明描述写得太宽泛，需要收紧，比如加上“多份文档”“汇总”等更具体的条件词。

4. 多个Skill同时在场时：编排顺序与冲突消解

4.1 串行编排：上一个技能的输出是下一个技能的输入

现实任务不是一个Skill能独自搞定的。比如“把销售周报转成PPT”，至少需要三个技能：报表分析技能、文案提炼技能、PPT生成技能。这时候就要考虑编排。

我最常用的编排模式是串行流水线：A技能的输出，作为B技能的输入。实现方式有两种：

• Agent自主编排：模型在对话过程中先后触发多个技能，Agent只负责透传上下文。
• 框架编排：在Agent配置里写一个pipeline，定义技能执行顺序和参数映射。

两种方式各有优劣。Agent自主编排灵活，模型可以根据用户反馈中途调整路径；框架编排稳定，执行顺序固定，适合对时效和准确性要求高的任务。我的建议是：核心链路用框架编排，临场变化用Agent自主编排，两者混用。

4.2 并行分派：按内容类型拆给不同技能

有些任务天然可以并行。例如用户一次性上传十份文件，其中五份是PDF报表、三份是Word方案、两份是Excel数据。如果按串行处理，效率太低。

碰上这种情况，可以做一个“前置分派器”技能，它的唯一职责是识别文件类型，然后把不同类型的文件分别传给对应的处理技能。分派器本身不做任何实际加工，它只负责路由。

实现上，分派器可以是一个轻量级规则函数，不需要调用大模型：

def dispatch(file_paths): plan = {"pdf": [], "docx": [], "xlsx": []} for p in file_paths: ext = p.rsplit(".", 1)[-1].lower() plan[ext].append(p) return plan

但要注意，分派器返回后，后续并行执行需要Agent框架支持并发调用。如果不支持并发，就退化成串行，只是顺序做了分类，也能减少模型在路径选择上的混乱。

4.3 冲突消解：当多个技能都说“我能处理”时

技能一多，冲突就来了。典型的冲突场景：用户说“帮我整理一下这几份会议记录”，此时会议纪要整理技能和跨文档摘要技能都认为自己适合。模型一旦选错，输出风格就跑偏。

我的解决方案是给每个Skill定义一个“触发优先级”和一个“排他声明”：

{ "priority": 10, "exclusive": true, "conflict_policy": "当文档包含时间、人名、决议等会议元素时，本技能优先于通用摘要技能" }

框架在处理时，会先筛选出所有“候选技能”，按优先级排序，再检查排他声明。排他声明命中后，低优先级技能自动退出。

这套机制的核心不是让开发者写更多代码，而是逼着技能作者在定义阶段就想清楚“我的技能和别的技能边界在哪”。如果两个技能经常冲突，说明职责划分有问题，应当合并或拆分，而不是一味堆冲突策略。

4.4 跨技能上下文透传：压低信息损耗

编排过程中最容易被忽略的是上下文传递。技能A的返回值往往是大段文本，直接传给技能B时，B需要重新理解一遍，既费token又容易跑偏。

我在模拟项目X里设计了一个“摘要透传”环节：A技能除了返回完整结果，还额外返回一份压缩版的“要点列表”，B技能优先阅读要点列表，只有必要时才回溯完整结果。这个做法把上下文传递的信息损耗降到了最低。

具体实现就是在结构化输出里加一个字段：

{ "output": "完整结果文本", "compressed": "要点列表，用于传给下一个技能", "meta": { "source": ["file1.pdf", "file2.docx"], "confidence": 0.93 } }

不要小看这个compressed字段，它让整个编排链路的token开销减少了大概30%，而且下游技能的准确率反而更高，因为没了信息噪声。

5. 我在真实项目里踩过的五个Skill坑，和对应的解决方案

5.1 幻觉调用：模型自作主张执行了未授权的技能

最早一次踩坑发生在联调阶段。用户只是问“这个报表什么时候能出”，模型却直接调用了“邮件推送”技能，把未完成的报表草稿发了出去。事后排查发现，模型把“什么时候能出”理解成了“现在发送报表”。

根因是技能描述里带有“当用户询问报表状态时也可调用”的模糊表达。我的解决方式是：把“发送”动作和“查询”动作彻底分离，查询状态只读，不允许触发发送。并且在描述里加上负面提示：“本技能不发送任何内容，仅生成报表文件。若用户要求发送，请调用其他技能。”

负面提示是阻止幻觉调用的有效手段。模型决策时会对“不能做什么”的约束更敏感，因为它能直接排除一个错误选项。

5.2 参数校验缺失：模型传了非法参数，技能原地崩溃

另一个高频坑是参数校验。Skill接收的file_paths里混入了一个不存在的路径，或者target_length传了一个负数。

我一开始没做校验，结果运行时抛出未捕获异常，整条链路中断，用户看到的只有一行“系统错误”。后来我在所有Skill里加了一个统一入口：

def safe_run(skill_func): def wrapper(*args, **kwargs): try: validate_schema(kwargs) return skill_func(*args, **kwargs) except SchemaValidationError as e: return {"error_code": "INVALID_PARAM", "message": str(e)} except Exception as e: return {"error_code": "INTERNAL_ERROR", "message": str(e)} return wrapper

这个包装函数的作用是双重的：一方面挡住非法参数，另一方面把异常转化为结构化返回。Agent拿到错误码之后，可以自动修正参数并重试一次，而不是直接摆烂。

5.3 技能体积膨胀：一次加载太多技能，响应速度直线下降

有一阵子我恨不得把每个功能都做成Skill，结果Agent加载了40多个技能定义。模型每轮决策都要把所有描述读一遍，响应延迟从1.5秒涨到4秒，触发准确率也掉了。

后来我意识到：技能加载是分层的，不该一股脑全塞给模型。我改用“双层注册法”：

• 常驻技能：不超过8个，高频使用，例如摘要、搜索、文件读取。
• 动态技能：按会话主题或用户意图临时加载，例如报表生成技能只在用户提到“报表”时才挂载。

动态加载的实现可以在会话初始化时做一个意图预分析，把相关技能ID注入工具列表。这套做法让模型每轮需要扫描的描述量减少了近六成，延迟重新回到2秒以内。

5.4 失败重试：Skill内部报错，该由谁来兜底

一次调度演示中，某个Skill因为上游数据源临时不可用而超时。当时我的Agent没有重试机制，直接返回了一个错误码，用户看到“任务失败”后整个人懵了。

我需要想清楚：错误到底该怎么兜底？分三层：

• 第一层：Skill内部做一次重试，间隔指数退避。
• 第二层：Agent根据错误码，换一个等价Skill执行。例如摘要技能失败，就换文本提取技能+关键词聚合技能顶替。
• 第三层：以上都失败，才返回用户“任务失败”，同时附上失败的具体原因和已尝试过的补救措施。

现在我在所有Skill里都内置了第一层重试，Agent框架负责第二层切换，只有到了第三层才会打断用户。这套分级兜底机制，让我的项目故障率下降了七成。

5.5 调试方法论：先判断是“触发错”还是“执行错”

开发Agent Skills时最头疼的问题就是排错。技能行为异常，到底是模型压根没选中它，还是选中之后执行链路出了Bug？

我的排查方法是看三段日志：

• 决策日志：模型输出了什么tool_call，对应哪个skill_id。
• 参数日志：传入的参数是什么，有没有被schema拦截。
• 执行日志：Skill内部每一步的耗时和返回值。

只要把三段日志拉出来对齐，基本能秒定位问题。有一次用户反馈“摘要太短”，我一看参数日志，发现模型把target_length传成了默认值800，但用户原话是“简单点就行”。问题不在执行，而在描述里没有说明“目标字数应尽量贴合用户对篇幅的要求”。修正描述后，模型就会在用户说“简单点”时主动传一个较小的target_length。

先定位到是哪一段出问题，再决定去改描述还是改代码，能省一半以上的调试时间。

6. Skill的下一步演进：版本管理、语义路由与运行时自举

6.1 语义化版本与灰度迁移

Skill是会持续迭代的，我在模拟项目X里就用上了语义化版本号：主版本号变化代表协议不兼容，比如输入schema改了必填字段；次版本号变化代表新增参数或描述调整；补丁号变化代表只修了内部逻辑。

版本管理配套的是一个“迁移区”设计。新版本的Skill不直接替换线上版本，而是先进入灰度名单，只让5%的会话使用。观察几天后如果触发率和成功率都优于旧版，再逐步放量到50%、100%。

有一次新版描述改了措辞，触发率肉眼可见地掉了5个百分点，因为灰度机制及时发现，我立刻回退，避免了一次线上质量事故。

6.2 语义路由：把“线性扫描”升级为“向量检索”

当Skill数量真正多起来，线性扫描模式就扛不住了。40个技能、每个描述200字，模型每轮都要读一遍，token成本和延迟都飙升。

我在进阶阶段做了一个“技能路由器”模块：它的职责不是调用技能，而是先从技能库中检索出最相关的3到5个技能。具体做法是把所有技能描述预计算成向量，用户每次发起新请求时，用请求文本做一次向量相似度查询，只把命中的技能注入工具列表。

这个模块对于几十个技能的场景已经绰绰有余。实测中检索精度比线性扫描更高，因为向量匹配能发现“表面不通、语义相关”的技能，而关键词匹配不行。

6.3 运行时自举：Agent也能自己生成临时小技能

最后一个进阶方向是我最近着迷的：动态生成小型Skill。它的思路是，当Agent遇到一个重复出现但技能库中没有覆盖的任务时，它把这一次成功处理的过程封装成一个临时技能定义，存到临时技能区。下次遇到同类任务，直接调用临时技能，不用再走一遍完整推理。

听起来很酷，但实际坑也不少。动态生成的技能描述质量参差不齐，如果模型在任务中犯了错，这个错也会被“固化”进技能里。我的解决方法是加一道人工评审闸门：动态技能只在本会话内生效，不会自动进全局技能库。只有经过测试校验、确认输出质量稳定后，才手动将其升级为正式技能。

即便如此，这个方向的潜力还是很大的。它意味着技能系统不再是静态的代码资产，而是一个能随使用场景不断自我生长的能力库。大模型应用的边界，也随之从“预定义功能”扩展到“运行时自适应”。

回看这一整套流程，从定义规范到封装执行，从多技能编排到踩坑修复，再到版本演进与动态自举，我最大的体会是：Agent Skills真正的价值不在于“省掉几个if-else”，而在于它提供了一种让模型和工程都能理解的标准化协议。模型因此降低了决策负担，工程师因此降低了维护成本。写任何一个Skill之前，先问自己三个问题：能不能用一句话说清这个技能负责什么？输入输出是否稳定、是否可测？换一个更强的模型过来，能不能直接复用？三问都过关了，再动手写定义。这套习惯陪我走过了好几个项目周期，现在分享出来，希望能让你的Agent开发之路走得更顺。