# 技能 API 参考

本页汇总工作区技能的查询、创建、导入、版本和运行接口。认证与工作区规则见 [Product API 开始使用](../../product-api/getting-started.md)。

## 接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `GET` | `/workspaces/{workspace_id}/skills` | 列出技能。 |
| `GET` | `/workspaces/{workspace_id}/skills/tags` | 列出技能标签及数量。 |
| `POST` | `/workspaces/{workspace_id}/skills` | 创建技能。 |
| `GET` | `/workspaces/{workspace_id}/skills/{skill_id}` | 读取技能详情。 |
| `PATCH` | `/workspaces/{workspace_id}/skills/{skill_id}` | 部分更新技能；将状态设为 `archived` 可归档。 |
| `POST` | `/workspaces/{workspace_id}/skills/import/inspect` | 检查技能包。 |
| `POST` | `/workspaces/{workspace_id}/skills/import` | 导入技能包。 |
| `GET` | `/workspaces/{workspace_id}/skills/{skill_id}/files` | 列出技能文件。 |
| `GET` | `/workspaces/{workspace_id}/skills/{skill_id}/files/content?path={path}` | 下载技能文件。 |
| `GET` | `/workspaces/{workspace_id}/skills/{skill_id}/versions` | 列出技能版本。 |
| `POST` | `/workspaces/{workspace_id}/skills/{skill_id}/versions/{version}/current` | 将指定版本设为当前版本。 |
| `POST` | `/workspaces/{workspace_id}/skills/{skill_id}/execute` | 运行技能。 |
| `POST` | `/workspaces/{workspace_id}/skills/polish/stream` | 流式润色技能草稿。 |

## 创建和更新字段

| 字段 | 类型 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `name` | string | 创建时是 | — | 技能名称。 |
| `description` | string | 否 | — | 任务目标和结果。 |
| `status` | string | 否 | — | 技能状态。归档使用 `archived`。 |
| `source_type`、`source_ref` | string | 否 | — | 技能来源。 |
| `category`、`tags`、`phase` | string、array、string | 否 | — | 分类和检索信息。 |
| `routing_summary` | object | 否 | — | 选择技能所需的摘要和示例。 |
| `instruction` | object | 否 | — | `body` 及可选变量 Schema。 |
| `requirements` | object | 否 | — | 技能、工具、知识库、文件和模型能力依赖。 |
| `parameters_schema` | object | 否 | — | 执行输入的 JSON Schema。 |
| `output_contract` | object | 否 | — | 输出约定。 |
| `change_summary` | string | 否 | — | 本次变更摘要。 |

更新接口接受上述字段的子集。系统技能或来自其他工作区的技能可能需要通过 `skill_workspace_id` 指定资源所属工作区；不要用当前工作区 ID 猜测资源归属。

## 列表和版本

技能列表支持 `query`、`category`、`status`、`source_type`、`phase`、重复的 `tags`、`limit` 和 `offset`。版本列表额外返回 `version`、`spec_snapshot`、`change_summary` 和创建时间。

设置当前版本时，请求体包含：

```json
{
  "expected_current_version": 3
}
```

该字段用于检测并发修改。若当前版本已变化，应重新读取版本列表，而不是直接重试旧请求。

## 运行请求和响应

运行请求可包含 `agent_id`、`context_id`、`message`、`parts`、`variables`、`parameters`、`resource_refs`、`idempotency_key` 和 `metadata`。响应主要字段如下：

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 始终返回 | 技能运行记录 ID。 |
| `skill_id` | string | 始终返回 | 本次运行的技能。 |
| `skill_version` | integer | 始终返回 | 本次运行使用的版本。 |
| `runtime_task_id` | string | 已创建运行任务时返回 | 底层运行任务 ID。 |
| `runtime_task_url` | string | 可提供查询入口时返回 | 后续查询入口。 |
| `status` | string | 始终返回 | 执行当前状态。 |
| `accepted_at` | string | 始终返回 | 请求受理时间。 |

## 流式润色事件

流式响应使用 SSE。客户端必须按 `request_id` 关联同一次请求，并处理：`started`、`delta`、`ping`、`result`、`error` 和 `done`。只有收到 `result` 后才能取得完整候选技能；收到 `done` 只表示流结束，不会自动保存候选内容。

## 任务指南

- [创建和管理技能](manage-skills.md)
- [导入和运行技能](import-run-skills.md)