创建技能 API：POST /skills-大模型服务平台百炼(Model Studio)-阿里云帮助中心

从已上传的 zip 包创建技能。请求体仅含 file_id，name 与 description 由服务端从 SKILL.md 解析得到。新建技能进入 checking，扫描通过后变为 active。

前提

已完成 Endpoint 与鉴权配置，详见API 总览与认证。创建技能前需先用File上传 zip 包获得 file_id。zip 包根目录须包含 SKILL.md，声明技能名称与描述。

接口

POST /skills

请求体仅含 file_id，对应文件须为 .zip 且通过审核。name 与 description 由服务端从 zip 包内的 SKILL.md 解析得到。

请求示例

Bash

curl -X POST "$AGENTSTUDIO_URL/skills" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_xxx"}'

Python

skill = client.skills.create(file_id="file_xxx")
print(skill.id)

Java

Skill skill = client.skills().create(SkillCreateParam.builder()
    .fileId("file_xxx").build());
System.out.println(skill.getId());

响应示例

{
  "id": "skill_xxx",
  "type": "skill",
  "name": "pdf3.0",
  "description": "Use this skill whenever the user wants to do anything with PDF files...",
  "source": "customer",
  "status": "checking",
  "latest_version": "1.0",
  "created_at": "2026-06-16T07:56:03Z",
  "updated_at": "2026-06-16T07:56:03Z",
  "request_id": "xxx"
}

响应字段

字段	类型	说明
`id`	string	技能 ID，格式 `skill_xxx`
`type`	string	固定为 `skill`
`name` / `description`	string	从 zip 包内 `SKILL.md` 解析得到
`source`	string	来源：`customer`（自建）/ `official`（百炼官方）
`status`	string	扫描状态：`checking` / `active` / `rejected` / `deleted`，仅 `active` 可挂载
`latest_version`	string	最新版本号，挂载到智能体时不能锁定到 `latest`，必须指定具体版本号
`created_at` / `updated_at`	string	创建/最近更新时间，ISO 8601
`request_id`	string	本次请求的唯一标识

扫描状态

新建技能或上传新版本进入 checking 状态，扫描通过后变为 active 才可挂载到智能体；命中安全风险变为 rejected，不能挂载，可根据版本信息获取具体错误原因。删除后状态为 deleted。