Skip to main content
PATCH
Update a skill set
Renames or redescribes the workspace skill set named by id (its setId). Send a new name, a new description, or both. A builtin set’s name and description are read-only; its membership is not (see Add a skill to a skill set).

Authority and retries

Requires skills:manage at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted skills:manage only at an org unit is refused with 403 and nothing is written. A Forge agent can never hold skills:manage. MCP clients reach this operation through forge_call_operation. Send an Idempotency-Key to make a retry safe. The same key and the same body within 24 hours return the recorded 200 only while you still hold skills:manage at the platform scope; otherwise the answer is 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

setId
string
required

The skill set's id (its setId), as listSkillSets returns it

Minimum string length: 1

Body

application/json

The workspace skill set's id and a new name or description. A builtin set's metadata is read-only.

name
string

The set's display name (1-120 characters)

Required string length: 1 - 120
description
string

The new description

Maximum string length: 2000

Response

Update a skill set

data
object
required

A skill set by its id (setId), with each member's skill: its name and status, or name: null with status: "missing" when the skill no longer exists ("unresolved" past a list's read budget).

meta
object
required