Replace an Existing Skill
PUT
/skills-service/api/v2/skills/{skill_id}
SKILL.md file has been updated, reference files added or removed, or rebuilt the bundle from scratch.skill_id: The Ejento id of the skill you're replacing.file: a .zip archive or a single .md file containing the new version.name in the SKILL.md frontmatter must match the existing skill's name (resolved from skill_id).type (single_file/bundle) must match the existing skill — type is immutable.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.200 OK with the refreshed skill record, layout type, and new file listing.404 skill_not_found — no skill with this name exists. Use POST /v2/skills to create one first.400 skill_type_immutable — uploaded artifact's type differs from the existing skill.403 system_curated_immutable — skill is system-curated and cannot be mutated here.403 permission_denied — caller lacks permission to manage skills.400 skill_name_mismatch — frontmatter name doesn't match the name resolved from skill_id.Request
Path Params
Header Params
Body Params multipart/form-dataRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff --request PUT 'https:///skills-service/api/v2/skills/' \
--header 'Ocp-Apim-Subscription-Key: ' \
--header 'Authorization: Bearer ' \
--form 'file=""'Response Response Example
200 - Example 1
{
"data": {
"items": [
{
"file_path": "SKILL.md",
"size": 2048
},
{
"file_path": "references/v2.md",
"size": 1024
}
],
"meta": {
"file_count": 2,
"total_size_bytes": 3072
},
"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' replaced",
"success": true
}