Update a skill

Update a skill’s metadata or content.

PUT /api/v1/cloud/skills/{skill_id}

Updates the metadata or content of the specified skill. Only JSON request bodies are supported.

Path parameters

Parameter	Type	Required	Description
skill_id	string	Yes	Skill unique identifier

Headers

Header	Required	Description
Authorization	Yes	Bearer $QODER_PAT
Content-Type	Yes	application/json

Request body

Field	Type	Required	Description
name	string	No	New skill name. Maximum 64 characters; lowercase letters, digits, hyphens, and underscores only; must start with a letter or digit
description	string	No	New skill description
content	string	No	New skill content. When content_encoding is "base64", this must be a base64-encoded zip archive containing SKILL.md; otherwise it is stored as plain text
content_encoding	string	No	Set to "base64" when content is a base64-encoded zip archive
metadata	object	No	Custom metadata. Replaces the stored metadata object

Example request

curl -X PUT https://api.qoder.com/api/v1/cloud/skills/skill_019e3bba474b73cfaf19eae9b5f5e66d \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-skill-name",
    "description": "Updated skill description",
    "metadata": {"team":"docs","stage":"updated"}
  }'

Example response

HTTP 200 OK

{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "updated-skill-name",
  "description": "Updated skill description",
  "source": "custom",
  "latest_version": "1",
  "metadata": {
    "team": "docs",
    "stage": "updated"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:36:01.767469Z"
}

Response notes

• updated_at is refreshed to the operation time.
• latest_version increments when content is updated.
• latest_version is not incremented for metadata-only updates.
• Fields not included in the request body retain their previous values.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Used multipart instead of JSON: “Request body must be valid JSON.”
401	TOKEN_INVALID	Missing or invalid authentication token
404	not_found_error	Skill does not exist or is no longer accessible

Notes

• The PUT endpoint accepts only application/json Content-Type.
• For base64 zip content, the archive must contain SKILL.md at the root or one directory below the root.
• If base64 zip content includes SKILL.md frontmatter and name or description are omitted, the API uses the frontmatter values.

See Errors for the full error envelope.

Related

Agent Skills

Attach domain expertise to your agent.