Skip to main content
POST
Add a skill to a skill set
Adds the skill named by skillId to the skill set named by id. meta.changed is false when it was already a member, and nothing is written. Builtin and workspace sets alike: operators own every set’s membership. The response is the set. A membership change reaches every agent holding the set at its next dispatch: each holder’s cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with 409 and nothing is written; revoke the set from some agents first.

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 skill set's id and the skillId to add or remove.

skillId
string
required

The skill's id (skillId)

Minimum string length: 1

Response

Add a skill to 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