SKILL.md file, added or removed reference files, or rebuilt the bundle from scratch.name in the SKILL.md frontmatter must match the existing skill's name (resolved from skill_id).type, which never changes after creation:single_file skill (just a SKILL.md): upload a .md file, or a .zip that contains only SKILL.md.bundle skill (SKILL.md plus other files): upload a .zip/.skill that includes at least one file besides SKILL.md.skill_type_immutable.name, description, license, compatibility, metadata, allowed-tools. Any other field is rejected with 422.name: lowercase letters, digits, hyphens; ≤64 chars; no leading/trailing or consecutive hyphens (ASCII only).description: required, ≤1024 chars.compatibility: optional, ≤500 chars..zip/.skill bundle ≤50 MB on both the compressed upload and its summed uncompressed files (default limits). An upload over its limit is rejected with 413 http_413 while it is received, or with 400 http_400 once it is opened (e.g. a bundle that grows past the limit when unpacked).skill_frontmatter_invalid with a field_errors list.modified_on / modified_by now update on every successful replace, even when the description is unchanged..skill accepted as an alias for .zip bundle uploads.curl --location --globoff --request PUT 'https:///skills-service/api/v2/skills/' \
--header 'Ocp-Apim-Subscription-Key: ' \
--header 'Authorization: Bearer ' \
--form 'file="(a SKILL.md file, or a .zip or .skill bundle)"'{
"success": true,
"message": "Skill 'my-skill' replaced",
"data": {
"skill": {
"id": 42,
"name": "my-skill",
"description": "My skill description.",
"category": "Engineering",
"type": "bundle",
"org_id": 7,
"is_enabled": true,
"is_draft": false,
"is_default": false,
"created_by": "[email protected]",
"created_on": "2026-05-21T12:00:00Z",
"modified_by": "[email protected]",
"modified_on": "2026-05-21T12:00:00Z"
},
"type": "bundle",
"items": [
{
"file_path": "SKILL.md",
"size": 2048
},
{
"file_path": "references/v2.md",
"size": 1024
}
],
"meta": {
"file_count": 2,
"total_size_bytes": 3072
}
}
}