创建 Skill 版本

描述

在现有 Skill 上追加一个新版本。版本一旦创建即不可变；version 由服务端生成为 16 位 Unix 微秒时间戳，成功后同时更新 Skill 的 latest_version 指向新版本。包内规范和上传字段规则与创建 Skill 保持一致，详见 Skill package。

路径

POST /api/v1/forward/skills/{id}/versions

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	是	`multipart/form-data`

路径参数

参数	类型	必选	说明
`id`	string	是	目标 Skill 的 ID。

表单字段

字段	类型	必选	说明
`files`	file	是	上传字段，可重复出现多次。支持两种形态： • 单个 `.zip` 包； • 裸文件树——每个 part 独立上传一个文件，`filename` 携带相对路径（如 `customer-reply/SKILL.md`、`customer-reply/scripts/run.sh`）。压缩包本身与解压后总大小均不超过 50 MB。

本接口只接受 files；未提供时返回 400。旧的单 file 字段在此不受支持。

包内约束详见 Skill package：包内必须有 SKILL.md，且有且仅有一个顶层目录、目录名与 SKILL.md 的 name 一致。

示例请求

单 zip 包：

curl -X POST "https://api.qoder.com/api/v1/forward/skills/skill_xxx/versions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@customer-reply.zip;type=application/zip"

裸文件树（files 字段重复）：

curl -X POST "https://api.qoder.com/api/v1/forward/skills/skill_xxx/versions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@customer-reply/SKILL.md;filename=customer-reply/SKILL.md" \
  -F "files=@customer-reply/scripts/run.sh;filename=customer-reply/scripts/run.sh"

示例响应

HTTP 201 Created

{
  "id": "skillver_xxx",
  "skill_id": "skill_xxx",
  "version": "1786973491821648",
  "name": "customer-reply",
  "description": "Customer reply skill",
  "directory": "customer-reply",
  "content_size": 2607,
  "content_sha256": "9de8ae3a296bc6198cd080f5ce31d523a34fd0a52e2e64365055fa79a0d3383d",
  "status": "active",
  "created_at": "2026-08-17T13:31:31.917881Z",
  "metadata": {}
}

响应字段

响应为 Skill 版本对象，version 为新分配的 16 位 Unix 微秒时间戳。创建成功后，Skill 的 latest_version 会同步指向该值——可通过查询 Skill 验证。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	multipart 解析失败、包结构不合法（缺 `SKILL.md`、多顶层目录、目录名与 `name` 不一致等）、参数缺失。
400	`skill_content_too_large`	压缩包本身或解压后总大小超过 50 MB。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	当前调用方无权访问该 Skill。
404	`not_found_error`	Skill 不存在或不可见。
413	`invalid_request_error`	请求体整体超过服务允许的大小上限。
429	`rate_limit_error`	当前调用方超过接口限流。
500/502/503	`api_error`	Forward 或依赖服务失败。

​描述

​路径

​请求头

​路径参数

​表单字段

​示例请求

​示例响应

​响应字段

​错误码

描述

路径

请求头

路径参数

表单字段

示例请求

示例响应

响应字段

错误码