企业官网建设流程全解析

1. 为什么要单独聊聊 Agent Skills

这几年做 Agent 相关项目的开发者应该都有一个感受：模型能力在快速拉齐，真正拉开差距的反而是工程细节。你用的是同一个大模型，别人的 Agent 能稳定完成多步骤任务，你的 Agent 跑两步就开始“失忆”或者胡言乱语，问题往往就出在技能层。

Agent Skills，直白说就是让 Agent 具备某种可控、可复用、可观测的能力模块。它不是一条 Prompt 提示词，也不是一个简单的工具函数，而是一整套“模型+工具+流程+校验”的组合。我一开始做某个跨平台系统的时候，以为给 Agent 配上几个 API 就算有技能了，结果跑起来才发现，技能封装得好不好，直接决定了系统的稳定性、可控性和后续扩展成本。

这篇文章我不打算讲那些空泛的概念，就围绕 Agent 技能模块从设计到落地的完整链路，把我在实际项目里踩过的坑、验证过的方法、以及现在沉淀下来的一套实践方案展开聊聊。内容适合三类人：正在做 Agent 应用开发的工程师、准备给团队搭 Agent 基础设施的技术负责人、以及刚入门不久想少走弯路的开发者。

先说清楚一个核心观点：Agent Skills 的关键不是“让模型学会干什么”，而是“让系统稳定地完成什么”。这两个出发点会导致完全不同的设计路线。

2. Agent 技能模块的整体设计与能力边界划分

2.1 技能与工具、工作流、插件到底有什么区别

很多项目里，技能（Skill）、工具（Tool）、工作流（Workflow）、插件（Plugin）这几个词会被混着用，但这几样东西在系统设计里的位置完全不同。

我的理解是这样：工具是原子操作，比如“调用天气 API”、“执行一段 SQL”，它不需要模型做太多决策，入参定义清楚就能跑；工作流是固定流程，比如“先拉数据、再清洗、然后建模、最后出报告”，步骤是编排死的；插件通常指第三方能力接入的标准协议包；而技能更像是一个“具备决策能力的模块”，它内部可以调度多个工具，可以走多条路径，模型在这个模块范围内有一定的自主判断空间。

举一个具体的例子。我之前做一个智能客服系统，需要 Agent 处理退款请求。如果只是暴露一个“退款接口”给模型，模型可能会在用户还没确认订单信息的时候就调接口，或者在参数不全的时候乱填。但如果把这个能力封装成一个“退款处理技能”，内部定义前置校验步骤、参数提取规则、风险判断逻辑、二次确认机制，模型只能在技能限定的范围内做选择，稳定性就会高很多。

所以技能的边界是什么？我认为有三个判断标准：

• 是否有明确的输入输出契约，但内部路径允许模型自主选择；
• 是否包含状态管理和异常处理逻辑，而不是单纯的请求-响应；
• 是否可以被其他技能编排调用，形成更高层的能力。

满足这三条，它才配叫一个技能模块，否则充其量就是一个工具封装。

2.2 技能拆解的两种路线：按任务拆还是按能力拆

设计技能库的时候，团队里最容易吵起来的就是拆解粒度。我见过两种主流路线，各有适用场景。

按任务拆，就是我们常说的“垂直技能”。比如“生成周报”、“分析用户流失”、“撰写招聘 JD”，每个技能对应一个具体任务场景。这种路线的好处是贴近业务，业务方一听就懂，上线快，验证快。缺点是技能数量会爆炸，每来一个新需求就得加一个新技能，维护成本高，而且技能之间很多逻辑是重复的。

按能力拆，则是“水平技能”。比如“信息抽取”、“文本总结”、“数据格式化”、“代码执行”，这些技能不绑定具体业务，而是提供通用能力，上层业务通过编排组合来实现具体任务。这种路线前期投入大，抽象难度高，但一旦建好，新业务场景只是重新组合一遍已有技能，边际成本很低。

我的建议是，新项目起步阶段不要二选一，而是用“核心场景垂直切入 + 通用能力水平沉淀”的方式。先挑两三个最高频的核心业务场景做垂直技能，把流程跑通；同时留意这些垂直技能里哪些步骤是重复的，逐步抽成水平技能。等水平技能沉淀到一定数量，再反过来重构垂直技能，让它们变成水平技能的组合编排。

我自己在实际项目里就是这么处理的。一开始做了四个垂直技能，跑了三个月后抽出了三个水平技能，后来新接的业务需求里有七成不需要新增技能，直接编排现有模块就能完成。这里有一个数学账：如果按任务拆，N 个业务场景就需要 N 个技能；如果按能力拆，M 个通用能力可以覆盖大部分场景，而 M 通常远小于 N。

2.3 技能注册表与命名规范：容易被忽视的架构问题

技能模块一旦超过十个，你就需要一套注册管理机制，不然项目后期会非常痛苦。我在项目里踩过这个坑，当时技能数量到了十五六个，每个技能散落在不同目录，没有统一的元数据登记，结果出现了两个技能做类似事情但命名完全不一样的情况，排查问题的时候要找半天。

后来我参照微服务的服务注册思路，给技能模块加了一个统一注册表，每个技能必须声明如下元数据：

• 技能标识符：全局唯一，语义化命名，比如refund_processor、info_extractor；
• 技能名称和描述：给模型看的说明，描述里必须写清楚“什么时候用这个技能”和“什么时候不该用”；
• 输入输出 Schema：严格定义参数结构和返回格式；
• 依赖列表：依赖哪些其他技能或工具；
• 版本号：技能迭代必须带版本，并且保证向后兼容；
• 超时设置和并发限制：防止某个技能拖垮整个系统。

命名规范这块我个人建议采用“领域前缀 + 动作 + 对象”的方式。比如finance_calculate_tax、hr_generate_onboarding_doc，一眼就能看出归属领域和职责。千万不要用do_stuff、process_data这类没有信息量的名字，模型在理解技能描述的时候会非常吃亏，因为大模型对语义化命名的理解准确度明显更高。

注册表本身可以用 JSON 或 YAML 文件维护，也可以直接放在配置中心或者数据库里，关键是它必须成为技能调用的唯一入口。模型在决策时看到的不是代码里的函数，而是注册表里经过清洗的技能描述。

3. 核心细节拆解：从技能定义到上下文管理

3.1 技能描述文档的写法，直接影响模型命中率

技能描述是给大模型看的“用户手册”，它的质量直接影响模型在规划阶段能不能正确选择这个技能。说实话这一块是很多团队最容易忽略的。花大量时间写代码，结果描述就写两行字，模型根本不知道这个技能什么时候该用、什么时候不该用。

我总结了一套技能描述的写作模板，包括五个部分：

• 一句话概述：这个技能做什么，控制在 30 字以内。
• 适用条件：明确“当满足以下条件时使用本技能”，列出具体规则。
• 不适用的场景：明确“以下情况不要使用本技能”，这是防止模型误用最关键的部分。
• 输入说明：列出必要参数和可选参数，标注类型、格式要求、取值范围。
• 典型示例：给一个真实的输入输出对，帮助模型理解调用效果。

举例来说，如果是一个信息抽取技能，我的描述大概长这样：

name: info_extractor description: | 从非结构化的文本中抽取指定类型的实体信息。 适用条件： - 用户提供了包含个人姓名、日期、地点、机构等实体信息的自由文本； - 需要将自由文本中的关键信息结构化输出。 不适用场景： - 输入已经是结构化数据（如 JSON、表格），此时不需要抽取； - 需要理解文本情感倾向，请使用 sentiment_analyzer 技能。 输入： - text: 字符串，必填，待抽取的原始文本 - target_types: 字符串数组，可选，指定抽取哪些实体类型，默认抽取全部 输出： - entities: 数组，每个实体包含 type、value、confidence 三个字段

这样的描述写出来，模型误调用的概率会明显下降。我之前做过一个对比测试，描述文档从三行扩展到完整五段之后，技能选择准确率从 82% 提升到了 94%。这个提升幅度非常可观，而且完全不需要改动模型和代码，只是文案层面的优化。

3.2 技能内部的状态管理与记忆注入

技能模块一旦涉及多步操作，就必然要面对状态管理问题。比如一个订单处理技能，内部可能是“核实订单”、“检查库存”、“锁定库存”、“发起支付”、“更新状态”五步，步骤之间需要传递订单号、用户信息、库存余量等数据。

我的方案是给每个技能实例化一个独立的上下文对象，这个对象在技能生命周期内持有局部状态，任务完成或者异常终止后销毁。上下文对象里至少包含三类信息：

• 任务级变量：本轮任务产生的中间结果；
• 会话级信息：从上层 Agent 传入的用户意图、历史操作记录；
• 技能自身的配置项：超时时间、重试策略、调用工具的认证信息。

实现的时候我比较推荐用类或者数据类来承载，而不是到处用全局变量。全局变量在多技能并发执行的时候会互相污染，排查问题特别痛苦。我自己早期掉过这个坑：两个技能同时跑，A 技能改了一个全局缓存变量，B 技能读到错误数据，最后生成了错误的结果，调试花了一整天才定位到原因。

记忆注入这块，要注意控制注入到大模型上下文里的信息量。技能内部步骤不需要把完整历史对话都塞进去，只需要把当前步骤需要的状态变量格式化后注入。这里有一个经验值：每步骤注入的上下文尽量控制在 1500 字以内，超过这个量模型的处理精度会下降，成本也会上升。如果确实需要更多历史信息，优先考虑摘要压缩，而不是直接拼接原文。

3.3 技能编排与级联调用时的参数透传问题

技能和技能之间不是孤立的。一个上层任务往往需要多个技能协作，比如“生成月度经营分析报告”这个技能，内部会调用“数据查询技能”、“指标计算技能”、“图表生成技能”和“文本总结技能”。这就涉及编排逻辑。

我在项目里采用的编排方式是 DAG 结构。每个技能节点声明依赖关系，编排引擎按拓扑序执行，同时处理分支和并行场景。这里最容易出的问题就是参数透传：上层技能的输出字段名和下层技能的输入参数名对不上，或者类型不一致，导致链路断裂。

解决方案不复杂，但必须严格执行：所有技能的输入输出必须通过注册表里声明的 Schema 做运行时校验，编排引擎在下发任务之前先做一次字段映射校验。比如上层技能输出的是user_id，下层技能期望的是uid，编排引擎需要有一个显式的映射规则user_id -> uid，不能指望模型自己猜。模型的字段对齐能力在复杂任务里并不可靠，我实测大概只有七成概率能猜对，剩下三成会直接报错或者静默填充错误值。

另外，级联调用时每个子技能的异常处理策略要单独定义。有的技能失败后可以降级（比如用简化的规则替代模型判断），有的技能失败后必须终止整个任务。这个策略不能统一，统一了会出现大问题——要么该降级的时候整个任务失败了，要么该终止的时候降级产生了错误结果还继续往下跑。

4. 实操过程：从零到一搭建一个可用的技能模块

4.1 需求定义与技能契约设计

这一节我拿一个实际做过的技能来走一遍全流程，让大家有一个完整的体感。这个技能叫customer_satisfaction_analyzer，场景是：分析客户对话记录，输出满意度评分和为提升满意度给出的建议。这个技能当时是嵌在一个客服质检系统里的。

第一步是定义技能契约。我通常会和产品方一起过一遍需求，把输入输出边界定死。这个技能最终定义如下：

• 输入：一段客户与客服的完整对话文本（纯文本格式），以及一条可选的业务维度说明（比如“本次对话涉及退款”）；
• 输出：
  • satisfaction_score：数值类型，0 到 10 的满意度评分；
  • key_factors：数组，列出影响满意度的关键因素；
  • improvement_suggestions：数组，给出具体的改进建议；
  • confidence：0 到 1 之间的置信度。

契约定义好之后，我会先拿 5 到 8 条典型的历史对话数据来手动标注预期输出，作为后续测试集。这一步看起来简单，但非常关键，没有明确的预期输出，后面评估技能好坏就无从谈起。

4.2 技能内部流程与 Prompt 编排

契约定了之后，开始设计技能内部流程。customer_satisfaction_analyzer我给它设置了三个内部阶段：

• 阶段一：对话清洗与角色分离。原始对话可能带有时间戳、系统消息等噪音，需要先转换成结构化的消息序列（caller 和 agent 交替发言）。
• 阶段二：分段情绪标注。把对话按主题分段，对每个分段做情绪倾向判断，这一步我用了模型调用，每次调用输入一段文本，输出该段的正负向情绪和强度值。
• 阶段三：综合评分与建议生成。将分段情绪结果汇总，让模型基于汇总信息输出满意度得分、关键因素和改进建议。

这里有一个重要的设计选择：为什么阶段二不直接让模型一次性读完整段对话然后输出结果？

我试过直接让模型一次读完，效果不稳定。对话一长，模型会忽略前面的细节，最后的情绪判断容易被末尾几轮对话带偏。分段处理相当于给模型一个“局部注意力”机制，每一段只关注当前内容，汇总阶段再综合全局，准确率明显提升。我拿 100 条历史数据做了对比，分段处理方式的评分准确率比一次性处理高出 12 个百分点。

Prompt 的书写也有些讲究。阶段二的 Prompt 我用了以下模板：

你是客户满意度分析专家。请分析以下客服对话片段，判断客户在片段中的情绪倾向。 输出格式严格为 JSON：{"sentiment": "positive|neutral|negative", "intensity": 0-1, "reason": "简要原因"} 注意： - 仅基于当前片段内容判断，不要推测未出现的信息； - 如果片段中客户没有明显情绪表达，返回 neutral； - intensity 为 0 到 1 之间的小数，表示情绪强烈程度。 对话片段： {segment_text}

注意最后的“仅基于当前片段内容判断”这一条，就是典型的不适用场景声明，这能有效防止模型自作主张结合会话历史补全内容。

4.3 工具调用与外部数据交互的工程化处理

这个技能本身没有外部 API 依赖，但我在另一个技能inventory_checker里做了一次标准的外部数据交互，正好可以聊聊工程层面的细节。inventory_checker需要根据产品 SKU 查询库存系统，拿到实时的库存数和预计补货时间。

工程化处理上有几个点容易踩坑。第一是超时控制，外部接口的响应时间不可控，技能调用外部工具时必须设置严格的超时时间。我当时对库存查询接口设置了 5 秒超时，超时后走缓存数据降级路径。第二是重试机制，不能无限重试，我当时的策略是最多重试两次，间隔分别为 500 毫秒和 2 秒，两次都失败就直接失败返回，让上层 Agent 决定如何处理。第三是数据校验，外部接口返回的数据不能直接拿来用，必须按照注册表里声明的 Schema 做类型检查和取值范围检查，不合法就丢弃本次调用结果，而不是把脏数据传给模型。

还有一个细节是认证信息的隔离。技能调用外部接口时用到的密钥、Token 不能存在代码里，也不要写入日志。我建议把所有外部服务的认证信息放到独立的环境变量或密钥管理服务里，技能模块通过统一配置读取。我在项目里踩过密钥泄露的坑，当时一个研发同学把内部邮件服务的 Token 打印到了日志里，好在只在测试环境，没有造成线上事故，但这个教训让我们后来强制所有技能模块接入统一的密钥托管。

4.4 技能模块的代码组织与接口设计

下面给一个参考的代码结构，我常用的组织方式是按技能分目录，每个技能是一个包，包含__init__.py（技能入口）、schema.py（输入输出定义）、prompts.py（Prompt 模板）、logic.py（核心逻辑）。

# 伪代码展示技能入口的基本结构 class CustomerSatisfactionAnalyzer: def __init__(self, context): self.context = context self.schema_input = InputSchema( agent_id="string", dialog="string" ) self.schema_output = OutputSchema( satisfaction_score="float", key_factors="list", improvement_suggestions="list", confidence="float" ) async def run(self, **kwargs): # 1. 输入校验 validated = validate_input(kwargs, self.schema_input) # 2. 内部流程 messages = await self._clean_dialog(validated["dialog"]) segments = split_by_topic(messages) segment_sentiments = [] for seg in segments: senti = await self._analyze_segment(seg) segment_sentiments.append(senti) # 3. 汇总结果 result = await self._summarize(segment_sentiments) # 4. 输出校验 return validate_output(result, self.schema_output)

注意这个结构里我把输入输出校验放在了最外层和最后层。这么做的好处是：技能内部再怎么复杂，外部拿到的始终是符合契约的数据结构。任何内部异常都会被封装成定义好的错误码，上层编排引擎不需要感知技能内部实现细节。

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

5.1 模型选错技能或者不调用技能

这是我在项目里遇到频率最高的问题。现象是：Agent 明明具备某个技能，而且用户的意图也很明确，但模型就是不去调用，或者调用了另一个不相关的技能。

排查路径我一般是这么走的。第一步，检查技能描述里是否写清楚了“适用条件”和“不适用场景”。绝大多数情况下，模型不调用技能是因为描述太模糊，它不确定当前任务是不是该用这个技能。第二步，检查技能名称是否有歧义，比如一个叫search_engine的技能，模型可能会以为它是用于检索网页的，但实际上它检索的是内部知识库，这种情况下建议改成internal_doc_search。第三步，检查技能描述里是否有“这个技能是处理某某类型任务的首选”之类的强调语句，在描述里把技能的适用优先级写清楚，能提高调用率。

我还试过在系统 Prompt 中加入技能选择的引导规则，比如“当任务涉及 X 场景时，必须使用对应技能”，这个方法有效果，但是要注意别写得太死，否则模型在场景边界模糊的时候会强行调用技能，产生错误结果。

5.2 技能内部多步骤执行时的上下文污染

技能内部如果有循环或分支，比较容易出现上下文污染。典型现象是：步骤 B 需要读取步骤 A 的中间结果，但拿到的是上一次任务遗留的旧值。

我排查的时候会用一种很原始但有效的方法：在每次模型调用前后，把当前技能上下文的关键变量打印到日志里，做一次快照。日志格式大概是这样的：

[skill=inventory_checker][step=query_stock][input] sku=SKU001 ... [skill=inventory_checker][step=query_stock][output] stock_count=156 ...

通过对比相邻两次任务之间同一字段的值，很容易定位到是哪一步没有正确清空或者覆盖了变量。修复方式就是在技能实例创建时强制初始化上下文对象，并且在每次任务开始前调用一次reset()。不要依赖 Python 的默认值或者类属性来保存状态，这是最容易导致污染的写法。

另外要注意并发场景下的内存隔离。如果两个任务同时触发同一个技能类，实例对象必须独立，不能共享实例变量。

5.3 大模型返回非结构化内容导致的解析失败

技能内部调用模型时，即使我们在 Prompt 里明确要求输出 JSON，模型偶尔还是会返回一些额外的解释文字或者 Markdown 代码块标记，导致json.loads直接报错。这是大模型应用的经典问题，几乎所有做 Agent 的人都会遇到。

我的处理方式是三层兜底。第一层，在 Prompt 里输出格式要求写得非常明确，并要求“只输出 JSON，不要输出任何解释”。第二层，代码里做一个容错解析函数，自动剥离 Markdown 代码块标记，提取第一个合法的 JSON 对象。第三层，如果解析还是失败，重试一次，重试时在 Prompt 里补充说明上一次的格式错误。实测三层兜底配合，解析失败率可以压到 1% 以下。

这里还要提一个细节：模型输出的 JSON 字段顺序可能不固定，我们不能在代码里依赖“第一个字段是某某”这种假设，所有字段必须通过 key 来读取。字段缺失时要给默认值，并且把缺失字段名记录到日志，方便后续改进 Prompt 或者调整输出约束。

5.4 技能响应延迟过高

技能响应慢，通常有两个原因。第一个是技能内部串行调用太多，一步等一步，累计延迟高。解决办法是分析依赖关系，把没有前后依赖的步骤改成并行执行。我之前优化过一个报告生成技能，原本三个模型调用串行执行，耗时 8 秒左右，改成并行后降到了 4 秒以内，效果非常明显。

第二个原因是上下文中塞了太多历史信息，导致每次请求的 token 数很高，模型处理时间变长。解决办法就是前面说过的，控制每个步骤注入的上下文量，尽量只注入当前步骤真正需要的数据。如果必须传长文本，可以先做摘要压缩。

我还会给技能设置一个内部的时间预算。比如整条链路允许 10 秒，那阶段 A 只有 3 秒预算，阶段 B 有 5 秒预算，超过预算直接降级处理。预算机制能有效防止单个技能拖长整个系统的响应时间。

5.5 常见问题速查表

6. 技能评估与迭代：让 Skill 越用越准

6.1 建立技能级指标体系

技能上线后不能只靠人工感觉来评判好坏。我建议每个技能都配一组可量化的指标，至少包括：调用准确率、任务成功率、平均响应时长、异常率、上下文消耗量。

以customer_satisfaction_analyzer为例，我定义的指标是：评分误差（预测值和人工标注值的绝对差小于等于 1 的比例）达到 85%、任务成功率不低于 95%、技能平均响应时长不超过 5 秒、异常率不超过 2%。这些指标每周自动计算一次，变化趋势会在报表里展示。

有了指标之后，迭代才有依据。如果任务成功率高但评分误差大，说明技能流程没断，但模型判断精度不足，需要优化 Prompt 或者换更强的模型；如果异常率升高，说明有新的输入模式进来，技能没有覆盖到，需要补充输入数据处理逻辑。

6.2 用评测集驱动技能迭代

我手头每个核心技能都维护着一个评测集，大约 30 到 100 条样本。这些样本来源于真实业务中积累的上线前标注数据，也包括线上跑出来的失败案例，会定期补充进去。

评测集的使用方法是这样的：每次技能改动之后，用评测集跑一遍全量测试，对比改动前后的指标变化。如果某项指标下降了，就需要重新评估这个改动是否值得上线。这有点类似软件工程里的回归测试。没有评测集，你可能改了一处 Prompt，某个场景变好了，同时另一个场景变坏了，但你完全没感知到。

我个人习惯是一个月做一次评测集回顾，把线上新出现的问题样本补充进去，同时淘汰那些已经不再有代表性的旧样本。评测集的规模不用太大，关键是要覆盖到不同场景和边缘情况，尤其是那些曾经让技能出错的场景。

6.3 从线上日志中挖掘技能改进点

线上日志是技能迭代的金矿，但前提是日志要打全。我在前面提到过给技能打快照日志，这里再强调一下：每个技能入口和出口都要有结构化日志，里面至少包含任务 ID、技能版本、输入摘要、输出结果、耗时、错误信息。没有这些，后续做问题回溯会非常痛苦。

每周我会花半天时间翻一遍失败日志，重点关注三类：任务失败但错误信息模糊的、模型输出符合格式但内容明显不合理、响应耗时远高于平均水平的。这三类往往对应技能逻辑缺陷、Prompt 约束不足、以及流程效率问题，每一条都可能是一个改进点。

我印象最深的一次改进是：通过日志发现inventory_checker技能在 SKU 不存在时返回的错误提示太简略，模型拿到这个错误后不知道该怎么处理，导致整个任务卡住。后来我在错误里补充了“SKU 不存在，请先检查 SKU 是否正确或联系商家提供有效 SKU”的提示，任务失败率立刻下降了 6 个百分点。这种问题光靠代码 review 很难发现，一定要看真实日志里的模型行为链路。

6.4 技能版本管理与灰度策略

技能迭代越频繁，版本管理就越重要。我的做法是每个技能打版本号，大版本更新意味着输入输出契约变化，小版本更新只是内部逻辑或 Prompt 调整。大版本升级不能直接替换，必须先做兼容层，让旧版本的应用还能跑一段时间。

灰度上线这块，我的做法是只在评测集上验证通过后，先切 10% 的流量到新版本，观察一两天，对比新旧版本的核心指标。如果新版本在准确率、耗时、异常率上全面优于或者持平旧版本，再逐步放量到 50%、100%。这个策略在线上 Agent 系统里非常有必要，因为模型的非确定性意味着小版本改动也可能带来意料之外的行为变化。

还有一个容易被忽略的细节：技能升级时，系统 Prompt 里的技能描述也要同步更新。有些团队只改了技能内部代码，忘了更新描述文档，结果模型根据旧描述选择了技能，但实际执行的是新逻辑，行为不匹配会导致不少诡异问题。

7. 技能扩展：从单技能到 Agent 能力生态

到这一步，你的项目里应该已经有一个像样的技能库了。但技能的真正价值在于形成一种能力生态，让新的 Agent 可以“插上”现有的技能直接工作，而不是每个新 Agent 都从零开发。

我在项目里的做法是建了一个内部技能市场，把经过验证的高质量技能发布出来，供其他项目组的 Agent 直接使用。技能市场需要解决几个问题：技能发现（怎么让开发者找到合适的技能）、技能鉴权（谁可以用哪些技能，调用权限如何控制）、技能监控（每个技能的调用量、成功率、成本消耗）、技能下线（长期无人使用或者指标不达标的技能如何退役）。

当然，不是所有项目都需要技能市场，如果你的业务场景比较单一，可能不需要搞这么重。但不管规模大小，有一点是通用的：技能的重用性一定要在设计阶段就考虑进去。我见过太多项目，技能和服务强耦合，换一个业务场景就要改核心逻辑，最后技能库慢慢变成了一个又一个孤岛，失去了“组合”的价值。

所以技能设计的时候，我建议问自己一个问题：如果另一个完全不相关的项目要复用这个技能，它需要改动什么？如果它需要改的只是输入配置和 Prompt 模板，那这个技能就设计得不错；如果它必须改内部逻辑才能用，那这个技能也许更应该拆成一个工具集。

我在项目里还做过一个“技能组合推荐”的实验：根据任务描述，用相似度匹配推荐一组合适的技能编排方案。效果还行，但说实话现阶段还只能作为辅助。真正的高效编排还是依赖经验，这也是为什么我建议大家多在真实场景里打磨技能库，而不是把时间都花在追求抽象框架上。

模块化这件事，本质上是用前期的设计投入换长期的维护效率。Agent 和传统软件开发最大的不同是它有不确定性，而技能模块恰恰是应对不确定性的一种工程化手段——它把不确定的模型行为约束在可控的边界内，把确定性的逻辑（校验、流程、容错）用代码固化下来。这可能是我们现阶段做 Agent 工程最值得投入的方向之一。

我个人在实际操作中感受最深的一点是：技能文档描述和代码逻辑同等重要。很多团队把重心放在代码实现上，却忽略了前端描述对模型决策的引导作用。如果你只能记住这篇文章里的一件事情，那我的建议是：下一周挑一个技能，把它的描述文档按照“概述、适用条件、不适用场景、输入说明、典型示例”五段结构重写一遍，然后跑一个 30 条的回归测试，对比一下技能选择准确率和任务成功率的变化。实测下来，这个动作是所有技能优化手段里性价比最高的一个。

最后分享一个小技巧：在设计新技能时，先在纸上画一遍“用户在什么场景下会触达这个技能，触发后 Agent 应该经历哪几步，每一步失败后应该降级还是终止”。这个纸面推演花不了半小时，但能帮你提前规避掉至少一半的未来 Bug。技能设计做好做扎实，后续的 Agent 系统就会越来越顺，越来越像一个真正能用起来的产品，而不是一个玩具级 Demo。