Skill API 复用的响应与包结构。
Skill 对象
创建、查询、列表接口返回该结构（Skill 壳）。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Skill ID，前缀为 skill_ |
type | string | 固定值 "skill" |
display_title | string | 展示标题（≤255 字符，无唯一性限制，创建后不可改）。缺省值：zip 上传时 = zip 文件名去 .zip 后缀；裸文件树时 = SKILL.md 的 name |
source | string | 可选值：custom、qoder |
latest_version | string | null | 最新版本号，epoch 微秒字符串（如 "1759178010641129"）；所有版本均被删除时为 null |
metadata | object | 与 Skill 一起存储的自定义元数据对象；省略时为 {} |
created_at | string | 创建时间（ISO 8601，微秒精度，如 2026-05-18T15:35:24.248164Z） |
updated_at | string | 最后更新时间（ISO 8601，微秒精度）；随版本增删刷新 |
description | string | ⚠️ 已废弃：Skill 描述（替代：版本对象上的 description） |
content | string | ⚠️ 已废弃：base64 编码内容，仅 include_content=true 时返回（替代：GET /skills/{skill_id}/versions/{version}/content） |
content_encoding | string | ⚠️ 已废弃：与 content 一起返回，值为 base64（替代：同上） |
Skill version 对象
创建版本、获取版本、列表版本接口返回该结构。每个版本是不可变的完整内容快照。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 版本 ID |
type | string | 固定值 "skill_version" |
skill_id | string | 所属 Skill 的 ID |
version | string | 版本号，创建时刻的 epoch 微秒字符串（如 "1759178010641129"） |
name | string | 该版本 SKILL.md frontmatter 的 name；跨版本必须一致 |
description | string | 该版本 SKILL.md frontmatter 的 description |
directory | string | 沙箱安装目录名，恒等于 name |
created_at | string | 版本创建时间（ISO 8601，微秒精度） |
content_size | integer | ⚠️ 已废弃：内容大小（字节）（替代：无，将移除） |
content_sha256 | string | ⚠️ 已废弃：SHA-256 摘要（替代：无，将移除） |
status | string | ⚠️ 已废弃：版本状态（替代：无，将移除） |
updated_at | string | ⚠️ 已废弃：最后更新时间（版本不可变，替代：created_at） |
Skill package
创建 Skill / 创建版本请求使用 multipart/form-data 的 files 字段上传 .zip 压缩包或裸文件树。
| 规则 | 说明 |
|---|---|
| 上传形式 | 单个 .zip 压缩包，或裸文件树（多个 files part，filename 携带相对路径） |
| 大小限制 | 压缩包 ≤50 MB，且解压后总大小 ≤50 MB |
| 顶级目录 | 必须有唯一的顶级目录，且目录名必须等于 SKILL.md 的 name，否则 400 |
| 必需 manifest | 顶级目录内包含 SKILL.md，以 YAML frontmatter 开头 |
frontmatter name | 必填非空；≤64 字符；正则 ^[a-z0-9][a-z0-9_-]*$；同一 Skill 的所有版本必须一致 |
frontmatter description | 必填非空；≤5120 字符 |
| frontmatter 解析 | 严格 YAML 优先，失败时宽松回退（逐行提取顶级 name:/description:，其他键忽略）；值中包含 ': ' 时建议加引号 |