Skip to main content
PATCH
Change a skill

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer stfy_live_…. See Authentication for how to get one and which scopes it needs.

Path Parameters

key
string
required

The skill's key, from GET /v1/skills

Maximum string length: 64

Body

application/json

What is sent changes; what is left out is kept. A change to any field but enabled publishes a new version.

description
string
Required string length: 1 - 2000
enabled
boolean

Whether agents in this workspace load it

expected_version
integer

The version you read: a 409 if another is live. Without it, this change wins

Required range: x >= 1
files
FileIn · object[]

Replaces every file under references/; an empty list removes them. Other files are kept

Maximum array length: 25
instructions
string

At most 256 KB

Minimum string length: 1
name
string
Required string length: 1 - 255
parent_addendum
string | null

null clears it

Maximum string length: 4000
run_in_sub_agent
boolean

Turning it off clears parent_addendum

Response

200 - application/json

Successful Response

description
string
required

What an agent reads every turn to decide when to use it

enabled
boolean
required

Whether agents in this workspace load it

key
string
required

Fixed when the skill is made: the name agents call it by

name
string
required
source
enum<string>
required

statisfy (shipped by Statisfy: read-only, but each workspace can turn it off) or workspace (this workspace's own)

Available options:
statisfy,
workspace
status
enum<string>
required

The skill's own state. A Statisfy skill turned off by this workspace stays enabled here: see enabled

Available options:
enabled,
disabled,
archived
used_by
SkillAgent · object[] | null
required

Every agent it is set on (archived agents left out). Changing a skill in use needs 'skills:publish'. Null when a change saved but its agents could not be read: read the skill again

version
integer | null
required

The live version, what a change or POST /v1/skills/{key}/live sends back as expected_version. Null when storage could not be read