Create a skill

Prerequisites

Endpoint and authentication are configured. See Overview and authentication. Before creating a skill, upload the zip package via File to obtain a file_id. The zip's root directory must contain SKILL.md declaring the skill's name and description.

Endpoint

POST /skills

The request body contains only file_id; the corresponding file must be a .zip that has passed review. name and description are parsed by the server from SKILL.md inside the zip.

Request example

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

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

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

Response example

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

Scan status

A newly created skill or a newly uploaded version enters checking. It must reach active after passing the scan before it can be mounted to an agent. If a security risk is detected the status becomes rejected and the version cannot be mounted; query the version for the concrete error reason. After deletion the status is deleted.