Skip to main content

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.

Skills are uploaded as ZIP packages. The root directory of the ZIP must contain a SKILL.md file.

SKILL.md Authoring Spec

A SKILL.md file has two parts: YAML front matter and a Markdown body. The front matter is wrapped in --- and declares the skill name and description, which agents use to decide when to invoke the skill. The body contains the instructions and is loaded only after the skill triggers. 
---
name: my-custom-skill
description: "What the skill does, including trigger conditions, applicable scenarios, and out-of-scope scenarios."
---

Write the skill instructions here.
Review fails if the front matter is missing, is not wrapped in ---, or contains YAML syntax errors.
Fields
FieldRequiredDescription
nameYesThe unique identifier of the skill. Use lowercase letters, digits, and hyphens only, up to 64 characters, such as data-cleaner or invoice-parser.
descriptionYesDescribes the trigger conditions and capabilities of the skill, and directly affects invocation accuracy. Up to 1024 characters. Cannot contain angle brackets.
Writing an effective description The quality of the description determines how accurately agents invoke the skill. Include the following:
  1. Applicable input types: The file formats or data types the skill handles.
  2. Supported operations: The specific operations the skill can perform.
  3. Trigger keywords: Words or phrasings in a conversation that should trigger the skill.
  4. Out-of-scope scenarios: Cases where the skill should not trigger, to avoid false invocations.

Uploading a Custom Skill

  1. Click Custom Skill.
  2. Select a local ZIP file (≤ 10 MB). 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 a 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 Upload New Skill Version 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.8-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

Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support