企业官网建设流程全解析

DB-GPT load_skill 工具深度指南：按技能名与文件路径加载 SKILL.md 工作流

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

导读

load_skill是 DB-GPT Agentic Data API 内置工具集中的一个核心工具，它负责按**技能名称（skill_name）与文件路径（file_path）**从技能注册表（Skill Registry）中解析并加载一个技能的内容——通常是SKILL.md中的指令与提示模板，并把它返回给 Agent。本指南将以 docs/docs/agents/modules/resource/tools/load-skill.md 为骨架，结合仓库源码讲解load_skill的参数、执行链路、底层注册表机制、适用场景与典型编排方式，帮助你理解并正确使用这一「技能驱动型 Agent」的入口工具。

一、工具定位：技能驱动的执行入口

DB-GPT 将 Agent 的能力组织为可复用的技能包（skill），每个技能包是一个包含SKILL.md的小型自包含目录（详见 技能总览）：

my-skill/ ├── SKILL.md # 必选：指令 + 元数据 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：按需加载的文档 └── assets/ # 可选：模板、输出资源、静态文件

当 Agent 面对的任务恰好匹配某个技能时，与其临时发挥（improvising）整套执行流程，不如加载一份经过编排的标准工作流。load_skill就是完成这一步的工具——它只负责「读入」，不负责「执行」。在 内置工具总览 给出的推荐执行顺序中，load_skill总是处于技能驱动工作流的第一步：

Skill-driven workflow（技能驱动工作流） 1. load_skill 2. sql_query 或 code_interpreter 3. html_interpreter 用于最终交付

二、参数说明

load_skill接受两个必填参数，均为字符串：

{ "skill_name": "skill name", "file_path": "skill file path" }

从源码看（skill_tools.py），skill_name是解析技能的核心键：工具首先通过注册表按名称精确查找技能，若未命中则遍历注册表做大小写不敏感匹配。file_path主要用于向 Agent 返回「技能来自哪个文件」的定位信息，实际读取内容并不依赖该路径本身，而是依赖注册表中已注册的技能对象。

三、它做了什么：三步执行链路

原文档将load_skill的行为概括为三步，对应源码中的实现如下：

1. 从注册表解析技能（resolve the skill from the registry）

工具调用dbgpt.agent.claude_skill中的全局技能注册表：

from dbgpt.agent.claude_skill import get_registry registry = get_registry() matched = registry.get_skill(skill_name) if not matched: for s in registry.list_skills(): if s.name.lower() == skill_name.lower(): matched = registry.get_skill(s.name) break

注册表类SkillRegistry维护_skills字典（名称 →FileBasedSkill实例），提供register_skill、get_skill、list_skills、match_skill、load_from_directory等接口，详见 claude_skill/init.py。技能通过load_skills_from_dir()或SkillLoader.load_skills_from_directory()批量注入注册表，后者会递归扫描目录下的*.json、*.yaml、*.yml与SKILL.md文件（见 loader.py）。

解析失败时的行为：若注册表中找不到匹配技能，工具不会抛异常，而是返回一段结构化的 JSON 错误块，便于 Agent 感知并调整策略：

{ "chunks": [ {"output_type": "text", "content": "Skill 'skill_name' not found"} ] }

2. 读取技能指令或提示模板（reads the skill instructions or prompt template）

命中后，工具把解析到的技能对象与提示写入 Agent 的react_state，供后续编排使用：

react_state["matched"] = matched react_state["skill_prompt"] = matched.get_prompt()

随后按优先级取出内容：

if matched.instructions: chunks.append({"output_type": "markdown", "content": matched.instructions}) elif matched.prompt_template: chunks.append({"output_type": "markdown", "content": prompt_text})

对于文件型技能，instructions即SKILL.md中 frontmatter（---包裹的 YAML 元数据）之后的正文部分；get_prompt()会将其封装为PromptTemplate（Jinja2 格式、非严格模式），见 claude_skill/init.py。

3. 将加载的工作流内容返回给 Agent（returns the loaded workflow content）

工具的返回值统一采用「chunks」协议，便于前端与 SSE 流式渲染。load_skill的返回结构大致为：

{ "chunks": [ {"output_type": "text", "content": "Skill: financial-report-analyzer"}, {"output_type": "text", "content": "File path: skills/financial-report-analyzer/SKILL.md"}, {"output_type": "text", "content": "---"}, {"output_type": "markdown", "content": "……SKILL.md 中的完整工作流指令……"} ] }

四、何时使用它

load_skill并非总是必需，它的适用条件对应原文档的「When to use it」：

• 任务匹配一个可复用的技能（the task matches a reusable skill）：Agent 识别出任务场景与某个技能的定义域一致，例如上传了财报 PDF、CSV 数据集等；
• 技能包含经过编排的业务逻辑（the skill contains curated business logic）：技能内封装了固定的分析框架、指标口径或输出规范，直接照搬比临时设计更可靠；
• 工作流应在执行前标准化（the workflow should be standardized before execution starts）：先加载标准化步骤，再执行sql_query/code_interpreter/execute_skill_script_file等工具，避免执行路径发散。

反过来说，当任务没有匹配的既有技能、或只是简单的单步查询时，直接使用code_interpreter、sql_query等工具即可，无需经过load_skill。内置工具的选择边界可参考 内置工具总览 中的工具选型表。

五、完整示例

以仓库自带的财报分析技能为例（技能定义见 financial-report-analyzer/SKILL.md，其 frontmatter 中name: financial-report-analyzer），load_skill的标准调用如下：

{ "skill_name": "financial-report-analyzer", "file_path": "skills/financial-report-analyzer/SKILL.md" }

加载成功后，Agent 会获得该技能定义的核心工作流（数据提取 → 财务比率计算 → 图表生成 → 深度分析 → 渲染报告）。仓库中同类的可加载技能还包括csv-data-analysis、walmart-sales-analyzer、agent-browser等，均位于 skills/ 目录。

六、注意事项（Notes）

• load_skill只加载指令，不执行工作流本身。原文档对此特别强调：加载（loads instructions）与执行（execute the workflow）是两件事。技能目录下scripts/中的脚本并不由load_skill运行，而是由配套的execute_skill_script_file工具按名调用（见 skill_tools.py）。
• 加载后，Agent 应遵循技能声明的必需工具与步骤。技能可以在SKILL.mdfrontmatter 中声明required_tools，加载后由配套的load_tools工具解析并装配这些工具资源（见 react_tools.py）。

七、源码级原理：注册表与状态隔离

1. 全局注册表与批量加载

所有文件型技能统一由SkillRegistry管理。系统启动或技能变更时，通过以下方式之一把SKILL.md灌入注册表：

• load_skills_from_dir(directory, recursive=True)：递归扫描目录下所有**/SKILL.md并注册（claude_skill/init.py）；
• SkillLoader：支持从文件（JSON / YAML / SKILL.md）、Python 模块、目录三种来源加载技能（loader.py）；
• 技能管理模块get_skill_manager()：负责在SKILLS_DIR及其user/、claude/、project/子目录中定位技能路径，并支持通过环境变量DBGPT_DISABLE_PERSONAL_SKILL_SCRIPT_EXECUTION控制个人技能脚本的执行（manage.py）。

2. SKILL.md 的解析约定

FileBasedSkill要求SKILL.md以---开头，格式为「frontmatter 元数据 + 指令正文」。元数据解析优先使用 PyYAML（缺失name或description时报错），缺少 PyYAML 时回退到逐行解析。frontmatter 支持name、description、version、author、skill_type、tags、required_tools、required_knowledge、config等字段，详见 claude_skill/init.py 与自定义技能使用指南。

3. 状态隔离与并发安全

load_skill在 ReAct 工具工厂make_react_tools中被构造，每个主/子 Agent 调用工厂一次，各自捕获独立的react_state字典。工具把matched与skill_prompt写入自己捕获的字典，从而保证子 Agent 间的状态隔离。相关单元测试验证了「不存在的技能不会污染兄弟 Agent 的状态」以及「每个 Agent 的工具集相互独立」这两个关键行为，见 test_react_tools.py。

4. 与其它内置工具的编排关系

加载技能只是起点。技能内部往往编排多个内置工具协同完成端到端任务（详见 如何用技能）：

load_skill → 加载技能指令 sql_query → 按需检索结构化数据 code_interpreter → 计算指标、转换数据、生成图表 shell_interpreter → 按需执行 Shell 命令 execute_skill_script_file → 执行技能 scripts/ 目录下的脚本 html_interpreter → 渲染最终 HTML 报告或页面

八、最佳实践小结

1. 技能可复用才用技能：当流程需要可重复、可标准化时，为任务编写/选用技能并配合load_skill加载，而不是让 Agent 每次自由发挥；
2. 严格遵循技能指令：加载后按技能定义的工具顺序与步骤执行，优先使用技能要求的工具而非临场替代方案；
3. 善用execute_skill_script_file：技能内的 Python 脚本应通过该工具执行，系统会自动处理脚本输出中的图片转存（/images/URL 映射）、ratio_data、auto_data等副作用，无需load_skill参与；
4. 报告类任务用html_interpreter收尾：当技能产出网页或报告时，用html_interpreter做最终渲染，形成「加载技能 → 分析计算 → 渲染交付」的完整闭环；
5. 理解加载与执行的边界：load_skill永远只负责读入内容，任何执行动作都交给后续工具，这保证了技能编排的清晰与可审计性。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT