# 导入和运行技能

如果技能已经按技能包组织，可以先检查包内容，再导入工作区。导入成功只表示技能资源已经创建；要验证实际行为，还需要运行技能或将其绑定到智能体后发起一次低风险调用。

## 开始之前

请准备：

- Product API Base URL、个人访问令牌和工作区 ID；
- 本地技能包文件；
- 技能运行所需的智能体、工具、知识库或文件；
- 一组不产生不可逆副作用的测试输入。

## 1. 检查技能包

检查接口只解析和校验技能包，不会在工作区创建技能：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/skills/import/inspect" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./review-release-notes.zip"
```

先检查响应中的技能元数据、文件列表、警告和错误。发现缺少入口说明、引用文件或必要字段时，应先修复技能包，不要把“可以上传”当作“可以运行”。

## 2. 导入技能

确认检查结果后，上传同一个技能包。可选字段用于覆盖包内名称、描述、分类或标签：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/skills/import" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./review-release-notes.zip" \
  -F "name=review-release-notes" \
  -F "category=documentation" \
  -F 'tags=["review","release"]'
```

保存响应中的技能 ID。然后使用文件列表和文件内容接口确认随包导入的说明、模板或其他资源可以读取。

## 3. 运行技能

运行接口提交一次技能运行并返回技能运行记录。下面通过 `variables` 提供结构化输入：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/skills/$SKILL_ID/execute" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<AGENT_ID>",
    "message": "Review the supplied release notes.",
    "variables": {
      "content": "<RELEASE_NOTES>"
    },
    "idempotency_key": "<UNIQUE_REQUEST_KEY>"
  }'
```

响应中的 `data.id` 是技能运行记录 ID；`data.runtime_task_id` 和 `data.runtime_task_url` 在创建底层运行任务后返回。`accepted` 一类状态表示请求已受理，不代表技能已经成功完成。按返回的任务入口继续查询运行状态和结果。

## 使用 AI 润色草稿

流式润色接口可以根据名称、描述、说明和输入输出要求生成改写建议。事件依次包含 `started`、若干 `delta`、`result`，最后以 `done` 结束；`error` 表示本次生成失败。

润色结果是候选内容，不会自动创建或修改技能。提交前需要人工确认触发条件、工具依赖、权限边界和输出契约，尤其要处理结果中的 `pending_confirmations` 和 `warnings`。

## 绑定后验证

把技能绑定到智能体后，再通过智能体调用入口验证两件事：

1. 符合 `routing_summary` 的请求会选择该技能；
2. 不符合使用条件的请求不会误用该技能。

如果技能依赖有副作用的工具，第一次验证应使用测试资源，并保留人工批准步骤。

## 下一步

- [创建和管理技能](manage-skills.md)
- [查询技能 API](api-reference.md)
- [调用智能体](../../product-api/agents-a2a/call-agent-a2a.md)