Check skill pack¶

Verify and preview the skill ZIP package to be imported without creating the skill or saving the file. Passing the check only means that the package conforms to the import format, and the import interface still needs to be called to create skills.

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

Before you call this API¶

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

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.

The compressed package must contain one and only one SKILL.md. The file can be located in the root directory of the compressed package, or the only top-level directory; its YAML frontmatter must contain name and description, and the body must be non-empty instruction content.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/skills/import/inspect" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./skill-package.zip"

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. The compressed package is limited to 50 MiB, its uncompressed contents to 100 MiB, and it can contain up to 500 entries with each file limited to 10 MiB.

Successful response¶

Returns 200 and package preview on success. When the script file is included, warnings includes SKILL_PACKAGE_SCRIPTS_NOT_EXECUTABLE.

Response example

JSON
{
  "code": 0,
  "data": {
    "name": "摘要技能",
    "description": "总结输入内容。",
    "category": "文本处理",
    "tags": ["摘要"],
    "instruction": "总结用户提供的内容。",
    "files": [
      {
        "file_path": "SKILL.md",
        "file_kind": "manifest",
        "media_type": "text/markdown",
        "sha256": "abc123",
        "size_bytes": 512
      }
    ],
    "warnings": [],
    "archive_digest": "sha256:abc123"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.name`	string	Skill metadata read from the skill pack manifest.
`data.description`	string	Skill metadata read from the skill pack manifest.
`data.category`	string	Skill metadata read from the skill pack manifest.
`data.tags`	string[]	Skill metadata read from the skill pack list.
`data.instruction`	string	The command text of `SKILL.md`.
`data.files`	array	File metadata in the package.
`data.files[].file_path`	string	Relative path, file category and media type.
`data.files[].file_kind`	string	Relative path, file category and media type.
`data.files[].media_type`	string	Relative path, file category and media type.
`data.files[].sha256`	string	Summary of file content and size.
`data.files[].size_bytes`	integer	File content summary and size.
`data.warnings`	string[]	Non-blocking warning.
`data.archive_digest`	string	SHA-256 digest of the uploaded compressed package.

[] 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`）	The ZIP format, directory structure, `SKILL.md`, frontmatter, or path does not meet the requirements.	Fix the skill pack according to `details.reason` and try again.
`413`	`14`（`RESOURCE_EXHAUSTED`）	The compressed package exceeds 50 MiB, or the total decompressed size exceeds 100 MiB.	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 the permission to check skill packages.	Check workspace authorization.
`503`	`15`（`UNAVAILABLE`）	Skill services or authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

After completion, Query skill details confirms the current status.

Last updated on Sep 15, 2026