Skip to main content

Create a Skill

Creates a custom Skill from a ZIP package. The initial version is 1.0.

Endpoint

POST /api/v1/skills Uploads a ZIP package as multipart/form-data to create a custom Skill. The initial version is 1.0. This API only creates a new Skill. To upload a new version for an existing Skill, use Create a version.

Request parameters

Form fieldTypeRequiredDescription
filefileYesSkill package. Must be a .zip file no larger than 50MB
display_namestringNoDisplay name. If omitted or blank, the name in SKILL.md is used
display_descriptionstringNoDisplay description. If omitted or blank, the description in SKILL.md is used
The root directory of the ZIP package must contain SKILL.md, and the Front Matter must contain name and description.

Response

Returns a SkillDTO. After creation, latest_version is 1.0. After the security scan is submitted, status is checking. If no scan task is created, it is active.
FieldTypeDescription
idstringUnique Skill ID
display_namestringDisplay name
display_descriptionstringDisplay description
sourcestringAlways customer
statusstringchecking or active
latest_versionstringLatest version number
classificationstring / nullAlways null. Custom Skills have no classification
meta_infoobject / nullAlways null. Custom Skills have no metadata
created_atstringCreation time
updated_atstringUpdate time

Example

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 processing skill"
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "id": "skill_NWVhN2MyM2MyZjA3xxxxxxxxxxxx",
    "display_name": "pdf3.0",
    "display_description": "PDF processing skill",
    "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"
}

Errors

HTTP statuserror_codeDescription
401WORKSPACE_ID_ILLEGALIdentity information is missing or invalid
400SKILL_FILE_IS_NULLfile is not uploaded or the file is empty
400SKILL_FILE_FORMATER_ERRORThe file extension is not .zip, or the file header is not in ZIP format
400SKILL_PACKAGE_TOO_LARGEThe ZIP package exceeds 50MB
400INVALID_PARAMETERThe multipart request is malformed
500SKILL_FILE_FORMATER_ERRORSKILL.md is missing, or the Front Matter lacks name or description
500SKILL_NAME_OFFICIAL_DUPLICATEThe name in SKILL.md duplicates an official Skill
500SKILL_NAME_CUSTOMER_DUPLICATEThe name in SKILL.md duplicates a custom Skill in the current workspace
500SKILL_PACKAGE_TOO_LARGEThe uncompressed content exceeds 100MB
For the full list, see Skill API error codes.