创建 Skill

POST /api/v1/cloud/skills

上传并创建一个新的 Skill 资源。Skill 内容必须以 .zip 压缩包形式上传，使用 multipart/form-data 编码。

请求头

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

请求体（multipart/form-data）

字段	类型	必选	说明
file	file	是	Skill 内容的 .zip 压缩包，最大 5 MB
name	string	否	为兼容保留，但 API 实际使用 SKILL.md frontmatter 中的 name
type	string	否	Skill 类型，可选值：custom、prebuilt（默认 custom）
description	string	否	为兼容保留，但 API 实际使用 SKILL.md frontmatter 中的 description
metadata	JSON string	否	自定义元数据，JSON 对象格式

zip 文件结构

压缩包根目录或第一层目录中必须包含 SKILL.md 文件。SKILL.md 必须以如下 YAML frontmatter 开头：

---
name: my-skill
description: Skill 描述
version: 1.0.0
---

# Skill 标题

## Steps
1. 步骤一
2. 步骤二

zip 条目的路径分隔符可以是 /，也可以是 Windows 风格的 \；服务端查找 SKILL.md 时会自动归一化。

示例请求

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

# My Custom Skill

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

## Verification
确认操作完成。
EOF

# 打包为 zip
cd my-skill && zip ../my-skill.zip SKILL.md && cd ..

# 上传创建
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "name=my-custom-skill" \
  -F "type=custom" \
  -F 'metadata={"team":"docs"}' \
  -F "description=自定义 Skill 示例" \
  -F "file=@my-skill.zip"

示例响应

HTTP 201 Created

{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "my-custom-skill",
  "description": "自定义 Skill 示例",
  "source": "custom",
  "latest_version": "1",
  "metadata": {
    "team": "docs"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}

响应字段

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

错误码

HTTP	type	触发条件
400	invalid_request_error	非 multipart 请求：Invalid multipart form or request too large.
400	invalid_request_error	缺少 file 字段：Field 'file' is required.
400	invalid_request_error	非 zip 格式：Only .zip files are accepted.
401	authentication_error	缺少或无效的认证令牌

注意事项

• 允许创建同名 Skill（系统不强制名称唯一）

• name 和 description 始终从 SKILL.md frontmatter 中读取；form 中的同名字段不会覆盖压缩包内容

• Skill 名称最多 64 字符，只能包含小写字母、数字、连字符（-）和下划线（_），并且必须以字母或数字开头

• 支持 Windows 环境创建的 zip；路径中的反斜杠会被自动归一化

• 初始版本号为 1

• 不支持 JSON Content-Type，必须使用 multipart/form-data

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