创建 Skill

描述

上传 Skill 包并创建一个新的 Skill 记录。请求以 multipart/form-data 提交；创建成功后同时生成初始版本（latest_version 指向该版本）。

路径

POST /api/v1/forward/skills

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	是	`multipart/form-data`
`Idempotency-Key`	否	建议提供。相同 key 且规范化后的 `files` 指纹一致时可安全重试。

Form 字段

字段	类型	必选	说明
`files`	file	是*	推荐上传字段，可重复出现多次。支持两种形态： ① 单个 `.zip` 包； ② 裸文件树——每个 part 独立上传一个文件，`filename` 携带相对路径（如 `code-review/SKILL.md`、`code-review/scripts/run.sh`）。压缩包本身与解压后总大小均不超过 50 MB。
`metadata`	JSON string	否	调用方元数据对象，最多 15 个键；`created_by` 为保留字段，不可传入（传入返回 400）。
`icon_id`	string	否	Forward Resource icon 公开 ID。
`file`	file	是*	⚠️ 已弃用：单个 `.zip` 包，宽松包规则。命中时响应头返回 `Deprecation: true`。请迁移到 `files`。
`name`	string	否	⚠️ 已弃用：最终名称始终从上传包内 `SKILL.md` frontmatter 的 `name` 解析。字段保留仅为兼容，传入将被忽略。
`description`	string	否	⚠️ 已弃用：最终描述始终从 `SKILL.md` 解析。
`type`	string	否	⚠️ 已弃用：Skill 创建类型，可选 `custom`、`prebuilt`，默认 `custom`。`prebuilt` 会使响应 `source` 字段返回 `qoder`（其余为 `custom`）。

*files 与 file 二选一，至少提供其一；同时提供时以 files 为准。

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

示例请求

单 zip 包：

curl -X POST "https://api.qoder.com/api/v1/forward/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Idempotency-Key: create-skill-001" \
  -F "files=@skill.zip;type=application/zip" \
  -F "type=custom" \
  -F 'metadata={"source":"console"}' \
  -F "icon_id=pic_skill_default"

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

curl -X POST "https://api.qoder.com/api/v1/forward/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Idempotency-Key: create-skill-002" \
  -F "files=@code-review/SKILL.md;filename=code-review/SKILL.md" \
  -F "files=@code-review/scripts/run.sh;filename=code-review/scripts/run.sh"

示例响应

HTTP 201 Created

{
  "id": "skill_xxx",
  "type": "skill",
  "display_title": "code-review",
  "description": "Code review skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "metadata": {
    "source": "console"
  },
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T10:00:00Z",
  "identity_id": null,
  "icon_url": null,
  "binding_info": {
    "agent_template_count": 0
  }
}

响应字段

响应为 Skill 对象。同时会创建一个初始 Skill 版本对象，可通过列出 Skill 版本查看；latest_version 指向该版本的 16 位 Unix 微秒时间戳。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	multipart 解析失败、包结构不合法（缺 `SKILL.md`、多顶层目录、目录名与 `name` 不一致等）、`type` 非法、`metadata` 非法或包含保留键。
400	`invalid_request_error`	传入保留键 `created_by` 时，`message` 为 `metadata key "created_by" is reserved`，可据此定位到具体字段。
400	`skill_content_too_large`	压缩包本身或解压后总大小超过 50 MB。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	当前调用方无权访问该资源。
409	`conflict_error`	`Idempotency-Key` 对应不同请求指纹。
413	`invalid_request_error`	请求体整体超过服务允许的大小上限。
429	`rate_limit_error`	当前调用方超过接口限流。
500/502/503	`api_error`	Forward 或依赖服务失败。

​描述

​路径

​请求头

​Form 字段

​示例请求

​示例响应

​响应字段

​错误码

描述

路径

请求头

Form 字段

示例请求

示例响应

响应字段

错误码