Skill 数据结构

Skill 对象

创建、查询、列表接口都会返回该结构；content 与 content_encoding 仅在查询 Skill 请求 include_content=true 时随响应返回。

字段	类型	说明
`id`	string	Skill ID，前缀为 `skill_`
`type`	string	固定值 `"skill"`
`display_title`	string	展示标题，可与 SKILL 内的 `name` 独立设置；同一用户下允许重复
`source`	string	Skill 来源，可选值：`custom`、`qoder`
`latest_version`	string \| null	最新版本标识。三态： • 版本化后为 Unix 微秒时间戳（如 `1759178010641129`）； • 过渡期未回填时为旧递增计数器（如 `2`）； • 所有版本被删除后为 `null`。不保证为可 `+1` 的递增数字，客户端不应据此推算下一版本
`metadata`	object	与 Skill 一起存储的自定义元数据对象；省略时为 `{}`。`created_by` 为 Forward 保留字段，调用方不可传入
`created_at`	string	创建时间，RFC 3339 格式
`updated_at`	string	最后更新时间，RFC 3339 格式
`identity_id`	string \| null	Forward 归属身份；PAT 创建时通常为 `null`
`icon_url`	string \| null	Forward 关联的 icon URL
`binding_info`	Binding info	绑定信息（Template 引用计数等）
`description`	string	Skill 描述。⚠️ 弃用中：新客户端请改从版本对象读取（见 Skill 版本对象），此字段仅为兼容保留
`content`	string	⚠️ 弃用中：`include_content=true` 时返回的 base64 编码 zip 内容；请改用版本内容下载接口
`content_encoding`	string	⚠️ 弃用中：与 `content` 成对返回，值固定为 `"base64"`；请改用版本内容下载接口

Skill 版本对象

列出 Skill 版本、查询 Skill 版本和创建 Skill 版本会返回该结构；版本内容通过下载 Skill 版本内容拉取；已有版本可通过删除 Skill 版本软删除。版本一经创建后不可变，是内容 + 元信息的独立快照。

字段	类型	说明
`id`	string	Skill Version ID，前缀为 `skillver_`
`skill_id`	string	所属 Skill 的 ID
`version`	string	版本号。新建版本返回 16 位 Unix 微秒时间戳；`latest_version` 三态与本字段值域一致
`name`	string	从上传包 `SKILL.md` frontmatter `name` 解析出的规范名
`description`	string	从上传包 `SKILL.md` frontmatter `description` 解析出的描述
`directory`	string	包内顶层目录名，等于 `name`
`content_size`	integer	版本包大小，单位 byte；最大 50 MB
`content_sha256`	string	版本包内容的 SHA-256 摘要（十六进制小写）
`status`	string	版本状态；当前始终为 `active`
`created_at`	string	创建时间，RFC 3339 格式
`metadata`	object	版本级元数据，暂固定为 `{}`

老版本编号兼容

GET /skills/{id}/versions/{version} 路径段接受两种版本号：

推荐：16 位 Unix 微秒时间戳（如 1759178010641129）。
兼容：过渡期的老递增计数器（如 "1"、"2"）仍可命中同一条版本记录。传入不存在的老编号返回 404。

字面量 latest 不受支持（返回 400 invalid_request_error）；请通过查询 Skill 读取 latest_version 字段拿到当前最新版本号，再拼路径。下载 Skill 版本内容与查询 Skill 版本都遵循这条规则。

Binding info

Forward 在 Skill 响应中携带的引用聚合。

字段	类型	说明
`agent_template_count`	integer	当前绑定该 Skill 的 Template 数量

Skill package 上传包规则

创建 Skill 和创建 Skill 版本使用 multipart/form-data 上传。推荐字段名 files；file 是保留兼容的老字段（⚠️ 已弃用，命中时响应头返回 Deprecation: true，请迁移到 files）。支持两种上传形态： ① 单 .zip 包 上传单个 files part，Content-Type: application/zip；包内文件结构见下文"包内结构示例"。 ② 裸文件树 files 字段可重复出现多次，每个 part 上传一个文件；part 的 filename 携带相对路径（如 code-review/SKILL.md、code-review/scripts/run.sh）。Forward 按 part 顺序无关规范化后打包，最终以 zip 形式存储。

规则	说明
上传字段	`files`（可重复 part）；`file`（单 zip 兼容，已弃用）
大小上限	压缩包本身与解压后总大小均不超过 50 MB；任一超过返回 `400 skill_content_too_large`。声明的解压大小与实际解压字节都会校验
包内 manifest	顶层目录下的 `SKILL.md`（必需，含 frontmatter `name`、`description`）
顶层目录	有且仅有一个；目录名必须与 `SKILL.md` 的 `name` 一致

包内结构示例

code-review/
├── SKILL              # 必需，含 frontmatter name/description
├── scripts/
│   └── run.sh
└── data/
    └── rules.json

列表分页字段

Skill 列表响应的分页字段与 Forward 其他列表接口一致。

字段	类型	说明
`data`	Skill 对象数组	当前页记录
`has_more`	boolean	是否还有下一页
`next_page`	string \| null	下一页向后游标（推荐使用）；`has_more=true` 时等于当前页 `last_id`，否则为 `null`
`first_id`	string \| null	当前页第一条记录 ID
`last_id`	string \| null	当前页最后一条记录 ID

请求侧的三种游标参数 page / after_id / before_id 互斥，同时提供多个返回 400；推荐使用 page，语义等价于 after_id。

Skill 版本列表分页字段

Skill 版本列表响应只使用推荐分页字段。

字段	类型	说明
`data`	Skill 版本对象数组	当前页记录
`has_more`	boolean	是否还有下一页
`next_page`	string	下一页向后游标；`has_more=false` 时省略

​Skill 对象

​Skill 版本对象

​老版本编号兼容

​Binding info

​Skill package 上传包规则

​包内结构示例

​列表分页字段

​Skill 版本列表分页字段