Create skills

Create a skill in the current workspace and create version 1 as the current version. The skill must also provide a name, description, and command body or route summary.

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

Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

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 created, passed through the X-Workspace-ID Header.

requirements.skill_refs cannot reference the skill itself; tool and skill references must be valid resource IDs. Keys or running session references cannot be included in the metadata and schema.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "摘要技能",
    "description": "总结输入内容。",
    "instruction": {
      "body": "总结用户提供的内容。"
    },
    "status": "active",
    "tags": ["文本处理"]
  }'

Path parameters

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

Request body

Field	Type	Is it required	Description
name	string	Yes	Skill name, up to 128 characters.
description	string	Yes	Skill description, up to 4096 characters.
instruction	object	Condition required	Command definition; when routing_summary.summary is not provided, instruction.body must be provided. Can contain variables_schema.
routing_summary	object	Condition required	Route summary; when instruction.body is not provided, summary must be provided. Can contain examples.
status	string	No	Status: draft (default), active, disabled, or archived.
source_type	string	No	Source type and reference. The source type defaults to custom, but can also be system, market, or workflow_template.
source_ref	string	No	Source type and reference. The source type defaults to custom, but can also be system, market, or workflow_template.
category	string	No	Classification and display information.
icon_ref	string	No	Classification and display information.
tags	string[]	No	Classification and display information.
phase	string	No	Classification and display information.
pipeline_ref	string	No	Classification and display information.
requirements	object	No	Dependency requirement, can include skill_refs, tool_refs, tool_resource_refs, knowledge_base_roles, file_inputs, and model_capabilities.
parameters_schema	object	No	Input parameter Schema and output convention.
output_contract	object	No	Input parameter Schema and output convention.
market_metadata	object	No	Market metadata, tags, annotations, and extended metadata.
labels	object	No	Market metadata, tags, annotations, and extended metadata.
annotations	object	No	Market metadata, tags, annotations, and extended metadata.
metadata	object	No	Market metadata, tags, annotations, and extended metadata.
change_summary	string	No	Description of changes for the first version.

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

Successful response

Returns 201 and the new skill on success.

{
  "code": 0,
  "data": {
    "id": "skill_01",
    "workspace_id": "ws_01",
    "name": "摘要技能",
    "description": "总结输入内容。",
    "status": "active",
    "source_type": "custom",
    "instruction": {
      "body": "总结用户提供的内容。"
    },
    "version": 1,
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Skill ID and workspace.
data.workspace_id	string	Skill ID and workspace.
data.name	string	Basic information and status of the skill.
data.description	string	Basic information and status of the skill.
data.status	string	Basic information and status of the skill.
data.source_type	string	Source type and source reference; not returned if reference is not set.
data.source_ref	string	Source type and source reference; not returned if reference is not set.
data.instruction	object	Directive, routing summary, and dependency requirements.
data.routing_summary	object	Directive, routing summary, and dependency requirements.
data.requirements	object	Directive, routing summary, and dependency requirements.
data.parameters_schema	object	Input Schema and output convention; does not return if not set.
data.output_contract	object	Input Schema and output convention; does not return if not set.
data.version	integer	Current skill version; the new skill is 1.
data.created_at	string	Creation and last update times, using RFC 3339 format.
data.updated_at	string	Creation and last update times, using RFC 3339 format.

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

Error response

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

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	Name, description, directive and route summary are missing, or dependency, state, source type is invalid.	Complete required fields and check resource references and field values.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to create skills in the workspace.	Check workspace authorization.
409	4（ALREADY_EXISTS）	The specified skill ID already exists.	Change skill ID or update existing skills.
503	15（UNAVAILABLE）	Skill services or authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Record the returned skill ID. Use Query skill details to confirm the saved result.

Last updated on Sep 3, 2026