Skip to main content
POST
Upload a skill from a Markdown file

Authorizations

Authorization
string
header
required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Query Parameters

overwrite
boolean
default:false

If false (default), returns 409 Conflict when the uploaded skill is referenced by an agent. If true, the skill is uploaded regardless.

externalId
string
required

CDF external ID for the skill's SKILL.md file. Leading and trailing whitespace is trimmed before validation. Must not start with the reserved prefix 'cdf-'. Must be between 1 and 128 characters inclusive, with no null character (U+0000).

Required string length: 1 - 128
Pattern: ^[^\x00]{1,128}$

Body

multipart/form-data
file
file
required

UTF-8 .md file in SKILL.md form: YAML frontmatter with name and description, then a Markdown body (text/markdown).

Response

Successful Response

items
SkillListResponseItem · object[]
required

Skills returned with full detail, including Markdown instruction content (e.g. create or fetch-by-id responses). For POST /skills, items match the request items order and count.

Last modified on October 6, 2026