Skip to main content
POST
/
api
/
v1
/
skills
Create skill
curl --request POST \
  --url http://localhost:3001/api/v1/skills \
  --header 'Content-Type: application/json' \
  --cookie nut-session= \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "content": "<string>",
  "license": "<string>",
  "compatibility": "<string>",
  "allowedTools": "<string>",
  "metadata": {},
  "archiveUrl": "<string>"
}
'
{
  "success": true,
  "document": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "license": "<string>",
    "compatibility": "<string>",
    "allowedTools": "<string>",
    "metadata": {},
    "content": "<string>"
  }
}

Authorizations

​
nut-session
string
cookie
required

Session cookie authentication

Body

application/json
​
name
string
required

Skill name (kebab-case, 1-64 chars, lowercase letters, numbers, and hyphens only). Must match the directory name.

Maximum string length: 64
Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
​
description
string
required

Short description of the skill (max 1024 chars)

Maximum string length: 1024
​
content
string

Skill instructions in Markdown (body of SKILL.md)

​
license
string

License identifier (e.g. MIT, Apache-2.0)

​
compatibility
string

Compatibility requirements (e.g. "Requires git, node >= 18")

​
allowedTools
string

Space-delimited list of pre-approved tool names

​
metadata
object

Arbitrary key-value metadata map. Coconut-specific keys include color, mcpServers, focusAreas, contextPreferences.

​
archiveUrl
string<uri>

URL of a zip archive to download and extract into the skill directory. Must be hosted on a trusted registry domain.

Response

Skill created

​
success
boolean
​
document
object

A skill document following the Agent Skills specification. Stored as .nut/skills/<id>/SKILL.md with YAML frontmatter.