技能包规范

技能定义格式遵循 Agent Skills 开放标准。技能是纯指令型资产，即一份由 LLM 阅读并遵循的 Markdown 指引。Tool（function calling）的定义、注册与执行由应用层负责，对 DolphinX 透明。

1. 技能包结构

技能包为 ZIP 文件（解压后最大 30 MB），必须包含 SKILL.md 入口文件（位于根目录或唯一子目录下）：

my-skill/
 SKILL.md # 必须：YAML frontmatter + Markdown 指令体
 template.md # 可选：模板文件
 reference.md # 可选：参考文档
 scripts/ # 可选：脚本
 helper.py
 assets/ # 可选：资源文件

2. SKILL.md 格式

由 YAML frontmatter（--- 分隔）和 Markdown body 两部分组成：

---
name: search-database
version: 1.0.0
description: Search distributed tables
argument-hint: "SELECT fields FROM table WHERE condition"
category: database
displayName: Database Search
license: MIT
compatibility: ">=3.0.0"
disable-model-invocation: false
user-invocable: true
---
## Usage Guide
You can use this skill to query DolphinDB distributed tables.
### Parameters
- `$ARGUMENTS`: The SQL query to execute
### Context Variables
- `${SESSION_ID}`: Current session ID
- `${AGENT_ID}`: Current agent ID
- `${USER_ID}`: Current DolphinDB user ID

3. frontmatter 字段说明

标准字段（Agent Skills 开放标准定义）：


字段	类型	必填	说明
name	string	是	技能标识符，全局唯一。格式：`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`，≤64 字符。
description	string	是	技能描述，说明做什么、何时用（≤1024 字符）。注入技能目录供 LLM 判断是否需要该技能。
version	string	否	技能版本号（如 1.0.0）。
license	string	否	许可证信息。
compatibility	string	否	环境要求（≤500 字符）。
metadata	map	否	自定义键值对。

DolphinX 扩展字段（从 frontmatter 解析，存为独立列）：


字段	类型	默认值	说明
argument-hint	string	—	参数提示（如 `[query] [limit]`），在技能目录中展示。
disable-model-invocation	bool	false	为 true 时 LLM 不可自动发现该技能（不进入技能目录），但用户/应用仍可显式触发。
user-invocable	bool	true	为 true 时用户可通过命令直接调用该技能。
category	string	—	技能分类标签。
displayName	string	—	技能名称。

其余 frontmatter 字段（如 model、effort、allowed-tools 等）统一收入 metadata JSON，DolphinX 不为其建独立列。

4. 渐进式加载模型（Progressive Disclosure）


加载阶段	加载时机	内容	Token 开销
技能目录	默认注入上下文	name + description + argument-hint	每个技能约 50-100
技能详细指令	应用层显式加载时（例如通过 activeSkillNames 或自定义 tool / 逻辑）	SKILL.md 的完整 Markdown body	建议 < 5000
技能文件	应用层按需提取时（通过 `skill.files.get` / `skill.files.batchGet` 等原语）	包内的脚本、模板、参考文档等	不限

5. DolphinX 内置技能


技能或技能包名称	说明
dolphindb-backtest	用于基于回测插件生成回测脚本：让 DolphinX 直接从量化策略描述生成 DolphinDB 回测脚本。
dolphindb-coding-style	用于指导编写 DolphinDB 代码，包含以下技能： dolphindb-basic-syntax-programming：为 DolphinDB 基础语法、脚本骨架和初版代码生成提供规则集。 dolphindb-vectorization-programming：用于指导 DolphinDB 向量化编程。 dolphindb-functional-programming：用于指导 DolphinDB 函数式编程。 dolphindb-sql-programming：用于指导编写 DolphinDB SQL 语句。
dolphindb-data-import	用于指导 DolphinDB 数据导入，覆盖 CSV/TXT 文本文件导入、二进制文件导入、HDF5 插件导入、Parquet 插件导入、IOTDB 引擎导入等场景。
dolphindb-factor	用于因子生成，包含以下技能： dolphindb_daily_factor：用于日频数据的因子生成。 dolphindb_highfreq_factor：用于日内/高频数据的因子生成。 dolphindb_rag：用于强制要求 DolphinDB 相关问题时进行溯源。
dolphindb-ficc-pricing	用于构造债券/利率/外汇/商品期货期权/权益期权等 13 类资产的 instrument、利率曲线/波动率曲面/股息曲线，以及说明各专用 pricer 与 `instrumentPricer` 调用规范。
dolphindb-hfdataimport	用于导入高频历史行情数据，包含以下技能： dolphindb-csmar-import：用于导入 CSMAR 历史行情数据。 dolphindb-datayes-import：用于导入通联历史行情数据。
dolphindb-machinelearning	用于数据源发现、原始建模数据选择、字段角色推断、数据清洗、特征工程、分类、回归和聚类。
dolphindb-ops	用于 DolphinDB 故障诊断（OOM、慢查询、流延迟、磁盘满、复制异常、元数据损坏等）、备份恢复、安全配置、作业管理等运维场景。
dolphindb-orca-dstream	用于指导编写、审查和修复 DolphinDB Orca 声明式 DStream API 代码。
dolphindb-plot	用于指导生成折线图、柱形图、条形图、饼图、面积图、散点图和三维曲面图等可视化图形。
dolphindb-report-factor-replication	用于研报因子复现，覆盖候选因子提取、单因子逻辑抽取、字段审计与取数、MR/Execute 模式判定、DolphinDB 因子代码生成、内置指标复用、常见复现模式和未来数据泄露检查。
dolphindb-test	用于指导生成 DolphinDB 功能测试方案、测试场景文档和完整测试用例。
dolphindb-tushare-import	用于将 Tushare 数据导入 DolphinDB。
dolphindb-universal-financial-data	用于处理金融数据，包含以下技能： dolphindb-finance-dbtbcreate：用于在 DolphinDB 中为金融数据创建数据库和表。 dolphindb-finance-dataimport：用于将 CSV 文件导入到已存在的 DolphinDB 表中。