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.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/import

Before you call¶

First Check the skill package to confirm that the package format passes the verification. Prepare a personal access token with access to the target workspace, the target workspace ID, and the local skills pack file.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: The workspace ID of the skill to be imported, passed through the X-Workspace-ID Header.

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 example¶

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

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.

{
  "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": []
  }
}

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¶

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

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 3, 2026