# 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.

```text
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

```bash
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.

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](get-skill.md) to confirm the saved result.