Read one skill
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
skillId*stringSkill id
1 <= lengthstate?stringWhich representation to read. draft returns the open draft when you hold it, or when you are an admin or the owner and the key may publish the resource
"published""published""draft"The requested representation
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 GET 'https://app.skilder.ai/api/v1/skills/0x1a2b'{ "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" }}Create a skill POST
Creates a published skill, owned by the caller. Requires the Contributor or Admin role; a key needs `write:skills`. With a `slug`, creation is idempotent: a duplicate returns the existing skill with 200. Its owner's retry finishes a creation that stopped part-way, with 201; 409 while it is still running, or when someone else's retry meets it or a draft is open on it. Parallel creations with one slug create one skill: the others meet it while it is running.
Update a skill (into its draft) PATCH
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.

