创建 Skill-阿里云帮助中心

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

请求头

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

请求体（multipart/form-data）

字段	类型	必选	说明
`file`	file	是	Skill 内容的 `.zip` 压缩包（必须为 zip 格式）
`name`	string	否	Skill 名称（如不提供，从 zip 中的 `SKILL.md` frontmatter 读取）
`type`	string	否	Skill 类型，可选值：`custom`、`prebuilt`（默认 `custom`）
`description`	string	否	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.cn/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"
}

响应字段

字段	类型	说明
`id`	string	Skill 唯一标识符（`skill_` 前缀）
`type`	string	资源类型，固定为 `"skill"`
`name`	string	Skill 名称
`description`	string	Skill 描述
`skill_type`	string	Skill 类型：`custom` 或 `prebuilt`
`status`	string	状态：`active`
`version`	integer	当前版本号（从 1 开始）
`content_size`	integer	zip 文件内容大小（字节）
`content_sha256`	string	内容的 SHA-256 哈希值
`metadata`	object	自定义元数据
`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（系统不强制名称唯一）
如果 form 中不提供 name，系统会从 zip 内的 SKILL.md frontmatter 中读取
如果 form 中不提供 description，系统会从 zip 内的 SKILL.md frontmatter 中读取
如果两处都提供了 name 或 description，SKILL.md frontmatter 中的值优先
初始版本号为 1
不支持 JSON Content-Type，必须使用 multipart/form-data

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