创建 Skill

上传并创建一个新的 Skill 资源，内容必须以 zip 压缩包形式上传。

POST /v1/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/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",
  "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（系统不强制名称唯一）
• name 和 description 始终从 SKILL.md frontmatter 中读取；form 中的同名字段不会覆盖压缩包内容
• Skill 名称最多 64 字符，只能包含小写字母、数字、连字符（-）和下划线（_），并且必须以字母或数字开头
• 支持 Windows 环境创建的 zip；路径中的反斜杠会被自动归一化
• 初始版本号为 1
• 不支持 JSON Content-Type，必须使用 multipart/form-data

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

​

相关

Agent 技能

为 Agent 附加领域专业知识。