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

​
请求头

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

​
请求体（multipart/form-data）

字段类型必选说明
filefile是Skill 内容的 .zip 压缩包（必须为 zip 格式）
namestring否Skill 名称（如不提供，从 zip 中的 SKILL.md frontmatter 读取）
typestring否Skill 类型，可选值：custom、prebuilt（默认 custom）
descriptionstring否Skill 描述

​
zip 文件结构

压缩包中应包含 SKILL.md 文件，格式如下： 
---
name: my-skill
description: Skill 描述
version: 1.0.0
---

# Skill 标题

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

​
示例请求

# 准备 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/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "name=my-custom-skill" \
  -F "type=custom" \
  -F "description=自定义 Skill 示例" \
  -F "file=@my-skill.zip"

​
示例响应

HTTP 201 Created 
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "name": "my-custom-skill",
  "description": "自定义 Skill 示例",
  "skill_type": "custom",
  "status": "active",
  "version": 1,
  "content_size": 309,
  "content_sha256": "f253cb7d35790025f85917c0c239422cff1de067d00278db8897c585a3f28d94",
  "metadata": {},
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}

​
响应字段

字段类型说明
idstringSkill 唯一标识符（skill_ 前缀）
typestring资源类型，固定为 "skill"
namestringSkill 名称
descriptionstringSkill 描述
skill_typestringSkill 类型：custom 或 prebuilt
statusstring状态：active
versioninteger当前版本号（从 1 开始）
content_sizeintegerzip 文件内容大小（字节）
content_sha256string内容的 SHA-256 哈希值
metadataobject自定义元数据
created_atstring创建时间（ISO 8601）
updated_atstring最后更新时间（ISO 8601）

​
错误码

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

​
注意事项

  • 允许创建同名 Skill（系统不强制名称唯一）
  • 如果 form 中不提供 name，系统会从 zip 内的 SKILL.md frontmatter 中读取
  • 如果 form 中不提供 description，系统会从 zip 内的 SKILL.md frontmatter 中读取
  • 如果两处都提供了 name 或 description，SKILL.md frontmatter 中的值优先
  • 初始版本号为 1
  • 不支持 JSON Content-Type，必须使用 multipart/form-data
完整错误信封说明详见 错误参考。