为已有 Skill 上传一个新的不可变版本快照。
POST /api/v1/cloud/skills/{skill_id}/versions
为已有 Skill 追加一个新版本。每个版本是完整内容快照（不是增量），使用 multipart/form-data 编码，内容通过 files 字段上传，格式与校验规则与 创建 Skill 完全相同。
请求头
| 头部 | 必选 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <PAT 或 SAT> |
Content-Type | 否 | 由 curl -F 自动设置为 multipart/form-data，无需手动指定 |
路径参数
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
skill_id | string | 是 | Skill 的唯一标识符 |
请求体（multipart/form-data）
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
files | file（可重复） | 是 | 新版本的完整内容：单个 .zip 压缩包或裸文件树。包结构规则见 Skill package |
示例请求
示例响应
HTTP 201 Created
响应字段
响应为 Skill version 对象。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 版本唯一标识符 |
type | string | 资源类型，固定为 "skill_version" |
skill_id | string | 所属 Skill 的 ID |
version | string | 版本号 |
name | string | 该版本 SKILL.md frontmatter 的 name |
description | string | 该版本 SKILL.md frontmatter 的 description |
directory | string | Skill 目录名 |
created_at | string | 版本创建时间 |
错误码
| HTTP | type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | 包结构非法、SKILL.md 缺失或 frontmatter 非法、解压后超过 50 MB |
| 400 | invalid_request_error | 新版本 name 与既有 name 不一致 |
| 401 | authentication_error | 缺少或无效的认证令牌 |
| 404 | not_found_error | Skill 不存在或已删除 |
| 413 | request_too_large_error | 压缩包超过 50 MB |
| 429 | rate_limit_error | 触发限流或配额限制 |
注意事项
- 新版本创建成功后，Skill 的
latest_version指向新版本，updated_at刷新