导入和运行技能¶
如果技能已经按技能包组织，可以先检查包内容，再导入工作区。导入成功只表示技能资源已经创建；要验证实际行为，还需要运行技能或将其绑定到智能体后发起一次低风险调用。
开始之前¶
请准备：
Product API Base URL、个人访问令牌和工作区 ID；
本地技能包文件；
技能运行所需的智能体、工具、知识库或文件；
一组不产生不可逆副作用的测试输入。
1. 检查技能包¶
检查接口只解析和校验技能包，不会在工作区创建技能：
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. 导入技能¶
确认检查结果后，上传同一个技能包。可选字段用于覆盖包内名称、描述、分类或标签：
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 提供结构化输入：
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。
绑定后验证¶
把技能绑定到智能体后，再通过智能体调用入口验证两件事：
符合
routing_summary的请求会选择该技能；不符合使用条件的请求不会误用该技能。
如果技能依赖有副作用的工具，第一次验证应使用测试资源，并保留人工批准步骤。