Import skill pack¶

Import the skills ZIP package and the static files within it, and create an active skill of version 1. Form fields can be used to override the name, description, category, and tags of the inventory within the package.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/skills/import

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First Check the skill package to confirm that the package format passes the verification.

The request type of this interface is multipart/form-data; the example uses curl -F to submit the file and do not add Content-Type: application/json.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/skills/import" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./skill-package.zip" \
  -F 'tags=["摘要","文本处理"]'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.

Form fields

Field	Type	Is it required	Description
`file`	file	Yes	`.zip` skill package that passes the format validation described in Check skill pack.
`name`	string	No	Override the corresponding metadata in `SKILL.md`; use the package value if not provided.
`description`	string	No	Override the corresponding metadata in `SKILL.md`; use the package value if not provided.
`category`	string	No	Override the corresponding metadata in `SKILL.md`; use the package value if not provided.
`tags`	string	No	JSON string array, such as `["summary","text-processing"]`; replaces the package tags when provided.

Successful response¶

Returns 201 on success. Static files are saved with the import results; subsequent skill version updates will not automatically return these files to the historical version.

Response example

JSON
{
  "code": 0,
  "data": {
    "skill": {
      "id": "skill_01",
      "workspace_id": "ws_01",
      "name": "摘要技能",
      "description": "总结输入内容。",
      "status": "active",
      "source_type": "custom",
      "source_ref": "skill_package:sha256:abc123",
      "version": 1
    },
    "files": [
      {
        "file_path": "SKILL.md",
        "file_kind": "manifest",
        "media_type": "text/markdown",
        "sha256": "abc123",
        "size_bytes": 512
      }
    ],
    "warnings": []
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.skill`	object	New skill; `status` is `active`, `version` is `1`.
`data.skill.source_ref`	string	Skill pack source reference pointing to the imported compressed package summary.
`data.files`	array	Saved static file metadata.
`data.warnings`	string[]	Non-blocking import warning.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>",
  "details": {
    "reason": "SKILL_PACKAGE_INVALID_ZIP"
  }
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Invalid package format, manifest, form `tags` or skill definition after import.	Fix package or form fields based on `details.reason`.
`413`	`14`（`RESOURCE_EXHAUSTED`）	The compressed package or decompressed content exceeds the size limit.	Reduce package size or remove unnecessary files.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to import skill packs.	Check workspace authorization.
`503`	`15`（`UNAVAILABLE`）	Skill pack storage or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

Use the returned skill ID Query skill files or Download skill file.

Last updated on Sep 15, 2026