Skip to main content
POST
Create 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.

Body

application/json
description
string
required

What an agent reads to decide when to use it

Required string length: 1 - 2000
instructions
string
required

What the agent follows when it uses it (Markdown), at most 256 KB

Minimum string length: 1
name
string
required

The skill's key is made from it, once

Required string length: 1 - 255
files
FileIn · object[]

Text files under references/

Maximum array length: 25
parent_addendum
string | null

Only with run_in_sub_agent: added to the calling agent's instructions

Maximum string length: 4000
run_in_sub_agent
boolean
default:false

Hand the skill to a sub-agent rather than follow it inline

Response

201 - 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