Agent Skills

Types

Skills are organized into two tabs:

• Marketplace: Official ready-to-use skills, such as PDF / Word / Excel / PowerPoint processing, and bailian-cli.

• Custom: Your own skills uploaded as a zip package (up to 10 MB). The root directory of the zip must contain a SKILL.md file that declares the skill name and description in YAML format. The agent decides when to invoke the skill based on the description.

Upload a custom skill

1. On the Custom tab, click Custom Skill.

2. Select a local zip package (up to 10 MB; the root directory must contain SKILL.md). After submission, the system automatically reviews the content and the skill enters the checking state. If the review passes, it becomes active and can be attached to an agent. If the review fails, it becomes rejected and cannot be attached.

When uploading via API, first call the file upload endpoint to obtain a file_id, then pass it to the create endpoint. For complete parameters and response fields, see Create a skill.

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/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());

Version management

You can upload a new version on the skill details page. When attaching to an agent, you must specify an exact version number. Uploading a new version does not affect agents that already have the previous version attached.

When uploading a new version via API, you also need to obtain a file_id first. The version number is automatically generated by the server. For complete parameters and response fields, see Upload New Skill Version.

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/skills/skill_xxx/versions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_xxx"}'

sv = client.skills.versions.create("skill_xxx", file_id="file_xxx")
print(sv.version)

SkillVersion sv = client.skills().createVersion("skill_xxx",
    SkillCreateParam.builder().fileId("file_xxx").build());
System.out.println(sv.getVersion());

Attach to an agent

In the agent editing page, click Add Skill in the Skills section, select a skill from the dropdown list, and specify a version. When creating or updating an agent via API, specify the skill ID and version in the skills field. For details, see Create Agent.

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/agents" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "model": {"id": "qwen3-max"},
    "skills": [
      {"type": "customer", "skill_id": "skill_xxx", "version": "1.0"}
    ]
  }'

agent = client.agents.create(
    name="my-agent",
    model="qwen3-max",
    skills=[
        {"type": "customer", "skill_id": "skill_xxx", "version": "1.0"},
    ],
)
print(agent.id)

Agent agent = client.agents().create(AgentCreateParam.builder()
    .name("my-agent")
    .model("qwen3-max")
    .skills(List.of(SkillConfig.builder()
        .type("customer")
        .skillId("skill_xxx")
        .version("1.0")
        .build()))
    .build());
System.out.println(agent.getId());

Deletion

Skills can only be deleted; archiving is not supported. Click Delete on the skill details page. The skill will be permanently deleted and cannot be recovered. Any references to the skill from agents will become invalid.

Delete a skill via API. This action is irreversible. For complete parameters and response fields, see Delete Skill.

curl -X DELETE "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/skills/skill_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

client.skills.delete("skill_xxx")

client.skills().delete("skill_xxx");