Create a skill version

POST /api/v1/cloud/skills/{skill_id}/versions Appends a new version to an existing skill. Each version is a complete content snapshot (not a delta). Use multipart/form-data encoding with the files field; the format and validation rules are identical to Create a skill.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	No	Set automatically by `curl -F` to `multipart/form-data`; do not specify manually

Path parameters

Parameter	Type	Required	Description
`skill_id`	string	Yes	Skill unique identifier

Request body (multipart/form-data)

Field	Type	Required	Description
`files`	file (repeatable)	Yes	Complete content of the new version: a single `.zip` archive or a bare file tree. See Skill package for the package rules

Example request

# Repackage after editing content (keep the top-level directory name equal to the skill name)
zip -r my-custom-skill-v2.zip my-custom-skill/

curl -X POST "https://api.qoder.com/api/v1/cloud/skills/skill_019e3bba474b73cfaf19eae9b5f5e66d/versions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-custom-skill-v2.zip"

Example response

HTTP 201 Created

{
  "id": "skillver_019e3bbb6a25768b9b50ca2f52aa4345",
  "type": "skill_version",
  "skill_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "version": "1759264410332875",
  "name": "my-custom-skill",
  "description": "Custom skill example (second revision)",
  "directory": "my-custom-skill",
  "created_at": "2026-05-19T10:12:07.332875Z"
}

Response fields

The response is a Skill version object.

Field	Type	Description
`id`	string	Version unique identifier
`type`	string	Always `"skill_version"`
`skill_id`	string	Owning Skill ID
`version`	string	Version identifier
`name`	string	`name` from this version's `SKILL.md` frontmatter
`description`	string	`description` from this version's `SKILL.md` frontmatter
`directory`	string	Skill directory name
`created_at`	string	Version creation time

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Invalid package structure, missing `SKILL.md` or invalid frontmatter, uncompressed content over 50 MB
400	`invalid_request_error`	New version's `name` does not match the skill's existing `name`
401	`TOKEN_INVALID`	Missing or invalid authentication token
404	`not_found_error`	Skill does not exist or has been deleted
413	`request_too_large_error`	Archive larger than 50 MB
429	`rate_limit_error`	Rate limit or quota exceeded

Notes

After the new version is created, the skill's latest_version points to it and updated_at is refreshed.

See Errors for the full error envelope.

Agent Skills

Attach domain expertise to your agent.

​Headers

​Path parameters

​Request body (multipart/form-data)

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related