Skip to main content

创建 Skill

上传 ZIP 包创建自定义 Skill,初始版本为 1.0。

接口

POST /api/v1/skills 使用 multipart/form-data 上传 ZIP 包,创建自定义 Skill。创建成功后初始版本为 1.0。 此接口只新增 Skill,不更新已有 Skill。为已有 Skill 上传新版本,使用创建版本。

请求参数

表单字段类型必填说明
filefile是Skill 包,必须为 .zip,大小不超过 50MB
display_namestring否展示名称;不传或为空白时取 SKILL.md 的 name
display_descriptionstring否展示描述;不传或为空白时取 SKILL.md 的 description
ZIP 包根目录须包含 SKILL.md,Front Matter 中须包含 name 和 description。

响应

返回 SkillDTO。新建后 latest_version 为 1.0。提交安全扫描后 status 为 checking;未产生扫描任务时为 active。
字段类型说明
idstringSkill 唯一标识
display_namestring展示名称
display_descriptionstring展示描述
sourcestring固定为 customer
statusstringchecking 或 active
latest_versionstring最新版本号
classificationstring / null固定为 null,自定义 Skill 无分类
meta_infoobject / null固定为 null,自定义 Skill 无元信息
created_atstring创建时间
updated_atstring更新时间

示例

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/skills" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F "file=@./pdf-skill.zip" \
  -F "display_name=pdf3.0" \
  -F "display_description=PDF 处理技能"
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "id": "skill_NWVhN2MyM2MyZjA3xxxxxxxxxxxx",
    "display_name": "pdf3.0",
    "display_description": "PDF 处理技能",
    "source": "customer",
    "status": "checking",
    "latest_version": "1.0",
    "classification": null,
    "meta_info": null,
    "created_at": "2026-06-16T07:56:03Z",
    "updated_at": "2026-06-16T07:56:03Z"
  },
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

错误

HTTP 状态码error_code说明
401WORKSPACE_ID_ILLEGAL身份信息缺失或无效
400SKILL_FILE_IS_NULL未上传 file 或文件为空
400SKILL_FILE_FORMATER_ERROR文件扩展名不是 .zip,或文件头不是 ZIP 格式
400SKILL_PACKAGE_TOO_LARGEZIP 包超过 50MB
400INVALID_PARAMETERmultipart 请求格式错误
500SKILL_FILE_FORMATER_ERROR缺少 SKILL.md,或 Front Matter 缺少 name 或 description
500SKILL_NAME_OFFICIAL_DUPLICATESKILL.md 的 name 与官方 Skill 重名
500SKILL_NAME_CUSTOMER_DUPLICATESKILL.md 的 name 与当前空间的自定义 Skill 重名
500SKILL_PACKAGE_TOO_LARGEZIP 解压后累计大小超过 100MB
完整错误码见Skill API 错误码。