Skip to content
Documentation

Upload a skill from a markdown file

POST
/api/v1/workspaces/{workspace_id}/skill_uploads
curl --request POST \
  --url https://example.com/%7B%7Bapp_url%7D/api/v1/workspaces/1/skill_uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@file

Creates a skill from an uploaded SKILL.md file. The name and description are read from the YAML frontmatter and the markdown body becomes the instructions.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspace_id
required
integer

Workspace ID

Request Body

Section titled “Request Body”
Media typemultipart/form-data
object
file
required
string format: binary

Responses

Section titled “Responses”

201

Section titled “201”

Successful

Media typeapplication/json
object
id
required
integer
name
required

Unique handle for the skill within the workspace. Lowercase letters, numbers and single hyphens only (agentskills.io name constraint).

string
description
required

Describes what the skill does and when to use it. Surfaced to the agent as part of the skills manifest.

string
instructions
required

The markdown body of the skill (the SKILL.md instructions).

string
attached_emails
required

Emails attached via email:<id> tokens in the body, resolved to their current id and name. Derived from the body; not set directly.

Array<object>
object
id
required
integer
name
required
string
ai_agents
required

Build agents that can access this skill.

Array<object>
object
id
required
integer
name
required
string
ai_reviewers
required

Review agents that can access this skill.

Array<object>
object
id
required
integer
name
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "id": 12345,
  "name": "brand-voice",
  "description": "Use when writing on-brand marketing copy for Acme.",
  "instructions": "# Brand voice\n\nWrite in a warm, concise tone. Never use exclamation marks.",
  "attached_emails": [
    {
      "id": 12345,
      "name": "Product Updates"
    }
  ],
  "ai_agents": [
    {
      "id": 12345,
      "name": "Marketing Agent"
    }
  ],
  "ai_reviewers": [
    {
      "id": 12345,
      "name": "Brand Reviewer"
    }
  ]
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
message
required
string
errors
required
object
key
additional properties
Array<string>
Example
{
  "errors": {
    "username": [
      "Username is required.",
      "Username must be unique."
    ],
    "email": [
      "Invalid email format."
    ]
  }
}