Update a skill (into its draft)
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
skillId*stringSkill id
1 <= lengthapplication/json- body
name?stringNew skill name
1 <= lengthdescription?stringNew short description
length <= 1024instructions?stringNew skill instructions (markdown), replacing the current ones
ownerId?stringTransfer ownership (owner-scoped; the transfer publishes with the draft)
1 <= lengthdisabled?booleanOperational flag, applied to the published state directly
The skill as the caller now sees it (draft representation while their draft is open)
application/json- response
A skill, as its published state or as its open draft (see state).
id*stringSkill id
slug*|Workspace-unique slug, when one was given at creation
name*stringSkill name
description*|Short description
instructions*|Skill instructions (markdown)
disabled*booleanOperational 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*stringWhich representation this is: the published state, or the open draft
"published""draft"draft*|The open draft, on both representations; null when no draft is open
curl -X PATCH 'https://app.skilder.ai/api/v1/skills/0x1a2b' \ -H 'Content-Type: application/json' \ -d '{}'{ "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" }}Read one skill GET
Any workspace role may read; a key needs `read:skills`. Returns the published state by default. `?state=draft` returns the open draft: 404 when no draft is open, 409 when another user holds it, unless the caller is an admin or the skill’s owner and the key has `publish:skills` (draft content is otherwise visible only to its author), 403 when the caller is a Member, whose role reads published skills only.
Delete a skill DELETE
Cascade-deletes the skill with its related resources and version history. Irreversible. Owner-scoped: an admin may delete any skill, a contributor only their own; a key needs `write:skills`.

