DB-GPT 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本文围绕 DB-GPT 的 Skills技能总览文档展开系统讲解 skill 的定义、目录结构、工作流与配套工具编排方式并结合仓库中skills/内置技能包与dbgpt-core、dbgpt-app的源码实现帮助读者完整理解“智能体如何按需发现、加载并执行一个技能包”以及如何在实际任务财报分析、CSV/Excel 数据分析中复用这一机制。什么是 skill在 DB-GPT 中skill 是一种可复用的能力包为智能体提供完成某类任务的结构化方式。本页对 skill 的定义参考了 Agent Skills 的开放描述skill 是一种轻量、自包含的能力包智能体可以按需发现、加载并执行。相比只依赖自由推理skill 为特定类型的工作提供了更稳定、更可重复的执行模式。结合 Agent Skills 的定义可以把 skill 理解为一种为智能体提供专业知识和工作流的轻量扩展格式一种经验与方法的打包形式而不只是事实、API 或 prompt一种渐进式暴露的能力单元先发现真正需要时再完整加载一个自包含的指令、脚本、模板和参考资料集合一种让智能体行为更稳定、可重复、具备领域感知的方式。在 DB-GPT 语境里skill 不只是“模型知道什么”而是一个打包好的工作流帮助智能体决定它要解决什么问题它应该调用哪些工具执行步骤应遵循怎样的顺序需要产出什么结果需要遵守哪些约束。这一点在仓库自带的技能包中可以得到直观印证以 财报分析技能的 SKILL.md 为例其正文不仅给出目标还逐条规定了“先执行哪个脚本、传入什么参数、系统会自动记录什么状态、最后如何渲染报告”本质上就是把一套经过验证的操作流程固化成了智能体可执行的指令。一个 skill 通常包含什么一个 DB-GPT skill 包通常包括名称nameSKILL.md中的说明与指令可选脚本可选模板可选静态资源或示例从本质上说skill 是一个包含SKILL.md的目录。这个文件定义元数据与执行指令告诉智能体如何完成某类任务。skill 还可以附带脚本、模板和参考资料标准目录形态如下my-skill/ ├── SKILL.md # Required: instructions metadata ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation loaded as needed └── assets/ # Optional: templates, output resources, static filesSKILL.md入口文件与元数据SKILL.md是 skill 的入口文件通常包含name、description等元数据智能体应遵循的工作流指令什么时候读取附加参考资料或使用打包资源的说明。从源码实现看SKILL.md的解析由核心包中的 Claude 风格技能解析器完成SkillLoader._load_from_markdown() 通过dbgpt.agent.claude_skill模块中的FileBasedSkill解析文件头部的 frontmatter 与正文指令再映射为 DB-GPT 内部的SkillMetadataname、description、version、author、skill_type、tags。也就是说SKILL.md头部声明的元数据字段与运行时加载的Skill对象字段是一一对应的。仓库中的真实技能文件可以直接看到这种格式。例如 csv-data-analysis 技能 的 frontmatter--- name: csv-data-analysis description: This skill should be used when users need to analyze CSV or Excel files, understand data patterns, generate statistical summaries, or create data visualizations. Trigger keywords include analyze CSV, analyze Excel, data analysis, ... ---description中甚至内嵌了触发关键词列表用于帮助智能体判断“当前任务是否适合加载本 skill”。再看 financial-report-analyzer 技能--- name: financial-report-analyzer description: 专门用于上市公司财报如年度报告、季度报告的深度分析。该技能能够自动提取 关键财务指标计算核心财务比率生成可视化图表并结合行业背景生成专业的财务分析报告。 ---两个文件都遵循同一模式元数据负责“被正确发现”正文负责“被正确执行”。各目录职责scripts / references / assets按照 DB-GPT 当前 skill-creator 的实践一个 skill 通常组织为一个小型、自包含的能力包部分必需作用SKILL.md是定义 skill 的身份信息与执行指令scripts/否存放可执行代码如 Python 或 shell 辅助脚本references/否存放按需加载进上下文的参考文档assets/否存放模板、字体、图标、样板文件或其他输出资源scripts/用于放置可执行辅助程序例如Python 数据处理脚本shell 脚本报告生成辅助代码skill 运行中需要的自动化代码。仓库内置的 walmart-sales-analyzer 技能 就是一个典型其scripts/目录包含了generate_time_series_trend.py、generate_correlation_heatmap.py、generate_html_report.py等一批确定性绘图与报告脚本把“生成图表”这类必须精确复现的步骤从 LLM 的自由发挥中剥离出来。references/用于保存不适合一直塞进SKILL.md的补充知识例如API 文档业务逻辑说明schema 定义工作流指南领域规范或策略文档。以财报技能为例references/financial_metrics.md 定义财务指标公式references/analysis_framework.md 定义分析结构与解读逻辑。这样既能保持SKILL.md精简又能在需要时为智能体提供更深的上下文——这正是“渐进式暴露”的落地方式。assets/用于存放更多面向输出而不是推理过程的资源例如HTML 模板图标与 logo字体前端样板文件报告资源。值得一提的是仓库内置技能实际普遍使用templates/目录来承载输出资源如 report_template.html与assets/职责相同详见 内置技能总览文档。为什么 skill 很重要在以下场景中skill 很有价值工作流需要标准化任务需要领域化推理报告或分析需要遵循固定模式希望智能体优先使用整理好的指令而不是完全临场发挥。从源码结构看这类价值对应着两个具体收益其一技能包让提示词、脚本、模板以文件形式沉淀在版本库中团队可以像评审代码一样评审、迭代工作流其二SkillMetadata中的required_tools、required_knowledge等字段见 skills/README.md 中对 Skill 组件的说明让“技能声明式依赖工具/知识库”成为可能运行时可以为智能体自动补齐所需能力。Skill 如何工作常见执行流程如下智能体识别当前任务适合某个 skill加载该 skill 的指令按照 skill 定义的工作流执行调用所需工具返回最终答案、报告或页面。加载环节load_skill 的源码级实现“加载 skill 指令”这一步在dbgpt-app中由专门的工具实现。load_skill 工具 的逻辑是智能体按skill_name调用load_skill工具从技能注册表get_registry()中查找匹配的技能找不到时还会做一次不区分大小写的模糊匹配命中后把技能实例写入react_state[matched]并把SKILL.md的正文指令写入react_state[skill_prompt]以分块形式返回技能名称、文件路径与完整指令文本instructions 或 prompt_template供模型在后续轮次中遵循。这一实现印证了总览文档中的描述skill 的指令是运行时按需注入的而不是预先全部塞进系统提示词——只有当智能体决定使用某个技能时对应SKILL.md的完整内容才会进入上下文。执行环节与内置工具协同skill 经常会编排多个内置执行工具一起工作load_skill→ 加载 skill 指令sql_query→ 按需获取结构化数据code_interpreter→ 计算指标、转换数据、生成图表shell_interpreter→ 在需要时执行 shell 命令html_interpreter→ 渲染最终报告或网页。此外仓库内置技能还广泛使用execute_skill_script_file来执行技能包内的脚本skill_namescript_file_nameargs它与shell_interpreter的区别在于该工具能自动处理脚本产物的后处理例如把生成的图片复制到静态目录并记录 URL 映射react_state[image_url_map]、把返回的 JSON 结果自动并入后续渲染react_state[ratio_data]。财报技能在其 SKILL.md 中明确要求“必须使用execute_skill_script_file不要用 shell_interpreter”原因就是上述自动合并机制。实际示例两个内置技能的完整工作流仓库在 skills/ 目录下内置了 5 个技能包agent-browser、csv-data-analysis、financial-report-analyzer、skill-creator、walmart-sales-analyzer完整映射关系见 内置技能总览。下面以两个数据类技能展开总览文档中的示例场景。财报分析总览文档中描述“一个财报分析 skill 可以定义如何检查上传的财报、如何计算指标并进行期间对比、如何生成图表与摘要、如何渲染最终 HTML 报告”。仓库中的 financial-report-analyzer 正是这一设想的生产级实现其目录结构为skills/financial-report-analyzer/ ├── SKILL.md ├── scripts/ │ ├── extract_financials.py │ ├── calculate_ratios.py │ ├── generate_charts.py │ └── fill_template.py ├── references/ │ ├── analysis_framework.md │ └── financial_metrics.md └── templates/ ├── report_template.html └── report_template.mdSKILL.md 将工作流固化为 6 步数据提取与结构化execute_skill_script_file执行extract_financials.py支持 PDF 与纯文本返回 JSON 结构化数据财务比率计算执行calculate_ratios.py自动计算毛利率、净利率、ROE、资产负债率等指标输出 30 个模板占位符键值系统自动保存到react_state[ratio_data]图表生成执行generate_charts.py生成 3 张图表指标对比柱状图、盈利能力条形图、资产结构环形图系统自动记录图片 URL 映射深度分析遵循references/analysis_framework.md由 LLM 撰写 7 段分析文本盈利能力、偿债风险、营运效率、现金流质量、优势列表、风险列表、综合评价渲染报告调用html_interpreter并指定template_pathdata中只传 7 段分析文本数据指标与图表 URL 由后端自动合并完成调用terminate返回简短摘要报告以卡片形式展示在侧边面板。这条流程恰好覆盖了总览文档强调的“稳定、可重复、领域感知”确定性计算交给脚本领域判断交给参考文档最终渲染交给模板LLM 只负责撰写分析文本。CSV / Excel 分析总览文档中“一个数据分析 skill 可以定义如何检查数据集、如何计算核心指标、如何可视化结果、如何把结果整理成可复用报告”对应仓库中的 csv-data-analysis 技能其配套资源为scripts/csv_analyzer.py、templates/report_template.html与references/reference.md见 CSV 数据分析技能文档。该技能的 SKILL.md 把工作流压缩为两步提取数据特征通过execute_skill_script_file运行csv_analyzer.py支持 .csv/.xlsx/.xls/.tsv脚本返回“统计摘要 标记数据块”两部分其中###KEY_START###...###KEY_END###形式的标记块由后端自动捕获注入模板模型无需手动搬运生成洞察并渲染报告模型基于统计摘要进行业务解读然后调用html_interpretertemplate_path指向csv-data-analysis/templates/report_template.html仅通过data参数填充内容占位符且明确要求“不要自行编写或修改任何 JavaScript 图表渲染代码”——模板已内置完整的 ECharts 渲染逻辑。这两个示例共同说明skill 的价值不在于替代 LLM 推理而在于把“哪些步骤必须精确、哪些步骤交给推理”划分清楚。源码中的 Skill 机制加载器、管理器与构建器除了文件式技能包dbgpt-core还内置了一套可编程的 Skill 基础设施核心文件位于 packages/dbgpt-core/src/dbgpt/agent/skill/模块说明见 skills/README.md部分说明Skill/SkillMetadata技能本体与元信息名称、描述、版本、类型、标签SkillLoader从 JSON/YAML 文件、SKILL.md或 Python 模块加载技能SkillBuilder以链式 API 编程式构建技能SkillManager技能的注册、按名/类型/版本检索从 loader.py 的load_skills_from_directory()可以看到加载器会递归扫描目录识别.json、.yaml、.yml及SKILL.md四类技能文件并分发到对应解析函数——这与仓库顶层skills/目录“每个子目录一个技能包”的组织方式正好对应。技能类型上README 中定义了Coding、DataAnalysis、WebSearch、KnowledgeQA、Chat、Custom六类未识别的类型会回落到Custom见 loader.py 中的类型转换逻辑。可编程侧的典型用法摘自 skills/README.mdfrom dbgpt.agent.skill import SkillBuilder, SkillType skill ( SkillBuilder(namemy_skill, descriptionMy awesome skill) .with_version(1.0.0) .with_author(Your Name) .with_skill_type(SkillType.Coding) .with_tags([coding, python]) .with_prompt_template( You are a coding assistant. Help users write clean, efficient code. ) .with_required_tool(python_interpreter) .build() )完整的 Agent 级使用示例可参考 examples/agents/skill_agent_example.py 与 examples/agents/claude_skill_example.pySKILL.md解析逻辑的测试用例见 tests/unit_tests/agent/test_claude_skill.py。最佳实践结合总览文档与仓库内置技能的实际约定整理出以下实践要点当工作流需要可重复时优先使用 skill严格遵循 skill 中定义的指令优先使用 skill 指定的工具而不是临时替代方案例如财报技能要求用execute_skill_script_file而非shell_interpreter就是为了保留后端对产物与状态的自动合并当 skill 产出网页或报告时优先使用html_interpreter做最终渲染并配合template_path模式让模型只填内容占位符、不碰模板中的渲染代码保持SKILL.md精简把公式定义、分析框架等深度知识放进references/按需加载把确定性计算放进scripts/把输出资源放进templates/或assets/。下一步想查看具体使用方式含财报分析、CSV 分析的界面级演示How to Use Skill想为项目编写自定义技能包How to Use Custom Skill想了解仓库内置的 5 个技能包各自的用途与资源Built-in Skills Overview【免费下载链接】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），仅供参考