Agent 调用 Skill 工具的完整流程是什么？

核心回答

Agent 使用 Skill，通常经历发现技能 → 判断是否匹配 → 加载正文 → 按指令执行 → 检查结果这条链路。

宿主先发现技能包，把名称、描述等简短信息提供给模型；模型结合任务判断需要哪项技能，或由用户显式指定。随后，宿主通过文件读取工具、专用加载工具或直接注入，将 SKILL.md 的指令放入本次上下文。模型据此组织步骤，按需读取参考资料、使用模板或请求执行脚本；运行时负责真正调用工具并返回结果，模型再检查是否满足任务要求。

**选择 Skill、读取 Skill 和执行业务动作是不同环节。**模型输出调用请求，程序执行请求；读取到一份文档并不意味着里面的脚本已经运行。Skill 也不一定需要业务工具，例如表情翻译技能加载规则后就可以直接生成结果。

展开说明

1. 发现阶段：让模型知道有哪些技能可用

宿主从配置的目录、技能仓库或其他来源发现技能，解析 SKILL.md 的元信息，建立名称、描述和位置之间的映射。对当前任务可用的技能，先提供简短目录，而不是把所有正文和资源一次性塞入上下文。

description 应说明适用任务和触发条件。例如“用户要求将文字翻译成 Emoji 时使用”，比“处理文本”更容易和代码审查等技能区分。同名技能由宿主按明确的优先规则处理；模型返回的名称应在已发现集合内查找，不能直接当作任意文件路径使用。

2. 激活阶段：把完整指令交给模型

如果由模型选择，它可以请求读取目录里给出的 SKILL.md，也可以调用宿主提供的技能加载工具。用户显式指定技能时，宿主还可以直接完成查找和注入。具体方式依赖产品和框架，不能把某个 load_skill() 名称当成通用标准。

文件读取方式通常让正文以工具结果进入对话；其他方式可由宿主组织消息。关键是后续模型调用实际获得了技能指令、来源和资源位置，而不是规定所有宿主必须放在同一种消息角色里。

3. 执行阶段：按技能流程使用本次输入和工具

模型读取正文后，结合用户输入执行步骤。正文引用的资料按需要再读取；相对资源路径要以技能所在目录解析。对于可执行脚本，模型请求调用已有的执行工具，运行时才负责启动程序、传入参数、处理超时并收集输出。

例如设计一个报表分析技能，可以规定先读取字段说明，再统计异常值，最后生成结论。本次的文件、统计时间和输出位置是执行参数；统计工具负责计算，技能负责规定流程。若技能要串联多个工具，应明确前一步哪些字段供下一步消费，并校验结果，不把一段未经确认的自然语言直接当成业务参数。

技能说明不能凭空赋予工具或权限。需要的执行环境、依赖和可用工具由宿主提供；模型提出的调用仍要经过运行时的参数与权限检查。工具返回失败时，Agent 根据错误类型补充输入、调整步骤或报告受阻，而不是继续宣称产物已完成。

4. 收尾阶段：检查产物，也维护技能版本

检查应对应任务目标：文件是否生成、数据是否完整、输出格式和内容是否满足要求。返回“脚本启动成功”和“报表生成成功”是两个不同结果。

为了定位问题，可以记录本次技能标识与版本或内容哈希、主要输入、工具结果和产物位置。技能更新后何时重新扫描、正文如何失效，由宿主的加载和缓存机制决定；编辑文件不会自动改变已经注入的旧上下文。长任务压缩上下文时，要让仍有效的技能要求可以保留或重新取得，避免执行到一半丢掉关键约束。

5. 教程中的实际例子

深度研搜的 Skills 示例 配置了文件系统 Backend 和 skills 目录，随后发起“只用表情翻译技能”的请求。对应的技能描述说明何时处理文字与 Emoji，Agent 按需取得正文，再按规则生成表情组合。

这个例子展示的是“技能目录 → 任务匹配 → 正文加载 → 按规则回复”。它没有必要为了使用 Skill 再调用数据库或其他业务接口。若换成带 Python 脚本的技能，后续才会多出运行脚本、读取退出状态和验证产物的步骤。

常见追问

大模型只会 Tool Calling，怎么调用 Skill？

可以把“加载技能”接到模型已有的工具调用链上：模型请求读文件或加载指定技能，程序把正文作为结果返回；下一次模型调用就能按照正文继续执行。宿主也可以提前注入正文。因此不需要模型另有一种原生“Skill Calling”协议。

Skill 没有工具，只有 Python 脚本，能执行吗？

需要宿主提供执行脚本的能力和相应环境。脚本存在于目录里只表示它是可用资源，模型读到文件名不会使它自动执行。程序也可以按固定流程调用脚本，再把结果交给模型，但那属于宿主实现。

两个 Skill 很相似，选错了怎么办？

先看描述是否把适用场景写清楚，是否应合并重复能力，或由明确任务参数选择。用容易混淆的请求检查选择结果，同时区分选错、未读正文和执行失败。若错误技能已触发业务写入，应先确认执行结果，再决定后续动作，不能仅换个技能重跑。

动态参数需要写回 SKILL.md 吗？

通常不需要。技能文档保留可复用流程与参数含义，本次参数由用户输入、任务状态或工具调用参数传入。必要时使用模板或结构化输入；缺少关键字段就补齐，不把每次请求都改成一份新的技能文档。

RagentJava Agent

基于 Ragent

Ragent 的执行链是：先看技能目录，调用 load_skill 取得手册，再让相关业务工具进入可用集合，执行时复查。 手册告诉模型怎样处理任务，工具才负责真正查询或修改业务数据。

手册怎样进入上下文

load_skill 的工具说明列出已启用技能的标识、名称和用途，初始输入不包含所有手册正文。模型选定技能后传入 skill_code，服务端从注册表读取正文，作为工具结果返回，并写入 ragent_loaded_skill 元数据；不存在或停用的技能返回错误，不伪装成加载成功。技能加载实现。

工具怎样随手册开放

AgentSkillMaskingMiddleware 根据当前上下文里的加载标记计算可见工具：所有启用技能关联的工具，减去已加载技能解锁的工具，余下的在本轮推理中隐藏。一个工具关联多份手册时，任一份已加载即可开放；未被技能关联的通用工具保持可见。

这不只修改模型看到的 Schema。中间件把隐藏集合放入运行上下文，McpToolProxy 执行前再检查一次；模型直接猜中工具名，也会收到“先加载手册”的错误。手册被会话压缩移走后，其加载标记消失，相关工具重新隐藏，摘要里一句“已经加载过”不能替代原手册。可见性计算、执行前复查。

这套机制控制按需披露，仍需配合写操作确认与业务权限。当前实现中，遮蔽计算异常会保留完整工具清单，因此不能把它当作任何故障下都能阻断越权的授权系统。

对应教程

参考资料