Skip to main content
Build Agent

Agent Skills

Skills are packaged capabilities that encapsulate end-to-end workflows for common tasks. They are managed on the Skills page in the console and can be reused across multiple agents.

Types

Skills are organized into two tabs:
  • Marketplace: Official, ready-to-use skills provided by Alibaba Cloud—for example, PDF/Word/Excel/PowerPoint processing tools and bailian-cli.
  • Custom: User-uploaded skills in ZIP format (up to 10 MB). The root directory of the ZIP must contain a SKILL.md file, which declares the skill’s name and description in YAML format. Agents use this description to determine when to invoke the skill.

Uploading a Custom Skill

  1. In the Custom tab, click Custom Skill.
  2. Select a local ZIP file (≤ 10 MB; must include SKILL.md in its root directory). After submission, the system automatically validates the content and sets the skill status to checking. Upon successful validation, the status changes to active, and the skill becomes available for attachment to agents. If validation fails, the status becomes rejected, and the skill cannot be attached.
When uploading via API, first call the file upload endpoint to obtain a file_id, then pass it to the skill creation endpoint. For full parameter and response field details, see the Create Skill API. 
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"}'

Version Management

You can upload new versions directly from the skill detail page. When attaching a skill to an agent, you must specify an exact version number. Subsequent uploads of new versions do not affect agents already using earlier versions. To upload a new version via API, you must again first obtain a file_id. Version numbers are auto-generated by the server. For complete parameter and response field documentation, see the Skill API. 
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"}'

Attaching to an Agent

In the agent editing interface, go to the Skills section and click Add Skill, then select a skill and specify its version from the dropdown. When creating or updating an agent via API, specify the skill ID and version in the skills field. See the Create Agent API for details. 
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"}
    ]
  }'

Deletion

Skills support only deletion—not archival. On the skill detail page, click Delete to permanently remove the skill. This action is irreversible. Any references to the deleted skill in attached agents will become invalid. 
curl -X DELETE "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/skills/skill_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Next Steps

Overview
Build Agent
Environment
Sessions
Context
Event Subscriptions
Billing
Changelog