更新 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	否	自定义元数据，会替换当前存储的元数据对象

​

示例请求

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

{
  "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 值

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

​

相关

Agent 技能

为 Agent 附加领域专业知识。