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_namestring要加载的技能名称应与SKILL.mdfrontmatter 中的name字段一致如financial-report-analyzer匹配时支持大小写不敏感回退file_pathstring技能文件路径通常指向技能包内的SKILL.md如skills/financial-report-analyzer/SKILL.md从源码看skill_tools.pyskill_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()会将其封装为PromptTemplateJinja2 格式、非严格模式见 claude_skill/init.py。3. 将加载的工作流内容返回给 Agentreturns 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 skillAgent 识别出任务场景与某个技能的定义域一致例如上传了财报 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-analyzerload_skill的标准调用如下{ skill_name: financial-report-analyzer, file_path: skills/financial-report-analyzer/SKILL.md }加载成功后Agent 会获得该技能定义的核心工作流数据提取 → 财务比率计算 → 图表生成 → 深度分析 → 渲染报告。仓库中同类的可加载技能还包括csv-data-analysis、walmart-sales-analyzer、agent-browser等均位于 skills/ 目录。六、注意事项Notesload_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, recursiveTrue)递归扫描目录下所有**/SKILL.md并注册claude_skill/init.pySkillLoader支持从文件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 报告或页面八、最佳实践小结技能可复用才用技能当流程需要可重复、可标准化时为任务编写/选用技能并配合load_skill加载而不是让 Agent 每次自由发挥严格遵循技能指令加载后按技能定义的工具顺序与步骤执行优先使用技能要求的工具而非临场替代方案善用execute_skill_script_file技能内的 Python 脚本应通过该工具执行系统会自动处理脚本输出中的图片转存/images/URL 映射、ratio_data、auto_data等副作用无需load_skill参与报告类任务用html_interpreter收尾当技能产出网页或报告时用html_interpreter做最终渲染形成「加载技能 → 分析计算 → 渲染交付」的完整闭环理解加载与执行的边界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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DB-GPT load_skill 工具深度指南：按技能名与文件路径加载 SKILL.md 工作流
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_namestring要加载的技能名称应与SKILL.mdfrontmatter 中的name字段一致如financial-report-analyzer匹配时支持大小写不敏感回退file_pathstring技能文件路径通常指向技能包内的SKILL.md如skills/financial-report-analyzer/SKILL.md从源码看skill_tools.pyskill_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()会将其封装为PromptTemplateJinja2 格式、非严格模式见 claude_skill/init.py。3. 将加载的工作流内容返回给 Agentreturns 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 skillAgent 识别出任务场景与某个技能的定义域一致例如上传了财报 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-analyzerload_skill的标准调用如下{ skill_name: financial-report-analyzer, file_path: skills/financial-report-analyzer/SKILL.md }加载成功后Agent 会获得该技能定义的核心工作流数据提取 → 财务比率计算 → 图表生成 → 深度分析 → 渲染报告。仓库中同类的可加载技能还包括csv-data-analysis、walmart-sales-analyzer、agent-browser等均位于 skills/ 目录。六、注意事项Notesload_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, recursiveTrue)递归扫描目录下所有**/SKILL.md并注册claude_skill/init.pySkillLoader支持从文件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 报告或页面八、最佳实践小结技能可复用才用技能当流程需要可重复、可标准化时为任务编写/选用技能并配合load_skill加载而不是让 Agent 每次自由发挥严格遵循技能指令加载后按技能定义的工具顺序与步骤执行优先使用技能要求的工具而非临场替代方案善用execute_skill_script_file技能内的 Python 脚本应通过该工具执行系统会自动处理脚本输出中的图片转存/images/URL 映射、ratio_data、auto_data等副作用无需load_skill参与报告类任务用html_interpreter收尾当技能产出网页或报告时用html_interpreter做最终渲染形成「加载技能 → 分析计算 → 渲染交付」的完整闭环理解加载与执行的边界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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考