Skip to main content
POST
Python SDK

Authorizations

Authorization
string
header
required

Enter your API key (e.g. dai_sk_test_key_001)

Headers

Authorization
string
X-Workspace-Id
string | null
X-Idempotency-Key
string | null

Cookies

decimal_session
string | null

Body

application/json

Validated request for POST /skills.

Uses relaxed name validation (allows underscores, dots, up to 200 chars).

name
string
required

URL-safe slug. Lowercase alphanumeric with hyphens/underscores/dots.

Required string length: 1 - 200
Example:

"search-flights"

description
string
required

Short one-line description shown in the skill registry.

Required string length: 1 - 1024
Example:

"Search available flights given origin, destination, and dates."

display_name
string | null

Human registry title shown instead of the slug name. Optional — the registry humanizes the slug when omitted.

Maximum string length: 200
Example:

"Search Flights"

body_markdown
string | null

Full SKILL.md body. At least 50 characters of substantive content.

Minimum string length: 1
body
string | null

Alias for body_markdown — accepted for backwards compatibility.

Minimum string length: 1
visibility
string
default:org

One of: org, workspace, personal. Public listing is not settable here — use POST /skills/{name}/publish.

Example:

"org"

stability
string
default:stable

One of: stable, experimental, deprecated.

Example:

"stable"

offer_scope
string | null

Which agents get this skill. 'restricted' (the default): only agents you add it to (POST /agents/{name}/skills/{skill_id}, or agent_name here). 'workspace': every agent in the org. A deleted skill's name created again gets the same. (Until 2026-10-25 an API key that left it out got 'workspace', and a re-created name kept its previous scope.)

Example:

"restricted"

agent_name
string | null

Also add the new skill to this agent (the dashboard sends it when you create a skill from an agent's page). Implies offer_scope='restricted' unless you say otherwise, and records a new config version for that agent.

Maximum string length: 255
Example:

"support-agent"

category
string | null

Optional grouping label, e.g. 'tools', 'policies', 'workflows'.

Maximum string length: 100
Example:

"tools"

skill_type
string | null

Taxonomy class: capability or preference. Defaults to the frontmatter skill-type: when omitted (legacy model-gap/proprietary/convention labels still accepted).

Example:

"preference"

skill_scope
string | null

Knowledge scope: public or private. Pairs with skill_type; defaults to the frontmatter skill-scope: when omitted (or the scope a legacy skill-type implies).

Example:

"public"

invocation_mode
string | null

Who may fire the skill: model, user, or any. Defaults to the frontmatter invocation: when omitted, else 'model'.

Example:

"model"

trigger_phrases
string[] | null

Phrases that hint the skill should activate. Used by smart routing.

Example:
frontmatter
Frontmatter · object | null

Raw frontmatter dict parsed from the SKILL.md header.

change_summary
string | null

Optional message attached to the first version.

author
string | null

Optional label shown as the first version's author in its history (anyone can read it once the skill is published). Who made the version is recorded separately.

project_id
string | null

Scope the skill to a specific project.

workspace_id
string | null

Owning workspace ID. Defaults to the caller's current workspace.

Response

Successful Response

status
string
required
Allowed value: "ok"
skill_id
string
required

Stable ID, always prefixed 'sk_'

name
string
required
version
integer
required

Starts at 1; increments on each body change

offer_scope
string
default:workspace

Which agents get the skill, as stored: 'restricted' (only agents you add it to) or 'workspace' (every agent).

added_to_agent
string | null

The agent the new skill was added to, when agent_name was sent.