> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Skill

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

`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 开头：

```markdown theme={null}
---
name: my-skill
description: Skill 描述
version: 1.0.0
---

# Skill 标题

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

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

## 示例请求

```bash theme={null}
# 准备 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**

```json theme={null}
{
  "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`

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="Agent 技能" icon="sparkles" href="/zh/cloud-agents/skills">
    为 Agent 附加领域专业知识。
  </Card>
</CardGroup>