Update skills

Partially updates skills in the current workspace. Fields not provided retain their original values; instead of just updating the label, the update creates a new skill version and sets it as the current version.

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

Before you call

First Query skill details confirm the skill to be updated. Prepare the personal access token, target workspace ID, and skill ID that have 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: Target workspace ID, passed through X-Workspace-ID Header.

• $SKILL_ID: Skill ID to be updated.

Request example

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills/$SKILL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "更新后的说明",
    "change_summary": "补充输出约定"
  }'

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	The current workspace ID.
skill_id	string	Yes	The skill ID to update.

Query parameters

Parameters	Type	Is it required	Description
skill_workspace_id	string	No	The workspace to which the skill belongs; can only be the current workspace or system. System skills are read-only and updates will be rejected.

Request body

The fields in the request body are optional; fields not provided retain their original values.

Field	Type	Is it required	Description
name	string	No	Basic definition of skill. The status can be draft, active, disabled, or archived.
description	string	No	Basic definition of skill. The status can be draft, active, disabled, or archived.
status	string	No	Basic definition of skill. The status can be draft, active, disabled, or archived.
source_type	string	No	Basic definition of skill. The status can be draft, active, disabled, or archived.
source_ref	string	No	Basic definition of skill. The status can be draft, active, disabled, or archived.
category	string	No	Classification and display information. Providing tags replaces the existing tag; merely updating the tag does not create a new version.
icon_ref	string	No	Classification and display information. Providing tags replaces the existing tag; merely updating the tag does not create a new version.
tags	string[]	No	Classification and display information. Providing tags replaces the existing tag; merely updating the tag does not create a new version.
phase	string	No	Classification and display information. Providing tags replaces the existing tag; merely updating the tag does not create a new version.
pipeline_ref	string	No	Classification and display information. Providing tags replaces the existing tag; merely updating the tag does not create a new version.
routing_summary	object	No	Route summary, directives, and dependency requirements.
instruction	object	No	Route summary, directives, and dependency requirements.
requirements	object	No	Route summary, directives, and dependency requirements.
parameters_schema	object	No	Input Schema and output convention.
output_contract	object	No	Input 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	Change description for the new version.

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

The updated skill must still retain the instruction body or route summary and satisfy the validation rules for skill dependency references.

Successful response

Returns 200 and the updated skill on success.

{
  "code": 0,
  "data": {
    "id": "skill_01",
    "workspace_id": "ws_01",
    "name": "摘要技能",
    "description": "更新后的说明",
    "status": "active",
    "source_type": "custom",
    "instruction": {
      "body": "总结用户提供的内容。"
    },
    "version": 3,
    "updated_at": "2026-01-03T10:00:00Z"
  }
}

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	Updated basic definition.
data.description	string	Updated basic definition.
data.status	string	Updated basic definition.
data.instruction	object	Updated directive, routing summary and dependency requirements.
data.routing_summary	object	Updated directive, routing summary and dependency requirements.
data.requirements	object	Updated directive, routing summary and dependency requirements.
data.version	integer	Current version; remains unchanged only when updating tags.
data.updated_at	string	Last updated time, using RFC 3339 format.

Error response

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

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The request field, dependency reference, or updated skill definition is invalid.	Check field values, directive or route summaries, and dependent resources.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to update skills.	Check workspace authorization.
403	7（FORBIDDEN）	Specify system skills as read-only.	Do not modify system skills; create or update your own skills in the current workspace.
404	3（NOT_FOUND）	The skill does not exist in the specified workspace.	Check skill ID and skill_workspace_id.
503	15（UNAVAILABLE）	Skill services or authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Use the same resource identifier Query skill details to confirm the update result.

Last updated on Sep 3, 2026