文档中心

向量数据库VikingDB

技能（Skills）

add_skills-导入技能

概述

/api/v1/skills 接口用于向 OpenViking 导入一个技能（Skill）。技能是描述 Agent 能力的结构化文档，定义了 Agent 可执行的操作、触发条件和所需工具。导入后，技能将被解析并建立索引，供 Agent 在推理时检索和调用。

技能数据支持三种传入方式：通过 data 直接传入内容（字符串或结构化对象），或通过 temp_file_id 引用已上传的 SKILL.md 文件（或包含 SKILL.md 的 ZIP 包）。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口导入技能。如需上传本地 SKILL.md 文件，请先调用 "/api/v1/resources/temp_upload" 获取 temp_file_id。

请求接口

URI	/api/v1/skills
请求方法	POST
请求头	Content-Type: application/json
	Authorization: Bearer {api_key}

请求参数

参数	类型	必选	默认值	备注
data	string / object	条件必选	--	技能内容或结构化技能数据支持以下格式：字符串：SKILL.md 文件的原始文本内容。对象（技能格式）：包含 `name`、`description`、`instruction` 等字段的结构化技能定义，详见下方字段说明。对象（MCP 格式）：MCP 工具定义格式，系统会自动转换为技能格式。 `data` 与 `temp_file_id` 二者必须提供其中一个。 `data` 为字符串时，不会被当作文件路径解析，仅作为文本内容处理。
temp_file_id	string	条件必选	--	临时文件 ID 通过 `/api/v1/resources/temp_upload` 上传 SKILL.md 文件（或含 SKILL.md 的 ZIP 包）后获得。 `data` 与 `temp_file_id` 二者必须提供其中一个。 ZIP 包中需包含 `SKILL.md` 文件，其余文件会作为辅助文件一并导入。
timeout	float	否	null	等待超时时间（秒）仅当 `wait=true` 时生效。`null` 表示不限超时。
telemetry	bool / object	否	false	是否返回调用统计信息 `true` 或 `{"summary": true}`：在响应中包含操作耗时等汇总信息。

技能结构化对象（data 为 object 时）字段说明：
name 为存储和 API 寻址所需的唯一字段，必须是 1～64 位 ASCII 字母、数字、下划线或连字符；description、content、allowed_tools 和 tags 为常用字段。原始 SKILL.md 文本必须包含 YAML frontmatter，并同时包含 name 和 description。

字段	类型	说明
name	string	技能名称，唯一标识该技能，同名技能导入时会覆盖已有版本
description	string	技能描述，用于向量索引和检索
instruction	string	技能执行指令，描述 Agent 应如何执行该技能
allowed_tools	list	允许使用的工具列表
tags	list	标签列表，用于分类和过滤

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.status	处理状态，成功为 `"success"`
result.uri	技能的 URI，格式为 `viking://agent/<agent_id>/skills/<skill_name>`
result.root_uri	技能的正式访问地址，与 `result.uri` 相同
result.name	导入的技能名称
result.auxiliary_files	随技能一同导入的辅助文件数量（仅 ZIP 包导入时可能大于 0）
result.queue_status	后台处理进度，包含 `Semantic`（内容解析）和 `Embedding`（索引生成）两个子对象
result.queue_status.*.processed	该阶段已处理的条目数
result.queue_status.*.error_count	该阶段处理失败的条目数
result.queue_status.*.errors	错误详情列表
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述
telemetry	调用统计信息，例如接口耗时（仅当请求参数 `telemetry=true` 时返回）

常见错误码：

error.code	说明
UNAUTHENTICATED	缺少 API Key 或 API Key 无效
PERMISSION_DENIED	API Key 权限不足
INVALID_ARGUMENT	参数错误，例如 `data` 和 `temp_file_id` 均未提供
PROCESSING_ERROR	技能解析或索引处理失败，例如 SKILL.md 格式不正确

完整示例

示例一：直接传入结构化技能数据

curl -X POST https://xxx/api/v1/skills \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "search-and-summarize",
      "description": "搜索指定主题的资料并生成摘要",
      "instruction": "根据用户提供的关键词，检索相关资源，提取关键信息，生成结构化摘要报告。",
      "allowed_tools": ["search", "summarize"],
      "tags": ["search", "summary"]
    }
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "status": "success",
        "root_uri": "viking://agent/{agent_id}/skills/search-and-summarize",
        "uri": "viking://agent/{agent_id}/skills/search-and-summarize",
        "name": "search-and-summarize",
        "auxiliary_files": 0,
        "queue_status": {
            "Semantic": {
                "processed": 0,
                "requeue_count": 0,
                "error_count": 0,
                "errors": []
            },
            "Embedding": {
                "processed": 1,
                "requeue_count": 0,
                "error_count": 0,
                "errors": []
            }
        }
    }
}

示例二：上传 SKILL.md 文件并导入

# 第一步：上传 SKILL.md
curl -X POST https://xxx/api/v1/resources/temp_upload \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -F "file=@SKILL.md"

# 返回：{"status":"ok","result":{"temp_file_id":"upload_def456.md"}}

# 第二步：导入技能
curl -X POST https://xxx/api/v1/skills \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "temp_file_id": "upload_def456.md"
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "uri": "viking://agent/{agent_id}/skills/my-skill",
        "root_uri": "viking://agent/{agent_id}/skills/my-skill",
        "name": "my-skill",
        "auxiliary_files": 0
    }
}

执行失败返回（技能解析失败）：

HTTP/1.1 400
Content-Type: application/json

{
    "status": "error",
    "error": {
        "code": "PROCESSING_ERROR",
        "message": "Skill parse error: SKILL.md not found in uploaded archive"
    }
}

示例三：传入原始 SKILL.md 文本内容

curl -X POST https://xxx/api/v1/skills \
  -H "Authorization: Bearer {api_key}" \
  -H "X-OpenViking-Agent: {agent_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "---\nname: code-review\ndescription: 对代码进行审查并提出改进建议\n---\n\n## 执行步骤\n\n1. 读取代码文件\n2. 分析代码结构和潜在问题\n3. 生成审查报告"
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "uri": "viking://agent/{agent_id}/skills/code-review",
        "root_uri": "viking://agent/{agent_id}/skills/code-review",
        "name": "code-review",
        "auxiliary_files": 0
    }
}

参数、示例与排错补充

数值边界限制缺失：timeout 单位为秒，取值范围 [0, 300]；0 表示立即返回当前处理状态。
返回参数描述不完整：result.status 取值为 pending、processing、success 或 failed；异步返回时应继续根据任务状态轮询。
标识型参数缺少获取规则：agent_id 在 OpenViking 控制台的 Agent 接入页创建或选择 Agent 后复制；请求头 X-OpenViking-Agent 必须传该值，不能使用 Agent 名称代替。
返回示例与返回参数说明不符：返回字段 requeue_count 已按响应示例补充类型和层级；公共包装字段为 status:string、result:object|array|null、telemetry:object|null、error:object|null。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.14 11:52:08

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：直接传入结构化技能数据 #

示例二：上传 SKILL.md 文件并导入 #

示例三：传入原始 SKILL.md 文本内容 #

参数、示例与排错补充 #

示例一：直接传入结构化技能数据

示例二：上传 SKILL.md 文件并导入

示例三：传入原始 SKILL.md 文本内容

参数、示例与排错补充