Skip to Content
Skilder
REST APISkills

Update a skill (into its draft)

In beta. This endpoint can still change in ways that break your integration. See the REST API overview.
PATCH
/skills/{skillId}

Requires the Contributor or Admin role; a key needs write:skills. Content edits land on the caller’s draft, which is opened automatically when none exists; the published state is untouched until an explicit publish. 409 when another user holds the open draft. disabled is operational, applied to the published state directly, and owner-scoped (the owner or an admin; a key needs publish:skills). ownerId transfers ownership (owner-scoped) as part of the draft.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Path Parameters

skillId*string

Skill id

Length1 <= length

Request Body

application/json
  1. body
name?string

New skill name

Length1 <= length
description?string

New short description

Lengthlength <= 1024
instructions?string

New skill instructions (markdown), replacing the current ones

ownerId?string

Transfer ownership (owner-scoped; the transfer publishes with the draft)

Length1 <= length
disabled?boolean

Operational flag, applied to the published state directly

Response Body

The skill as the caller now sees it (draft representation while their draft is open)

application/json
  1. response

A skill, as its published state or as its open draft (see state).

id*string

Skill id

slug*|

Workspace-unique slug, when one was given at creation

name*string

Skill name

description*|

Short description

instructions*|

Skill instructions (markdown)

disabled*boolean

Operational flag; a disabled skill is left out of the catalog agents see

ownerId*|

Owner user id; on a draft, the pending owner when the draft transfers ownership

createdAt*|

Creation time (ISO 8601)

updatedAt*|

Last change to the skill (ISO 8601), opening a draft included; publishedAt is the last publish

publishedAt*|

Last publish time (ISO 8601). Creation publishes the first version, so it is null only while a creation has not finished

state*string

Which representation this is: the published state, or the open draft

Value in"published""draft"
draft*|

The open draft, on both representations; null when no draft is open

Example Request
curl -X PATCH 'https://app.skilder.ai/api/v1/skills/0x1a2b' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "0x1a2b",  "slug": "weekly-report",  "name": "Weekly report",  "description": "Drafts the weekly status report from the team tracker.",  "instructions": "# Weekly report\n\nCollect the closed issues…",  "disabled": false,  "ownerId": "0x5e6f",  "createdAt": "2026-10-01T08:00:00.000Z",  "updatedAt": "2026-11-02T09:30:00.000Z",  "publishedAt": "2026-11-02T09:30:00.000Z",  "state": "published",  "draft": {    "authorId": "0x5e6f",    "authorName": "Ada Lovelace",    "openedAt": "2026-11-02T09:30:00.000Z"  }}