Skip to main content
Skills

Update a skill

(Deprecated) Update a skill's metadata or content.

PUT /api/v1/cloud/skills/{skill_id}
⚠️ This endpoint is deprecated and will be removed in a future release.
  • For content updates, use Create a skill version: POST /api/v1/cloud/skills/{skill_id}/versions. When content is updated through this endpoint, a new version is created internally rather than overwriting in place.
  • name cannot be changed: the skill name must stay consistent across all versions; sending a name different from the current one returns 400.
  • Patch updates to description / metadata still work, but are also scheduled for removal.
Updates the metadata or content of the specified skill. Only JSON request bodies are supported.
Creating new Skill content does not move a numeric Skill version pinned by an existing Session. Submit agent.skills through Update a session to advance that pin. Bindings with an omitted version or "latest" follow the newest Skill version at sandbox preparation time.

Path parameters

ParameterTypeRequiredDescription
skill_idstringYesSkill unique identifier

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json

Request body

FieldTypeRequiredDescription
namestringNo⚠️ Deprecated: renaming is no longer supported — a value different from the current name returns 400; the current value is a no-op (no replacement: name is immutable across versions)
descriptionstringNo⚠️ Deprecated: updates the skill shell description; scheduled for removal (the description is maintained per version via SKILL.md frontmatter instead)
contentstringNo⚠️ Deprecated: base64-encoded zip; internally converted into a new version. Plain-text content is no longer accepted and returns 400 (use POST /skills/{skill_id}/versions instead)
content_encodingstringNo⚠️ Deprecated: must be "base64" when content is a base64-encoded zip (same replacement as above)
metadataobjectNo⚠️ Deprecated: replaces the stored metadata object; scheduled for removal (no replacement yet)

Example request

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

Example response

HTTP 200 OK 
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "test-skill-api-doc",
  "description": "Updated skill description",
  "source": "custom",
  "latest_version": "1759178010641129",
  "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.
  • Updating content creates a new version; latest_version points to it.
  • Metadata-only updates do not create a new version.
  • Fields not included in the request body retain their previous values.

Errors

HTTPTypeTrigger
400invalid_request_errorUsed multipart instead of a JSON request body
400invalid_request_errorname differs from the current name (renaming is not allowed), or the SKILL.md name inside the base64 zip does not match the skill's existing name
400invalid_request_errorPlain-text content without content_encoding (no longer accepted; use a base64 zip or the versions endpoint)
401TOKEN_INVALIDMissing or invalid authentication token
404not_found_errorSkill does not exist or is no longer accessible
409conflict_errorOptimistic concurrency conflict
See Errors for the full error envelope.

Agent Skills

Attach domain expertise to your agent.
First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference