Create a New Skill
POST
/skills-service/api/v2/skills
SKILL.md file (instructions only) or a bundle — a .zip containing SKILL.md plus any reference files your skill needs (templates, examples, helper scripts, etc.).file: a .zip archive or a single .md file.name field in SKILL.md frontmatter — you don't pass it separately.name, description, license, compatibility, metadata, allowed-tools. Any other field (including category) is rejected with 422.name: lowercase letters, digits, hyphens; ≤64 chars; no leading/trailing or consecutive hyphens (ASCII only).description: required, ≤1024 chars (Deep Agents truncates descriptions beyond 1024 chars).compatibility: optional, ≤500 chars..zip bundle must be ≤50 MB total, measured on both the compressed upload and the summed uncompressed entries.error.code = skill_frontmatter_invalid and a field_errors list.201 Created with the full skill record, layout type (single_file or bundle), and file listing.409 skill_name_taken — a skill with this name already exists. Use PUT /v2/skills/{skill_id} (with the existing skill's id) to replace it instead.400 — invalid .zip, missing or malformed frontmatter, or unsafe file paths.403 permission_denied — caller lacks permission to manage skills.Request
Header Params
Body Params multipart/form-dataRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff 'https:///skills-service/api/v2/skills' \
--header 'Ocp-Apim-Subscription-Key: ' \
--header 'Authorization: Bearer ' \
--form 'file=""'Response Response Example
201 - Example 1
{
"data": {
"items": [
{
"file_path": "SKILL.md",
"size": 1024
},
{
"file_path": "references/notes.md",
"size": 512
}
],
"meta": {
"file_count": 2,
"total_size_bytes": 1536
},
"skill": {
"category": "Engineering",
"created_by": "[email protected]",
"created_on": "2026-05-21T12:00:00Z",
"description": "My skill description.",
"id": 42,
"is_default": false,
"is_draft": false,
"is_enabled": true,
"modified_by": "[email protected]",
"modified_on": "2026-05-21T12:00:00Z",
"name": "my-skill",
"org_id": 7,
"type": "bundle"
},
"type": "bundle"
},
"message": "Skill 'my-skill' uploaded",
"success": true
}