创建技能

在当前工作区创建技能，并创建版本 1 作为当前版本。技能必须同时提供名称、描述，以及指令正文或路由摘要。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：要创建技能的工作区 ID，通过 X-Workspace-ID Header 传递。

requirements.skill_refs 不能引用技能自身；工具和技能引用必须是有效的资源 ID。元数据和 Schema 中不能包含密钥或运行会话引用。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。

请求体

字段	类型	是否必填	说明
name	string	是	技能名称，最长 128 个字符。
description	string	是	技能描述，最长 4096 个字符。
instruction	object	条件必填	指令定义；当未提供 routing_summary.summary 时，必须提供 instruction.body。可包含 variables_schema。
routing_summary	object	条件必填	路由摘要；当未提供 instruction.body 时，必须提供 summary。可包含 examples。
status	string	否	状态：draft（默认）、active、disabled 或 archived。
source_type	string	否	来源类型和引用。来源类型默认为 custom，也可为 system、market 或 workflow_template。
source_ref	string	否	来源类型和引用。来源类型默认为 custom，也可为 system、market 或 workflow_template。
category	string	否	分类和展示信息。
icon_ref	string	否	分类和展示信息。
tags	string（字符串数组）	否	分类和展示信息。
phase	string	否	分类和展示信息。
pipeline_ref	string	否	分类和展示信息。
requirements	object	否	依赖要求，可包含 skill_refs、tool_refs、tool_resource_refs、knowledge_base_roles、file_inputs 和 model_capabilities。
parameters_schema	object	否	输入参数 Schema 和输出约定。
output_contract	object	否	输入参数 Schema 和输出约定。
market_metadata	object	否	市场元数据、标签、注释和扩展元数据。
labels	object	否	市场元数据、标签、注释和扩展元数据。
annotations	object	否	市场元数据、标签、注释和扩展元数据。
metadata	object	否	市场元数据、标签、注释和扩展元数据。
change_summary	string	否	首个版本的变更说明。

请求示例

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": ["文本处理"]
  }'

成功响应

成功时返回 201 和新技能。

{
  "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"
  }
}

响应字段如下。

字段	类型	说明
code	integer	成功时为 0。
data.id	string	技能 ID 和所属工作区。
data.workspace_id	string	技能 ID 和所属工作区。
data.name	string	技能基本信息和状态。
data.description	string	技能基本信息和状态。
data.status	string	技能基本信息和状态。
data.source_type	string	来源类型和来源引用；未设置引用时不返回。
data.source_ref	string	来源类型和来源引用；未设置引用时不返回。
data.instruction	object	指令、路由摘要和依赖要求。
data.routing_summary	object	指令、路由摘要和依赖要求。
data.requirements	object	指令、路由摘要和依赖要求。
data.parameters_schema	object	输入 Schema 和输出约定；未设置时不返回。
data.output_contract	object	输入 Schema 和输出约定；未设置时不返回。
data.version	integer	当前技能版本；新建技能为 1。
data.created_at	string	创建和最近更新时间，使用 RFC 3339 格式。
data.updated_at	string	创建和最近更新时间，使用 RFC 3339 格式。

错误响应

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

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	2（INVALID_ARGUMENT）	缺少名称、描述、指令和路由摘要，或依赖、状态、来源类型无效。	补齐必填字段，并检查资源引用和字段值。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。	检查 API Key。
403	5（PERMISSION_DENIED）	当前身份没有在工作区中创建技能的权限。	检查工作区授权。
409	4（ALREADY_EXISTS）	指定的技能 ID 已存在。	更换技能 ID 或更新已有技能。
503	15（UNAVAILABLE）	技能服务或授权依赖暂不可用。	稍后重试。

后续操作

记录返回的技能标识。用查询技能详情确认保存结果。

最后更新于 2026 年 8 月 22 日