企业官网建设流程全解析

先说结论：Agent Skills 不是给模型"加技能"，而是把你脑子里的任务拆解经验，沉淀成一套可以被模型稳定调用的结构化能力。我接触智能体开发也有不短的时间了，早期团队里每个人都在做自己的"万能 Prompt"，结果模型表现完全看运气。后来我们把注意力从 Prompt 文本转移到技能封装上，效果才算真正稳下来。这篇先聊清楚技能树的概念、定位和设计骨架，下篇再补调度与动态组合的细节。

1. 先搞清楚 Agent Skills 到底是什么

1.1 从"会说话"到"会动手"：智能体技能的定位

大语言模型本质上是一个"会说话"的系统，你跟它聊得再深入，它也不会自己去调用 API、操作文件、发请求。所谓的智能体，就是在模型外面套了一层"能动手"的机制，让它可以访问外部世界。但问题是，让它动手做什么、按什么顺序做、做到什么程度算完成，这些不能每次都靠模型临场发挥，否则返回结果的质量是完全不可控的。

Agent Skills 解决的就是这个"不可控"问题。一个技能本质上是对某一类任务的完整封装，里面包含任务描述、输入参数定义、执行逻辑、输出格式约定，甚至包括模型要遵循的规则边界。举个例子，你想让智能体做一个"网页内容摘要"的功能，如果不做技能封装，你会写一大段 Prompt 告诉它怎么抓取、怎么提取、怎么润色，而且每次触发条件稍有变化，输出就飘了。如果封装成一个 skill，只要传入 URL 和摘要长度，其他细节全部由技能内部的规则约束，模型的自由度被压缩在一个合理范围里，稳定性和可复用性立刻就不一样了。

我在实际项目中观察到一个很明显的现象：凡是表现优秀的智能体应用，背后几乎都有一个设计良好的技能库。那些表现忽好忽坏的 Demo，问题通常不是模型能力不够，而是把太多不该由模型掌控的细节交给了模型的自由发挥。

1.2 技能树与 Prompt 模板的本质区别

很多刚接触智能体的朋友会问：技能封装跟写好一点的 Prompt 模板有什么区别？这个问题问得很好，因为它们表面上有点像，但本质上完全不同。

Prompt 模板是"被动等待被填充"的文本，它的核心是提示。你给模型一段带占位符的指令，模型按指令完成任务。问题是，模板里的变量越多，组合越复杂，模型出错概率越大，而且模板跟模板之间没有任何结构化关系，无法复用、无法校验、无法版本管理。

技能则更像一个"可执行模块"。一个完整的技能通常包含三部分：

• 触发条件：什么情况下这个技能应该被启用，模型在什么上下文里可以调用它
• 参数 Schema：需要哪些输入，每个参数的格式、范围、必填与否，这些通常用 JSON Schema 来定义
• 执行逻辑：从接收参数到产出结果的完整流程约束，包括中间该调用哪些外部工具、用什么格式输出、遇到异常怎么处理

更关键的区别在于协作逻辑。Prompt 是"用户直接驱动模型"，技能是"模型在运行时自主决策是否调用、如何调用"，它把主动权交给模型，但把决策空间限制在预设的轨道内。这就像你给员工一份 SOP，而不是一段口头叮嘱。

另外，技能是可以叠加和组合的。Prompt 模板之间难以互相调用，但技能之间可以构建依赖关系。比如一个"周报生成"技能，内部可以调用"数据分析"技能和"文档排版"技能，这跟你的专业技能树一层层往上长是一个思路。

2. 技能树的设计思路：先搭骨架再填肉

2.1 技能的粒度怎么定

这是我在做技能体系时碰到的第一个头疼问题。技能拆得过细，会出现大量碎片化模块，模型在几百个技能里挑一个，选择成本极高，还容易选错；拆得过粗，一个技能里塞了十几条执行规则，参数又大又复杂，模型执行起来照样飘。

我的经验是：按"任务闭环"来定粒度，而不是按"动作"来定。什么叫任务闭环？就是一个技能从收到请求到产出可用结果，中间的逻辑是完整自洽的，用户不需要再额外调用其他技能来补齐缺口。比如"获取天气"和"根据天气推荐穿搭"是两个不同层级的东西，前者是一个原子动作，后者是一个闭环任务。做技能树时，应该以闭环任务为主要单位，原子动作作为内部步骤存在，而不是单独对外暴露太多技能。

举个我在某项目里的实测数据对比。最初把"搜索资料""提取信息""整理要点""生成报告"拆成四个独立技能，结果模型经常在调用完第一个后不知道该不该调第二个，或者把中间结果当成最终结果返回。后来重新设计成两个技能："资料调研"和"报告撰写"，前者内部串起搜索和提取，后者接收结构化材料直接出报告，错误率显著下降。

颗粒度判断标准我一般用三个问题来卡：

• 这个技能单独调用时，产出的结果对用户是否有直接价值？如果回答"没有"，说明粒度太细
• 这个技能是否能在 5 分钟内向一个不了解背景的人解释清楚它负责什么？如果解释不清，说明边界太模糊
• 这个技能的参数是否能控制在 6 个以内？如果超过，说明你可能把一个流程硬塞进了一个技能里

2.2 技能注册与调度：智能体是怎么"看见"技能的

技能不是写一堆脚本就行，它需要被智能体的核心系统"看见"并理解。这里有一个基本架构，我画个简单的分层：

• 技能注册中心：所有技能的统一入口，记录每个技能的名称、描述、参数 Schema、版本、启停状态
• 技能选择器：模型在对话中判断"该用哪个技能"的环节，通常是把技能列表转成模型可理解的描述集合，让模型选出最匹配的一个
• 技能执行器：根据选中的技能 ID，加载对应的逻辑代码，完成参数提取、校验、执行、结果格式化

这个分层的好处在于：模型看到的不是代码，而是技能的"描述视图"。你在做技能注册时，需要在技能的 Description 里写清楚"什么时候用这个技能"，这段描述的质量直接影响模型的选型准确性。

我踩过最典型的坑是技能描述写得太泛。比如某个技能叫"数据分析"，描述写的是"对数据进行分析并输出结果"，结果模型在用户问"今天天气怎么样"时都误调用过它。后来我把描述改成"当用户提供结构化表格数据并要求计算统计指标、生成图表描述或输出分析结论时使用，不适合处理非结构化文本"，误调用率立刻降下来了。

选型阶段还有一个小技巧：把高频技能和低频技能分开注册，高频技能放主列表里，低频技能收进"高级能力"里，避免主选择器的候选集过大。我们在实验里发现，当系统内技能数量超过 30 个时，模型选型准确率会明显下降，而分组后准确率能回升到正常水平。

3. 手把手搭一套最小可用的技能系统

3.1 定义技能接口：先让模型"读得懂"技能

搞懂概念之后，实际动手才是重点。我以一个真实做过的"智能周报生成器"为例，带着走一遍技能定义到调用的完整流程。这个项目本身不难，但足够体现技能树的核心要领。

首先，每个技能都应该有一个机器可读的描述文件，我习惯用 YAML 或者 JSON 来写，核心字段固定。下面是一个技能描述文件的实例：

name: weekly_report_generator description: > 当用户需要生成周期性工作周报时使用。该技能能够自动汇总本周任务完成情况、 分析项目进度偏差、生成结构化周报文本。适合输入包含任务列表、里程碑节点 或项目状态的场景。不适合处理纯个人日记类内容。 version: 1.2.0 author: agent_team tags: - report - weekly - productivity parameters: type: object properties: tasks: type: array description: 本周任务列表，每项包含任务名、状态和备注 items: type: object properties: name: type: string status: type: string enum: [done, in_progress, blocked] note: type: string project_milestones: type: array description: 项目里程碑节点及当前进度百分比 items: type: object properties: milestone: type: string progress: type: integer minimum: 0 maximum: 100 required: - tasks

注意 description 里的写法，它不仅是给人看的，更是给模型看的，要写清楚"何时触发、何时不触发"，这比任何参数定义都重要。

3.2 参数 Schema：给模型的行动装上限位器

参数 Schema 的作用是约束模型从对话里提取结构化输入，它直接决定了技能的稳定性。你还是用上面的 JSON Schema，但执行端的校验要做得比 Schema 定义更严格，这一点很多人会忽略。

我在实际开发中总结了一个"底线校验原则"：模型提取的参数，过不了校验就直接报错或要求重提，不要试图"宽容处理"。刚开始我自己心软，任务名缺失了就自动填"未命名任务"，结果后面所有报告里全是"未命名任务"，整个输出根本没法用。

校验代码用 Python 写的话，可以参考这个思路：

from jsonschema import validate, ValidationError def validate_skill_input(schema, payload): try: validate(instance=payload, schema=schema) except ValidationError as e: # 这里不只是报错，最好把缺失字段和错误原因返回给模型 # 让模型有机会修正自己的提取结果 return { "valid": False, "error": e.message, "missing": list(e.path) } return {"valid": True}

这里有个容易被忽略的设计点：校验失败时把 error 信息回传给模型，比直接向用户抛异常要好得多。模型可以根据错误信息重新提取参数，总共给 2 次重试机会即可，2 次都失败才向用户确认。这个机制跑熟之后，参数提取成功率能稳定在九成以上。

3.3 技能编排与调用：把执行逻辑变成一条"轨道"

有了技能描述和参数校验，下一步就是写技能本身的执行逻辑。还是以周报生成器为例，它的内部执行流程分四步：

1. 校验输入参数，确认任务列表和里程碑数据完整
2. 调用内部统计函数，计算本周完成率、阻塞项数量、进度偏差
3. 将统计结果和原始数据拼装成上下文，调用大模型生成周报文本
4. 对生成的周报做格式检查和截断保护，确保输出是干净的 Markdown 块

第三步是整个技能的核心，也是最容易失控的地方。我的建议是：在拼装上下文时，先把统计结果算成硬数据，不要把所有原始记录一股脑塞给模型。所谓"先算后写"，就是让模型做写作，而不是做分析。分析交给代码完成，模型只负责把分析结果串成通顺的叙述，这样输出质量会被拉高很多。

# 核心执行代码示例 def execute_weekly_report(params): tasks = params["tasks"] milestones = params.get("project_milestones", []) done_count = sum(1 for t in tasks if t["status"] == "done") blocked_count = sum(1 for t in tasks if t["status"] == "blocked") # 先算好硬数据，模型只负责表达 stats_context = { "完成率": f"{done_count / len(tasks) * 100:.1f}%", "阻塞项": blocked_count, "里程碑数": len(milestones), } # 再把统计结果和写作指令一起发给模型 response = llm_client.chat( system_prompt="你是项目助理，根据统计信息撰写简洁的周报。",, user_content=f"统计数据：{stats_context}；原始任务列表：{tasks}" ) return format_to_markdown(response)

一个常见的毛病是技能执行逻辑里掺杂太多"人味"的分支。比如判断任务名里是不是含有"紧急"两个字然后额外处理——这种规则会让技能越来越重，越来越难维护。更好的做法是把这类判断全部交给统计数据和模型，代码只做通用性处理。

3.4 技能调用链：当技能之间需要相互配合

单个技能跑通只是第一步，真实场景里智能体往往需要连续调用多个技能。还是说周报生成器，如果用户说"帮我汇总这个项目近三周的数据并生成一份完整周报"，它需要先调用"项目数据查询"技能拿数据，再调用"周报生成"技能出报告。

技能调用链的设计核心是中间状态的传递。上一个技能的输出要是刚好符合下一个技能的输入，这当然是最理想的情况，但现实中往往需要对中间结果做一次"翻译"。

我的做法是在技能描述文件里额外加一个字段 output_contract，字段里写明这个技能输出的结构，并在下一个技能的输入说明中引用输出契约。这相当于给技能之间也加了一个 Schema 约束，避免连接处变成逻辑黑洞。

这里有一个实测出来的设计技巧：与其把中间结果直接抛给下一个技能，不如把中间结果交给系统做一次轻量转换，再把转换后的数据喂给下游技能。这个转换逻辑可以非常简单，比如把 JSON 里某些字段重命名、过滤掉空值，但效果立竿见影，技能链的整体成功率会明显提升。

4. 常见问题与排查技巧实录

4.1 技能冲突：总是"调用错技能"

这是技能系统最容易翻车的点，尤其是技能数量一多，模型会经常出现"张冠李戴"。我在早期项目中就有过这样的实录：用户问"帮我写一封请假邮件"，智能体居然调用了"会议纪要生成"技能，输出内容牛头不对马嘴。

排查后发现，问题出在两个技能的 description 都包含"邮件""发送""自动生成"这类关键词，模型面对高相似度描述时无法有效区分。后来我定了一个规矩：每个技能的 description 前两句必须写清楚"本技能只处理 X，不处理 Y"，用排除法帮模型缩小选择空间。

另外我强烈建议在开发阶段给技能的 description 加上"仅测试用"的临时前缀，这样模型调错的时候你能立刻从日志里看出选型逻辑问题，等稳定之后再移除前缀。这个方法简单但极其好用。

4.2 上下文膨胀：技能描述把模型"淹没"了

技能系统做久了会遇到一个隐形问题：每个技能为了描述清楚，写得越来越长，结果每次对话都要把全部技能描述塞进上下文，随便几十个技能就是上万 token。这还没算参数定义和规则文本，几句对话下来上下文就快被技能说明占满了。

解决这个问题的思路是分层加载。不要把所有技能一股脑全塞给模型，而是先塞"一级技能"的描述，也就是那些大概率会被用到的通用技能；当对话内容中出现某个垂直领域的信号词时，再动态加载该领域下的二级技能描述。

我自己的实测数据是：将技能分为三层（全局层、领域层、专用层）后，平均单轮对话的上下文体积压缩了约一半，技能选型准确率反而有所提升。因为模型不再需要在几百个描述里"大海捞针"。

4.3 技能调试：日志记录远比"看结果"重要

技能系统的调试跟普通代码调试不太一样，因为同一个输入可能因为模型采样的随机性产生不同结果，你很难靠肉眼判断"到底是模型错了还是我定义错了"。我的习惯是给每个技能调用都打结构化日志，日志格式固定包含以下六个字段：

• skill_id：哪个技能被调用
• input_payload：模型提取出的原始参数
• validation_result：参数校验通过还是失败
• model_response：模型生成的原始回复
• final_output：经过后处理后的最终产出
• latency：耗时

这种日志在排查问题时有奇效。比如你发现某次调用输出的周报特别混乱，先把日志拉出来看 input_payload，如果原始参数就少了关键数据，那问题就出在上游参数提取环节，而不是写作环节。我多次靠这样的日志把问题精确锁定到某一层，避免了无意义的调参。

一定不要把日志细节全打出来，我建议封装一个 logger，把 skill_id 作为索引字段，后续可以按技能维度做错误率统计，哪个技能问题多一目了然。

4.4 技能演进与版本管理：技能也会"过时"

技能不是写完就完事，模型在变、业务在变、用户的提问方式也在变，技能需要持续迭代。我见过很多团队在技能迭代上吃了亏：直接在原文件上改，改完测试发现效果退步，却想退回旧版本，结果旧版本已经被覆盖了。

技能系统一定要引入版本概念，至少保证：

• 每次修改技能定义都要更新 version 字段
• 保留旧版本的完整文件，切换入口用配置控制而非直接覆盖
• 一次只改一个变量，比如这轮只改 description，下轮只改参数定义，避免多个变化叠加导致无法定位效果变化的原因

这套流程看起来有点重，但技能系统的维护本质上是一种持续调优，版本混乱带来的隐性成本会远高于你省下的那点管理精力。我自己经历过一次"技能描述回滚三天"的事故之后，就再也不敢偷懒了。

最后说几句实在话

Agent Skills 这套东西，看着是技术架构，实际上拼的是你对任务的理解深度。技术实现不过几十行代码，但把任务拆到什么粒度、技能边界画在哪里、哪些规则该写死、哪些该交给模型发挥，这些决策才真正决定智能体的上限。

我在实际项目中最大的体会是：不要追求一步到位的大而全技能库。先把 3 到 5 个核心场景打磨透，再慢慢往上面加技能，因为技能之间不是孤立的，加得不合适反而会干扰已有技能的选择逻辑。上篇先聊到这里，下篇我会继续说说技能树的动态组合、多智能体场景下的技能隔离，以及如何用反馈数据反向优化技能定义。如果你正在做智能体应用，不妨先把自己项目里最常用的三个任务封装成技能，跑一周看看稳定性和调试体验的变化。