> ## 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 的元数据或内容。

`PUT /api/v1/cloud/skills/{skill_id}`

更新指定 Skill 的元数据或内容。仅支持 JSON 请求体。

## 请求头

| 头部              | 必选 | 说明                 |
| --------------- | -- | ------------------ |
| `Authorization` | 是  | `Bearer <PAT>`     |
| `Content-Type`  | 是  | `application/json` |

## 路径参数

| 参数         | 类型     | 必选 | 说明           |
| ---------- | ------ | -- | ------------ |
| `skill_id` | string | 是  | Skill 的唯一标识符 |

## 请求体

| 字段                 | 类型     | 必选 | 说明                                                                                       |
| ------------------ | ------ | -- | ---------------------------------------------------------------------------------------- |
| `name`             | string | 否  | 新的 Skill 名称，最多 64 字符；只能包含小写字母、数字、连字符和下划线，并且必须以字母或数字开头                                    |
| `description`      | string | 否  | 新的 Skill 描述                                                                              |
| `content`          | string | 否  | 新的 Skill 内容。`content_encoding` 为 `"base64"` 时必须是 base64 编码的 zip 包并包含 `SKILL.md`；否则按纯文本存储 |
| `content_encoding` | string | 否  | 当 `content` 是 base64 编码 zip 包时设为 `"base64"`                                              |
| `metadata`         | object | 否  | 自定义元数据，会替换当前存储的元数据对象                                                                     |

## 示例请求

```bash theme={null}
curl -X PUT "https://api.qoder.com/api/v1/cloud/skills/skill_019e3bba474b73cfaf19eae9b5f5e66d" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-skill-name",
    "description": "更新后的 Skill 描述",
    "metadata": {"team":"docs","stage":"updated"}
  }'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "updated-skill-name",
  "description": "更新后的 Skill 描述",
  "source": "custom",
  "latest_version": "1",
  "metadata": {
    "team": "docs",
    "stage": "updated"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:36:01.767469Z"
}
```

## 响应说明

* `updated_at` 字段会更新为操作时间
* 更新 `content` 时 `latest_version` 会递增
* 仅更新元数据时 `latest_version` 不会递增
* 未提供的字段保持原值不变

## 错误码

| HTTP | type                    | 触发条件                                                    |
| ---- | ----------------------- | ------------------------------------------------------- |
| 400  | `invalid_request_error` | 使用 multipart 而非 JSON：`Request body must be valid JSON.` |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                                              |
| 404  | `not_found_error`       | Skill 不存在或不再可访问                                         |

## 注意事项

* PUT 端点仅接受 `application/json` Content-Type
* base64 zip 内容必须在根目录或第一层目录中包含 `SKILL.md`
* 如果 base64 zip 中的 `SKILL.md` frontmatter 提供了 `name` 或 `description`，且请求体没有显式传对应字段，API 会使用 frontmatter 值

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

## 相关

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