Copy

POST /api/v1/cloud/skills 上传并创建一个新的 Skill 资源，同时生成其首个不可变版本快照。使用 multipart/form-data 编码，内容通过 files 字段以 .zip 压缩包或裸文件树形式上传。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	否	由 `curl -F` 自动设置为 `multipart/form-data`，无需手动指定

请求体（multipart/form-data）

字段	类型	必选	说明
`files`	file（可重复）	是	Skill 内容。两种形式：① 单个 `.zip` 压缩包；② 裸文件树（多个 part，filename 携带相对路径）。两种形式都必须有唯一的顶级目录，且目录名等于 `SKILL.md` 中的 `name`
`display_title`	string	否	展示标题，无唯一性限制；缺省取自 zip 文件名或 `SKILL.md` 的 `name`。创建后不可修改
`metadata`	JSON string	否	自定义元数据，JSON 对象格式
`file`	file	否	⚠️ 已废弃：单 zip 上传的旧字段（替代：`files`）
`name`	string	否	⚠️ 已废弃：现自动映射为 `display_title`（替代：`display_title`；模型识别名始终来自 `SKILL.md` frontmatter 的 `name`）
`description`	string	否	⚠️ 已废弃：该字段无效，描述始终从 `SKILL.md` frontmatter 读取（无替代）
`type`	string	否	⚠️ 已废弃：`custom`/`prebuilt`，默认 `custom`；该字段将移除，届时一律为 `custom`

包结构规则

内容包必须有唯一的顶级目录（目录名等于 SKILL.md 的 name），顶级目录内包含以 YAML frontmatter 开头的 SKILL.md。完整规则（frontmatter 字段约束、大小限制、解析行为等）详见 Skill package。

示例请求

# 准备 skill 内容目录
mkdir my-custom-skill && cat > my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: 自定义 Skill 示例
---

# My Custom Skill

## Steps
1. 执行操作 A
2. 执行操作 B

## Verification
确认操作完成。
EOF

# 打包为 zip（保留顶级目录）
zip -r my-custom-skill.zip my-custom-skill/

# 上传创建
curl -X POST "https://api.qoder.com/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "display_title=My Custom Skill" \
  -F 'metadata={"team":"docs"}' \
  -F "files=@my-custom-skill.zip"

裸文件树上传（不打 zip，filename 携带相对路径）：

curl -X POST "https://api.qoder.com/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-custom-skill/SKILL.md;filename=my-custom-skill/SKILL.md" \
  -F "files=@my-custom-skill/templates/report.md;filename=my-custom-skill/templates/report.md"

示例响应

HTTP 201 Created

{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "My Custom Skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "metadata": {
    "team": "docs"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}

响应字段

响应为 Skill 对象。

字段	类型	说明
`id`	string	Skill 唯一标识符（`skill_` 前缀）
`type`	string	资源类型，固定为 `"skill"`
`display_title`	string	展示标题
`source`	string	Skill 来源：`custom` 或 `qoder`
`latest_version`	string	最新版本号
`metadata`	object	与 Skill 一起存储的自定义元数据对象；省略时为 `{}`
`created_at`	string	创建时间
`updated_at`	string	最后更新时间

错误码

HTTP	type	触发条件
400	`invalid_request_error`	非 multipart 请求、缺少 `files` 字段，或内容包不符合 Skill package 规则
401	`authentication_error`	缺少或无效的认证令牌
413	`request_too_large_error`	压缩包超过 50 MB
429	`rate_limit_error`	触发限流或配额限制

注意事项

Skill 的模型识别名始终为 SKILL.md frontmatter 中的 name，与 display_title 解耦
name 在该 Skill 的所有后续版本中必须保持一致（见创建 Skill 版本）

完整错误信封说明详见错误参考。

Agent 技能

为 Agent 附加领域专业知识。

​请求头

​请求体（multipart/form-data）

​包结构规则

​示例请求

​示例响应

​响应字段

​错误码

​注意事项

​相关