Skip to Content
Skilder
REST APISkills

Create a skill

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

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.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Request Body

application/json
  1. body
name*string

Skill name

Length1 <= length
description?string

Short description

Lengthlength <= 1024
instructions?string

Skill instructions (markdown)

slug?string

Slug, unique in the workspace. Creating with a slug that already exists returns that skill, or 409 (see the operation)

Length1 <= length

Response Body

An existing skill with the same slug (idempotent create)

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 POST 'https://app.skilder.ai/api/v1/skills' \  -H 'Content-Type: application/json' \  -d '{  "name": "Weekly report"}'
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"  }}