For the complete documentation index, see llms.txt. This page is also available as Markdown.

POST /v2/skills/{skill_id}/versions

Create Skill Version

post

Publish a new version, optionally carrying files from a previous version.

How to use

Publish a new revision. Repeat carry_paths for files to keep; base_version selects the source version (current by default). Supplying a different name can rename the skill. Review the assembled bundle before publishing.

Authentication and permissions

Required permissions: skills.update. Resource and owner access checks also apply.

Authorizations
AuthorizationstringRequired

Personal API key (sk_...) or supported user access JWT. See Authentication and authorization for endpoint restrictions and scopes. Use exactly one Authorization header.

Path parameters
skill_idstring · uuidRequired

ID of the skill.

Body
filesstring · binary[]Optional

Bundle files; each part's filename is its relative POSIX path inside the bundle (optionally under one shared root folder). A single .zip is accepted as an alternative.

namestring · nullableOptional

Skill name (form mode); a changed name renames the skill when published.

descriptionstring · nullableOptional

Skill description (form mode).

instructionsstring · nullableOptional

SKILL.md body (form mode).

actionsstring[]Optional

Action refs; repeat the field per item.

carry_pathsstring[]Optional

File paths to carry over unchanged from the current files; repeat the field per item.

base_versioninteger · min: 1 · nullableOptional

Version to copy carry_paths from; defaults to the current version.

Responses
201

Created

application/json
post/v2/skills/{skill_id}/versions
curl
curl --fail-with-body -sS \
  "$STACKAI_BASE_URL/v2/skills/${SKILL_ID}/versions" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  -F 'files=@skill.zip'
{
  "response_code": "text",
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "data": {
    "version": 1,
    "description": "text",
    "created_by_user_profile": {
      "id": "text",
      "full_name": "text"
    },
    "created_at": "2026-01-01T00:00:00.000Z",
    "instructions": "text",
    "frontmatter": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "actions": [
      "text"
    ],
    "files": [
      {
        "path": "text",
        "content_type": "text",
        "size": 1
      }
    ]
  }
}

Last updated

Was this helpful?