企业官网建设流程全解析

1. 从 Function Calling 到 Skill：一次工具调用范式的升级

去年底今年初，各大模型厂商不约而同地开始推广一个概念——Skill。Claude 把它做成了一套带SKILL.md的文件夹规范，豆包、Gemini、OpenClaw 也各自推出了类似的能力封装。很多人第一次听到这个词，第一反应是"这不就是 Function Calling 换个名字吗？"我当时也是这么想的，直到真的在自己的 Agent 项目里把二十多个函数调用改写成 Skill 之后，才意识到这远不是改个目录结构那么简单。

先说一个最直观的差异：Function Calling 里，你需要在系统提示词里塞一大段 JSON Schema，告诉模型"有哪些函数、参数是什么"，模型收到用户消息后，自己决定是否触发某个函数。这个方案在函数数量少的时候很顺手，但一旦函数多起来，系统提示词会急速膨胀，而且模型经常会在多个函数之间犹豫——"这个查询用哪个工具最合适？"这已经成了 Agent 召回准确率的第一杀手。

Skill 的思路完全不同：它把"某个能力的完整使用说明"外置成独立文件。模型不见得每次都需要把所有 Skill 的细节都读进上下文，而是先看到一份索引——每个 Skill 叫什么、管什么用，必要时再去展开读取完整的SKILL.md。换句话说，Skill 解决的问题不是"怎么把一个函数接进模型"，而是"怎么让模型在自己有限的上下文窗口里，知道有哪些工具可用、每个工具怎么用、什么时候该用哪个"。

这个转变背后是视角的切换：Function Calling 是面向程序员的函数注册表，Skill 是面向 Agent 的能力百科。程序员关心的是参数类型和返回值，Agent 关心的是"我面对一个问题时，我应该调用哪个能力来解决它"。理解了这层差异，后面所有的架构设计逻辑才能顺畅展开。

也正是因为这种差异，Skill 机制在落地时几乎同时牵扯到两个层面的工程问题：一是运行时架构，也就是解析、检索、执行、结果回填这整条链路怎么设计；二是内容工程，也就是一份SKILL.md怎么写才能让模型真正读得懂、用得上。这两块缺一不可，而且互相牵制。接下来的内容，我想把这两条线都拆开来讲，结合我实际改造项目的经验，给出可以直接照抄的完整方案。

2. Skill 调用机制的总体架构拆解

2.1 四层链路：索引层、解析层、执行层、反馈层

我把 Skill 调用机制抽象成四条链路，这也是我在自己项目里最终落地的架构骨架，四层分别为索引层、解析层、执行层和反馈层。

索引层解决的是"模型怎么知道有哪些 Skill"。我会在每次会话启动时，加载一份全局 Skill 索引，里面包含每个 Skill 的 ID、名称、一句话描述、标签、路径以及触发建议。这份索引会作为持久上下文，常驻在系统提示词里，但它的体量必须严格控制——每新增一个 Skill，索引只增加一两行描述，绝不能把完整文档塞进去。我见过一些团队把每个 Skill 的完整SKILL.md都写进系统提示词，二十个 Skill 之后系统提示词直接冲上两万 token，模型对话质量肉眼可见地下降。

解析层负责把SKILL.md转成结构化配置。一份 Skill 文件里通常包含名称、描述、使用场景、调用参数、操作步骤、依赖条件、示例片段等区块，解析层会把这些内容提取成 JSON 结构，供运行时做检索和匹配。这一层看起来简单，实际是坑最多的地方——因为SKILL.md本质是给人写的 Markdown，格式自由度很高，一旦缺乏严格的前置校验，解析结果就是玄学。

执行层是最核心的链路：模型通过一次特殊格式的调用指令来触发某个 Skill，执行层接收指令后，从解析结果中读取该 Skill 的配置，调用底层工具或外部 API，再把结果以统一格式回填给模型。这里的核心设计决策是：Skill 本身不做业务逻辑，它只是"能力说明书 + 调度配置"，真正干活的是它绑定的工具函数或外部服务。这种解耦非常重要，否则 Agent 框架会演变成一个所有逻辑都堆在 Skill 里的巨型泥球。

反馈层负责把执行结果、错误信息和状态变化回传给模型，模型基于反馈决定下一步动作。我实际踩坑后的经验是：反馈层的格式必须高度模板化，最好是 JSON 包裹的文本，千万不要把原始工具输出直接丢给模型。比如一个数据库查询 Skill，原始返回可能是 500 行的结果集，但反馈层应该先对结果做压缩、截断、摘要，只把最精炼的信息传给模型，否则上下文瞬间就被冲爆。

2.2 Skill 与系统提示词的关系

设计 Skill 机制时，最容易忽略的问题是"它要在多大程度上进入系统提示词"。我见过两种极端：一种是什么都不放，模型完全靠解析用户消息去猜该用哪个 Skill，结果命中率惨不忍睹；另一种是事无巨细全部放进系统提示词，上下文被 Skill 文档撑满，主任务反而做不好。

我的折中方案是：系统提示词只放索引摘要，加上一条硬性的调用规则说明。索引摘要控制在 500 字以内，每一行描述一个 Skill 的"名字 + 一句用途 + 大概率适用场景"，然后单独用一小段说明"当你判断用户需求属于以上某个 Skill 的适用场景时，请使用 {skill_name} 指令触发它"。这部分的目的是让模型形成"工具检索意识"，而不是教它工具的具体用法——具体用法留到模型真正触发 Skill 之后，执行层把完整SKILL.md内容注入当前轮次的辅助消息里。

这个设计有一个附带好处：系统提示词稳定了，缓存的命中率会显著提高。现在主流推理服务都对系统提示词做 KV Cache，系统提示词越长，每次请求的首 token 延迟就越高。我在项目中实测，把系统提示词从 1.8 万 token 压到 2000 token 之后，首 token 延迟平均下降了约 40%，这个收益在低并发场景里其实比想象中还明显。

2.3 Skill 的决策边界：谁能触发、什么时候触发

很多人在做 Skill 机制时忽略了一个关键问题——触发权限。是不是无论用户说什么，模型都可以自由触发任何 Skill？我一开始的做法是无约束自由触发，结果模型经常在不该触发时触发，比如用户只是随口问了一句"你今天怎么样"，模型就调用了天气查询 Skill。后来我把 Skill 配置里增加了 trigger conditions 字段，明确写出"只有在用户的输入包含城市名、时间诉求、且意图为查询天气/穿衣/出行建议时，才允许调用天气 Skill"。加了这层约束后，误触发率下降了一大截，同时命中率反而略有提升——因为模型对"什么条件才该触发"的理解更清晰了。

这里还可以加一道硬性规则：高危类 Skill 需要二次确认。比如删除数据、发邮件、执行 Shell 命令这类操作，可以在配置里标记requires_confirmation: true，执行层发现这个标记后不直接执行，而是让模型向用户确认后再发起调用。我实际遇到的场景是用户让 Agent"把这个文件夹里的临时文件清理一下"，模型直接触发了文件删除 Skill，在测试环境问题不大，但在生产环境这就是事故。加上二次确认机制后，这类风险基本被兜住了。

3. Skill 文件格式与解析实践

3.1 SKILL.md 标准结构与字段设计

一份标准的SKILL.md到底长什么样？这里给出一个我经过多次调整后定型的模板，它同时兼容 Claude 官方 Skill 规范和自建解析器：

--- name: database_query description: 对业务数据库执行只读 SQL 查询，支持多表 join 与聚合计算 version: 1.2.0 tags: [database, sql, query] triggers: - "用户提到查询数据、报表、统计" - "用户给出 SQL 语句并要求执行" - "用户问题涉及数据库中的业务记录" execution: type: tool tool_id: mysql_query_executor requires_confirmation: false timeout: 30s parameters: - name: sql type: string required: true description: 要执行的 SQL 语句，必须是 SELECT 开头的只读语句 - name: limit type: integer required: false default: 100 description: 返回结果的最大行数，默认 100 行 --- # 数据库查询 Skill ## 用途 ...（完整用法说明，供模型触发后阅读）

我把字段分成三组：前置元信息、执行配置、参数声明。前置元信息用于索引层做检索，执行配置告诉运行时该 Skill 用什么方式执行，参数声明则是一个简化的 JSON Schema。这里要注意的是：SKILL.md中参数声明的目标对象是模型，不是代码校验器。模型需要在一个充满噪声的上下文中快速理解参数含义，所以每个参数的 description 必须用最少的话说清楚"是什么、什么时候填、不填会怎样"。

3.2 解析器的容错设计

写解析器时我最头疼的问题是 Markdown 的极端灵活性。不同的人写SKILL.md会用不同的层级结构、不同的列表符号、甚至不同的 front matter 风格。如果解析器过于严格，常见结果就是：一旦某个字段写错，整个 Skill 直接失效，模型根本找不到它。

我的做法是分级容错：第一级，用正则提取 front matter 里的键值对，这个最稳定，因为格式受 YAML 约束；第二级，把正文转成纯文本后，按标题大纲切分成段落，再根据段落中是否包含"用途、示例、注意"等同义关键词做语义归类；第三级，如果结构化提取失败，就把整个正文作为 description 的兜底内容，保证 Skill 至少还能被检索到，只是细节注入能力弱一些。这套三级策略在实践中非常管用——它保证了"解析质量可以降级，但解析永远不失败"。

为了防止前端写坏格式，我还在仓库的 CI 里加了一个 skill lint 步骤，用脚本检查每个SKILL.md是否满足最少字段要求（name、description、execution.type、parameters 至少一项），不满足直接失败合并请求。这个环节帮我把很多低级错误挡在开发阶段，而不是让它们跑到运行时才爆雷。

3.3 版本管理与 Skill 热加载

Skill 不是一次性写死的东西。随着场景扩展，同一个 Skill 可能需要频繁修改描述、参数和示例。我参考常见的包管理习惯，给每个 Skill 增加了 version 字段，并在索引层记录"当前已加载的版本号"。当文件系统检测到SKILL.md变更后，触发热加载流程：重新解析文件、更新全局索引、清除该 Skill 相关的缓存标记。这样线上改动不需要重启 Agent 服务就能生效，对调试体验的提升非常大。

但热加载有个隐蔽的坑：模型对话过程中可能已经缓存了旧版本的 Skill 文档。比如第一轮模型读取了 database_query 的完整说明并记在上下文中，第二轮这个 Skill 更新了，模型记忆里却还是旧版本。我在工程上采用的折中方案是：热加载生效只针对新会话，当前会话继续保持旧版本上下文，同时在执行层每次调用时都会携带一个 skill_version 字段，如果执行层发现版本与解析层不一致，会返回一个"Skill 已更新，请重新读取"的信号，让模型主动放弃过时的上下文。虽然多了一次交互轮次，但避免了错误认知。

4. Skill 调用的运行时实现

4.1 调用指令的设计：让模型用最少的 token 表达意图

Skill 的调用指令决定了模型怎么开口"说"它要用哪个技能。我试过三种方案，对比下来体验差异很大。第一种是系统函数式调用，也就是走标准 function calling 通道，把 Skill 当作函数声明给模型；第二种是文本标签式调用，让模型在回复中输出<trigger>skill_name</trigger>标签；第三种是特殊 token 分隔，类似于[[skill:database_query]]。

最终我的选择是第三种。原因是：标准 function calling 要求参数严格遵循 JSON Schema，模型如果一时没想清楚参数，会倾向于不调用或者反复调用错误参数，白白增加 token 开销。文本标签虽然灵活，但需要一层额外的协议解析，还会让模型在对话中产生无关的可见输出。特殊 token 方案在协议层最干净，模型只需要记住"我想用 database_query 这个技能查询数据"，执行层拿到后，再进一步跟模型交互索要参数。

具体格式我定为[[action:skill_id||param_key=param_value||param_key2=param_value2]]。之所以重复param_key=param_value而非用 JSON，是因为实测中模型生成键值对的稳定性明显高于生成严格 JSON，尤其当参数值里含有换行或特殊字符时，JSON 很容易被截断或产生多余逗号。

4.2 参数收集与校验的两阶段交互

很多人以为 Skill 触发之后就顺理成章地执行了，但真实情况是：大部分情况下模型触发 Skill 时，并没有凑齐所有必需参数。比如模型说"帮我查一下这个月的销售额"，它可能先触发了 database_query，但你根本还没告诉它数据库连接是哪个、时间范围是什么。

我设计的执行流程是两阶段交互。第一阶段，模型触发 Skill 后，执行层先提取已提供的参数，检查哪些是必填但缺失的；如果缺失，执行层生成一条"参数收集请求"，让模型向用户追问。第二阶段，当所有必填参数齐备后，执行层真正调用工具函数，拿到结果后走反馈层处理。

两阶段交互的关键在于：参数收集请求必须以"建议追问内容"的形式回给模型，而不是直接拿一套字段列表砸给模型让它自己问。例如执行层返回的应该是"该 Skill 缺少 begindate 参数，建议向用户询问统计起始日期"，模型读到后自然生成一句自然语言提问。这样既保证了参数完备，又不会破坏对话的自然性。

4.3 超时、并发与上下文压缩

Skill 执行过程中，外部工具有可能是慢的，甚至是不可靠的。数据库查询可能五秒返回，也可能卡在半分钟。我在每个 Skill 的配置里设置了独立的超时阈值，执行层用可取消的请求上下文包裹调用。超时后返回的反馈不是一堆错误堆栈，而是一句"该操作执行超时，请检查服务状态或更换方案"，模型拿到这个反馈后可以自行选择重试、换策略，或者向用户说明情况。

上下文压缩是另一个必须处理的点。假设一个数据分析 Skill 返回了 200 行统计结果，模型真正需要理解的可能只是前 20 行的趋势。如果把这 200 行全部塞回上下文，不仅浪费 token，还会稀释模型对用户原有意图的注意力。我的做法是：执行层对工具返回结果做三层处理——先截断（超过阈值直接截），再摘要（对数值型结果做聚合统计），最后提炼（把关键结论单独提取出来）。这层逻辑看似简单，但它直接决定了长会话场景下模型的稳定表现。

4.4 与 MCP 生态的协同

讨论 Skill 机制时绕不开 MCP（Model Context Protocol）。MCP 解决的是"工具怎么通过标准协议暴露给 Agent"，Skill 解决的是"模型怎么知道这些工具适合什么时候用"。两者可以无缝叠加：一个 Skill 的 execution 配置里可以声明type: mcp_tool加上 MCP 的工具名，执行层接收到触发后，通过 MCP 客户端去调用对应工具。我在项目中就把内部十几个 MCP 工具全部包装成了 Skill，好处是模型侧面对的是一份份带有场景说明的 Skill 卡片，而不是一堆裸的工具名。对 Agent 来说，这相当于既有了"标准工具插头"（MCP），又有了"工具使用说明书"（Skill）。

5. 索引与检索：模型如何找到对的 Skill

5.1 向量检索与关键词召回的组合策略

当一个项目里的 Skill 数量超过 15 个时，单纯靠系统提示词里的文字索引已经不够用了。模型对索引末尾几行的注意力天然弱于开头几行，所以排在后面的 Skill 容易成为"永远不被触发"的死工具。我在实践中引入了一套组合检索机制：每次用户消息进来后，在决定要不要触发 Skill 之前，先把消息做一次检索，找出最相关的 3-5 个 Skill，然后把它们的完整文档注入当前上下文的辅助区域。

具体的检索方案我用的是关键词召回加向量召回的混合策略。关键词召回是基于消息中的实体词与 Skill 标签的匹配，向量召回则是把用户消息和每个 Skill 的 description 都做 embedding，用余弦相似度排序。两者取并集后按加权打分排序。实测下来，单纯向量召回在"用户描述模糊但语义相关"的场景表现好，单纯关键词召回在"用户直接说出技术术语"的场景表现好，混合策略能够把最终命中准确率从约 70% 提升到 88% 左右。

5.2 索引文件结构与增量更新

既然检索依赖索引，索引本身的组织方式就很重要。我的索引文件采用以下结构：

{ "skills": [ { "id": "database_query", "name": "数据库查询", "version": "1.2.0", "description": "对业务数据库执行只读 SQL 查询", "tags": ["database", "sql", "query"], "triggers": ["查询数据", "报表", "统计"], "path": "./skills/database_query/SKILL.md" } ], "updated_at": "2025-06-12T10:30:00Z" }

索引的更新策略与热加载绑定：当某个SKILL.md变更后，只重算该条目的 embedding 并更新updated_at，而不是全量重建。全量重建在 50 个 Skill 以内速度尚可，但考虑到服务会在运行中频繁变更 Skill，增量更新能显著降低资源开销。这里有一个值得注意的细节：description 的修改会显著影响向量检索结果，所以每次改动后我不仅更新索引，还会主动清一轮该 Skill 的历史检索缓存，防止旧结果污染新会话。

5.3 模型犹豫时的兜底策略

无论检索策略做得多好，模型总会遇到"多个 Skill 似乎在语义上都沾边"的情况。我观察到模型在这种状态下有两个典型表现：要么沉默不触发任何 Skill，直接凭自己的常识硬答，给用户一个不准确的答案；要么一口气触发好几个 Skill，把上下文搞得一团糟。前者属于"漏触发"，后者属于"过度触发"。

针对漏触发，我会在检索层做一次"低置信度提醒"：当最高相似度分数低于阈值但又高于一个底线时，在系统提示词里附加一句"你的可调用工具列表里可能有相关能力，建议结合用户真实意图判断是否需要触发"。这句提示在实验中能显著提升 Recall。针对过度触发，我会在反馈层加一个抑制机制：一条用户消息中最多允许触发两个 Skill，如果检索层返回了超过两个候选，就让模型自己对候选做一次取舍，而不是把全部候选都带入上下文。这个限流设计有效地控制了上下文膨胀。

6. 上下文生命周期：从触发前到执行后

6.1 Skill 文档的注入与回收

Skill 机制最考验工程细节的，就是上下文在"触发前、触发中、执行后"三个阶段的编排。触发前，系统提示词里只有轻量索引，模型不知道 Skill 的用法细节。触发中，执行层把命中的SKILL.md完整内容注入当前轮次消息的上下文，模型得以理解该 Skill 的完整操作规范。执行后，完整的 Skill 文档理论上应该"退场"，不再继续占用后续轮次的上下文窗口。

但现实的难点在于：LLM 上下文是连续的，你没法像操作系统回收内存那样精确地把某段 token 从上下文中抹掉。我采用的近似方案是：执行后，反馈层会附带一行摘要，例如"database_query 已按 SQL 查询完成，如需更多数据请重新触发"，然后在下一次全局上下文整理时，将上一轮注入但本轮未再被引用的长篇 Skill 文档截断或替换为一行回收标记。这个策略在长对话中能明显减少上下文碎片化。需要注意，回收标记本身要设计得足够轻，否则整理上下文的动作本身就变成了新的 token 负担。

6.2 长会话中的 Skill 记忆衰减

实测中一个非常有价值的发现是：模型在对话前几轮对 Skill 索引的注意力很高，但对话轮次超过 15 轮后，即使索引仍在系统提示词里，模型触发 Skill 的频率也会下降。我判断这不是模型"忘了"，而是上下文中累积了大量用户消息与助手回复，相对稀释了系统提示词的影响力。

为了对抗这种衰减，我在每 5 轮对话后执行一次"索引刷新"：重新把最近两轮的关键用户意图提取出来，和当前 Skill 索引做一次相关性加权，把最相关的 3 个 Skill 的简要提示重新追加到消息上下文的末尾，提醒模型"接下来的任务里，这几个能力可能仍然相关"。这个方案没有什么高深理论，但它在工程上是行之有效的——实际项目里长会话场景的 Skill 触发率从 46% 提升到 67%。

6.3 并发会话之间的 Skill 状态隔离

当多个用户同时使用同一个 Agent 服务时，Skill 的状态隔离就是不得不考虑的问题。Skill 本身是只读文件，天然可以在会话间共享，但 Skill 执行过程中产生的中间产物（比如缓存结果、临时文件、带状态的游标）必须隔离。我为每个 Skill 的运行时上下文打上 session_id 标签，所有临时产物都挂在这个标签下，会话结束或超时后由 GC 统一清理。早期我没有做这个隔离，出现过两个会话共享同一个数据库游标导致结果互相污染的问题，排查过程相当狼狈。如果你在做多租户版本的 Agent，建议一开始就把 session 维度放进 Skill 执行设计里。

7. 触发准确率优化：从 60% 到 90% 的调优实录

7.1 影响触发准确率的三大要素

触发的准确率几乎决定了一个 Skill 机制到底可不可用。如果模型总是漏触发、误触发，那 Skill 带来的能力上限再高也无济于事。我在调优过程中总结出三个影响因子。

第一个是 Skill 描述的"意图贴近度"。描述写得越贴近用户口语，模型越容易匹配上。比如把"数据库查询"泛化成"查数据、看报表、统计销售额、拉取记录"这么一组说法，效果远好于只写一句规范的"执行 SQL 查询"。第二个是示例 snippets 的丰富度，SKILL.md正文里的示例对话越多，模型对"什么话术会触发这个 Skill"的把握就越准。我把重点场景的示例控制在 2-3 个，太少模型理解不充分，太多则会在注入阶段浪费 token。第三个是系统提示词里索引摘要的排序，相关性越高的 Skill 放越靠前。为此我让系统提示词里的索引不再固定顺序，而是根据全局统计的触发频率动态重排，低频 Skill 会被自然沉底但不删除，高频 Skill 保持靠前位置。

7.2 数据驱动的触发策略迭代

触发策略不能拍脑袋，必须建立在真实日志反馈上。我会在每次触发的反馈层记录三样东西：触发前的用户消息、选中的 Skill ID、执行后用户是否继续追问或纠正。持续采集一段日志后，按 Skill 维度统计"触发后用户不再追问"的比例，这个比例可以粗略当作"这次触发是否真的解决了用户问题"的代理指标。对于低分 Skill，要么改描述，要么调整触发条件，要么直接下线。

我还引入了一个惩罚机制：如果某个 Skill 在近 30 次触发中有 20 次触发后用户都追问了"不对，我不是想问这个"，那它的索引排序会被自动下调；同一时段内长期零触发的 Skill，在索引里会被标记为"try entering by explicit name only"，也就是只允许用户在明确提到它的名字时模型才去触发。这套机制的初衷不是惩罚 Skill，而是让模型的注意力始终集中在真正有用的能力上。

7.3 A/B 测试一个 Skill 描述改动的完整流程

如果你要系统地调优 Skill，我建议养成 A/B 测试的习惯。流程可以这样跑：选定一个待优化的 Skill，将现有版本作为 A 组，新版本描述作为 B 组，让流量按 50:50 分流，分别记录两组的触发准确率、执行成功率、用户跟评率。至少跑 3-5 天积累足够样本，再用统计口径判断新版是否显著优于旧版。如果只靠感觉改，很容易陷入"改完觉得变好了，但又说不清好在哪里"的怪圈。我在实践中通过这套流程把 database_query 的触发准确率从 62% 提到了 84%，靠的正是连续三轮 A/B 测试加基于日志的修正。

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

8.1 排查速查表

我把实际项目里踩过的坑整理成了一张速查表，遇到问题可以先对着表排查，能省下大量试错时间。

8.2 三个让我印象深刻的线上问题

第一个问题是"Skill 描述写得越详细，触发准确率反而越低"。后来我从日志里发现，过长的描述把模型注意力引导到了次要细节上，它太关注某一句具体措辞，反而忽略了用户意图的整体语义。从那以后我把每个 Skill 的 description 压缩到不超过 50 字，再在正文用示例补足细节，效果立竿见影。

第二个问题是"热加载生效后，旧会话的模型还在用旧 Skill 执行"。这个问题在代码层面几乎不可见，因为索引版本号确实更新了，但对话缓存里的旧SKILL.md内容还在被读取。最终通过在执行层返回错误信号并让模型重新读取的方式解决，虽然多了一轮交互，但至少保证了行为一致。

第三个问题是"模型在低相关性时也会强行触发 Skill，试图表现得积极"。尤其是在用户问"有没有什么工具可以帮我做 XX"这样的元问题时，模型容易把这个请求误解为"现在就调用 XX Skill 做个演示"。我后来在系统提示词里加了一条规则：当用户在询问工具本身而不是要求执行任务时，应直接回答，不应触发任何 Skill。这条规则非常朴素，但帮我挡住了一大类误触发。

8.3 调试 Skill 调用的三个实用技巧

最后分享三个调试技巧。第一个是"镜像日志法"：在 Skill 执行链路的每个关键节点打结构化日志，包括触发来源、注入文档 ID、参数收集结果、执行耗时、反馈输出 token 数。排错时把这些日志按会话 ID 串起来，一眼就能定位问题在哪一层。

第二个是"最小复现法"：当某个 Skill 在复杂对话里表现不稳定时，把它剥离出来，用一个全新的会话、一句最简单的用户消息去测。如果最简单场景下能稳定触发，那问题基本出在上下文干扰；如果最简单场景下也表现异常，那问题多半在 Skill 文件本身或检索链路。

第三个是"回归用例集"：把历史纠错过的典型用户消息收集起来，形成一个固定回归集。每次修改索引、描述或触发规则后，跑一遍回归集，确保没有修好一个 bug 又引入另一个。早期没有这个习惯时，我经常陷入"调好这个 Skill 弄坏另一个"的死循环，补上回归测试后这类问题彻底消失了。

9. 结尾：一点个人体会

我在把 Skill 机制落地到真实项目之前，看了很多宣传口径，觉得这东西不过是给工具调用套了个壳。真正动手改完再跑完几轮调优之后，我才理解到它本质上是一次"从程序员视角到模型视角"的架构切换。Function Calling 是让模型去匹配程序员定义好的函数，而 Skill 是让系统的能力说明书以模型最容易理解的方式组织起来。两者的差距不在功能，而在表达方式——后者多出来的这一层"用自然语言描述能力边界与使用场景"的设计，恰恰是让 Agent 真正"学会用工具"的关键。

最后再分享一个实用的建议：如果你准备在自己项目里引入 Skill 机制，别一上来就追求把全部工具都改造成 Skill。先选 3-5 个最高频、最容易出错的工具做试点，把索引、解析、执行、反馈这四层链路跑通，再逐步扩展。Skill 机制的好处是模块化，扩展起来并不困难，但基础架构没搭稳就盲目铺量，后面光排查问题就够你喝一壶的。踩过几次坑之后你会慢慢发现，这个机制真正考验的，既不是模型能力，也不是框架代码，而是你对"模型如何理解工具"这件事的耐心和细致程度。