Create a Skill - Qoder CN Series - Alibaba Cloud Documentation Center

Request headers

Header	Required	Description
`Authorization`	Yes	Bearer PAT — see `Authorization: Bearer $QODER_PAT`.
`Content-Type`	No	`curl -F` sets this automatically to `multipart/form-data`; no need to specify it manually.

Request body (multipart/form-data)

Field	Type	Required	Description
`file`	file	Yes	The Skill content packaged as a `.zip` archive. The file must be a valid zip.
`name`	string	No	Skill name. If omitted, the value is read from the `SKILL.md` frontmatter inside the zip.
`type`	string	No	Skill type. One of `custom` or `prebuilt`. Defaults to `custom`.
`description`	string	No	Skill description.

Zip archive layout

The archive must contain a SKILL.md file in the following format:

---
name: my-skill
description: Skill description
version: 1.0.0
---

# Skill title

## Steps
1. Step one
2. Step two

Example request

# Prepare the Skill content directory
mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: Custom Skill example
version: 1.0.0
---

# My Custom Skill

## Steps
1. Do action A
2. Do action B

## Verification
Confirm the actions complete successfully.
EOF

# Package the directory as a zip
cd my-skill && zip ../my-skill.zip SKILL.md && cd ..

# Upload and create the Skill
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "name=my-custom-skill" \
  -F "type=custom" \
  -F "description=Custom Skill example" \
  -F "file=@my-skill.zip"

Example response

HTTP 201 Created

{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "name": "my-custom-skill",
  "description": "Custom Skill example",
  "skill_type": "custom",
  "status": "active",
  "version": 1,
  "content_size": 309,
  "content_sha256": "f253cb7d35790025f85917c0c239422cff1de067d00278db8897c585a3f28d94",
  "metadata": {},
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}

Response fields

Field	Type	Description
`id`	string	Unique Skill identifier, prefixed with `skill_`.
`type`	string	Resource type. Always `"skill"`.
`name`	string	Skill name.
`description`	string	Skill description.
`skill_type`	string	Skill type: `custom` or `prebuilt`.
`status`	string	Skill status. Currently always `active`.
`version`	integer	Current version number, starting at 1.
`content_size`	integer	Zip content size in bytes.
`content_sha256`	string	SHA-256 hash of the zip content.
`metadata`	object	User-defined metadata.
`created_at`	string	Creation timestamp (ISO 8601).
`updated_at`	string	Last-updated timestamp (ISO 8601).

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Request is not multipart or the body is too large: `Invalid multipart form or request too large.`
400	`invalid_request_error`	The `file` field is missing: `Field 'file' is required.`
400	`invalid_request_error`	Uploaded file is not a zip: `Only .zip files are accepted.`
401	`authentication_error`	Missing or invalid authentication token.

Notes

Skill names are not required to be unique — you can create multiple Skills that share a name.
If name is not sent in the form, the value is read from the SKILL.md frontmatter inside the archive.
If description is not sent in the form, the value is read from the SKILL.md frontmatter inside the archive.
When name or description is present in both the form and the SKILL.md frontmatter, the frontmatter value wins.
The initial version is 1.
JSON Content-Type is not accepted — you must use multipart/form-data.

For the full error envelope, see Errors.