Skip to main content
Skills

修改 Skill

Forward Skills API 接口说明。

⚠️ 已弃用：PUT /skills/{id} 是内容更新的旧路径，响应头会返回 Deprecation: true。请改用 创建 Skill 版本 追加不可变版本；本端点保留以兼容存量客户端。

描述

通过 PUT 修改 Skill 的展示信息或整体内容。技能名不可修改；传入 content 时会创建一个新的不可变版本（等价于追加版本），latest_version 指向新版本。

路径

PUT /api/v1/forward/skills/{id}

请求头

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

路径参数

参数类型必选说明
idstring是Skill ID。

请求体

字段类型必选说明
descriptionstring否新描述。
contentstring否新内容（zip 包内容）。压缩包本身与解压后总大小均不超过 50 MB，超过返回 400；请求体整体（含 base64 编码与 JSON 信封）上限约 67.7 MB，超过返回 413。
content_encodingstring否content 的编码。支持 base64、utf-8、utf8、plain、text；省略时按 UTF-8 文本处理。传入该字段时必须同时提供非空 content。
metadataobject否元数据对象，会替换当前 metadata（非合并）；传入时不能为 null，value 必须为 string。created_by 为保留字段，不可传入（传入返回 400）。
icon_idstring | null否更新或清空 Forward icon。
namestring否⚠️ 已弃用：技能名不可修改。传入必须与当前规范名完全一致，否则返回 400；一致时为空操作。

响应头

命中此端点时，响应头包含 Deprecation: true（不带 Sunset 具体日期）。

示例请求

curl -X PUT "https://api.qoder.com/api/v1/forward/skills/skill_xxx" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated customer reply skill",
    "content": "UEsDB...",
    "content_encoding": "base64",
    "metadata": {"source": "console"}
  }'

示例响应

HTTP 200 OK 
{
  "id": "skill_xxx",
  "type": "skill",
  "display_title": "customer-reply",
  "description": "Updated customer reply skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "metadata": {"source": "console"},
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T11:00:00Z",
  "identity_id": null,
  "icon_url": null,
  "binding_info": {"agent_template_count": 0}
}

响应字段

响应为 Skill 对象。

错误码

HTTPtype触发条件
400invalid_request_error请求体非法、name 与当前规范名不一致、content_encoding 未搭配 content 等。
400invalid_request_error传入保留键 created_by 时，message 为 metadata key "created_by" is reserved，可据此定位到具体字段。
400skill_content_too_largecontent 的压缩包本身或解压后总大小超过 50 MB。
401authentication_error缺少或无效的认证令牌。
403permission_error当前调用方无权修改该 Skill。
404not_found_errorSkill 不存在或不可见。
413invalid_request_error请求体整体超过约 67.7 MB。
429rate_limit_error当前调用方超过接口限流。
500/502/503api_errorForward 或依赖服务失败。
快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考
修改 Skill - Qoder