Criar uma Skill - Qoder CN Series: Central de Documentação do Alibaba Cloud

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
Authorization	Sim	Bearer PAT — consulte Authorization: Bearer $QODER_PAT.
Content-Type	Não	O comando curl -F define este valor automaticamente como multipart/form-data; não é necessário especificá-lo manualmente.

Corpo da requisição (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
file	file	Sim	Conteúdo da Skill empacotado em um arquivo .zip. O arquivo deve ser um zip válido.
name	string	Não	Nome da Skill. Se omitido, o valor será lido do frontmatter do arquivo SKILL.md dentro do zip.
type	string	Não	Tipo da Skill. Pode ser custom ou prebuilt. O padrão é custom.
description	string	Não	Descrição da Skill.

Estrutura do arquivo zip

O arquivo compactado deve conter um arquivo SKILL.md no seguinte formato:

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

# Skill title

## Steps
1. Step one
2. Step two

Exemplo de requisição

# 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"

Exemplo de resposta

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

Campos da resposta

Campo	Tipo	Descrição
id	string	Identificador único da Skill, com o prefixo skill_.
type	string	Tipo do resource. Sempre "skill".
name	string	Nome da Skill.
description	string	Descrição da Skill.
skill_type	string	Tipo da Skill: custom ou prebuilt.
status	string	Status da Skill. Atualmente sempre active.
version	integer	Número da versão atual, começando em 1.
content_size	integer	Tamanho do conteúdo zip em bytes.
content_sha256	string	Hash SHA-256 do conteúdo zip.
metadata	object	Metadados definidos pelo usuário.
created_at	string	Timestamp de criação (ISO 8601).
updated_at	string	Timestamp da última atualização (ISO 8601).

Erros

HTTP	Tipo	Causa
400	invalid_request_error	A requisição não é multipart ou o corpo é muito grande: Invalid multipart form or request too large.
400	invalid_request_error	O campo file está ausente: Field 'file' is required.
400	invalid_request_error	O arquivo enviado não é um zip: Only .zip files are accepted.
401	authentication_error	Token de autenticação ausente ou inválido.

Observações

Os nomes das Skills não precisam ser exclusivos — é possível criar várias Skills com o mesmo nome.
Caso o campo name não seja enviado no formulário, o sistema lerá o valor do frontmatter do SKILL.md dentro do arquivo compactado.
Se o campo description não for enviado no formulário, o valor será obtido do frontmatter do SKILL.md no arquivo compactado.
Quando name ou description estiverem presentes tanto no formulário quanto no frontmatter do SKILL.md, o valor do frontmatter prevalece.
A versão inicial é 1.
O Content-Type JSON não é aceito — use obrigatoriamente multipart/form-data.

Para consultar o envelope completo de erros, veja Erros.