---
orphan: true
---

# Streaming polishing skill draft

Submit the skill draft and receive the polish event sent by the server; the result event contains the skill content that can be saved.

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/polish/stream
```

## Before you call

Prepare personal access tokens, workspace IDs, and draft skills to be polished. The response type is `text/event-stream`.

The example below uses:

- `$AI_STUDIO_API_KEY`: Actual personal access token.
- `$WORKSPACE_ID`: Target workspace ID.

## Request example

```bash
curl -N -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills/polish/stream" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "摘要",
    "description": "生成内容摘要",
    "instruction": "总结输入内容"
  }'
```

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Skill name. |
| `instruction` | string | Yes | Skill command to be polished. |
| `description` | string | Yes | Skill description. |
| `instruction_spec` | object | No | Structured skill command. |
| `instruction_spec.body` | string | No | Command text. |
| `instruction_spec.variables_schema` | object | No | JSON Schema of the directive variable. |
| `input_requirements` | string | No | Input requirement. |
| `output_format` | string | No | Output format. |
| `category` | string | No | Skill classification. |
| `tags` | string[] | No | Skill tag. |
| `phase` | string | No | Skill stage. |
| `pipeline` | string[] | No | Pipeline step. |
| `pipeline_ref` | string | No | Pipeline reference. |
| `source_type` | string | No | Skill source type. |
| `source_ref` | string | No | Skill source reference. |
| `routing_summary` | object | No | Route summary. |
| `requirements` | object | No | Skill dependency requirement. |
| `parameters_schema` | object | No | JSON Schema of the input parameter. |
| `output_contract` | object | No | Output contract. |
| `labels` | object | No | String label. |
| `annotations` | object | No | String annotation. |
| `metadata` | object | No | Extended metadata. |

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

## Successful response

Returns the event stream on success. Each event consists of a `event:` line, a single line of JSON for the `data:` line, and a blank line. The `result` event contains the verified skill draft, and `done` indicates the end of the flow.

```text
event: started
data: {"request_id":"req_01","prompt_version":"skill_polish_v1"}

event: delta
data: {"request_id":"req_01","content":"请总结输入内容"}

event: ping
data: {"request_id":"req_01","timestamp":"2026-08-21T07:00:00Z"}

event: result
data: {"request_id":"req_01","result":{"name":"摘要","description":"摘要技能","instruction":"请总结输入内容","tags":[]}}

event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| SSE event name | string | The event type in the `event:` row, which can be `started`, `delta`, `ping`, `result`, `error`, or `done`. |
| `data.request_id` | string | ID of this polishing request. |
| `data.prompt_version` | string | `started` The prompt word version in the event. |
| `data.content` | string | The incremental text in the `delta` event. |
| `data.timestamp` | string | RFC 3339 time in the `ping` event. |
| `data.result` | object | The verified skill draft in the `result` event. |
| `data.result.name` | string | Skill name. |
| `data.result.description` | string | Skill description. |
| `data.result.instruction` | string | Polished skill command. |
| `data.result.instruction_spec` | object | Structured skill command; does not return if not set. |
| `data.result.input_requirements` | string | Input requirement; does not return if not set. |
| `data.result.output_format` | string | Output format; does not return if not set. |
| `data.result.category` | string | Skill classification; does not return if not set. |
| `data.result.tags` | string[] | Skill tag. |
| `data.result.phase` | string | Skill stage; does not return if not set. |
| `data.result.pipeline` | string[] | Pipeline step; does not return if not set. |
| `data.result.pipeline_ref` | string | Pipeline reference; does not return if not set. |
| `data.result.source_type` | string | Skill source type; does not return if not set. |
| `data.result.source_ref` | string | Skill source reference; does not return if not set. |
| `data.result.routing_summary` | object | Route summary; not returned if not set. |
| `data.result.requirements` | object | Skill dependency requirements; not returned if not set. |
| `data.result.parameters_schema` | object | JSON Schema of the input parameter; does not return if not set. |
| `data.result.output_contract` | object | Output contract; does not return if not set. |
| `data.result.labels` | object | String label; does not return if not set. |
| `data.result.annotations` | object | String annotation; does not return if not set. |
| `data.result.metadata` | object | Extended metadata; not returned if not set. |
| `data.result.pending_confirmations` | string[] | Things that still need to be confirmed; do not return if not. |
| `data.result.warnings` | string[] | Polishing warning; does not return if there is none. |
| `data.error` | object | Public error message in the `error` event. |
| `data.error.code` | string | Error code within the stream. |
| `data.error.message` | string | In-stream error description. |
| `data.error.retryable` | boolean | Whether it is possible to retry. |

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

## Error response

After the stream has started, a processing error is returned via the SSE `error` event, followed by `done`:

```text
event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}
```

Request errors before the stream is established with a plain JSON response:

```json
{
  "code": 2,
  "message": "invalid argument"
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `2`
  - The JSON is invalid, or the skill draft fails the validation before creating the event stream.
  - Check the request body and required fields.
* - `503`
  - `15`
  - Skill polish service is not configured.
  - Try again later.
```

After the event stream is established, errors such as `NO_AVAILABLE_MODEL` and `MODEL_REQUEST_FAILED` are located in the SSE `error` event and no longer change the HTTP status code.