创建和管理技能¶
技能把完成一类任务所需的说明、输入要求、工具依赖和输出约定保存为可复用资源。创建技能不会运行任务；创建成功后，需要保存技能 ID，再将技能绑定到智能体或通过运行接口验证。
开始之前¶
请准备 Product API Base URL、个人访问令牌和工作区 ID。本文假设 PRODUCT_API_BASE_URL 已包含 /newmoi；认证方式见 Product API 开始使用。
在创建技能前，先确认任务边界：什么输入可以触发这项技能、应该遵循哪些步骤、需要哪些工具或文件，以及期望得到什么结果。只写宽泛目标会让智能体难以判断何时使用技能。
创建技能¶
下面创建一个用于审查发布说明的工作区技能：
curl -X POST \
"$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/skills" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "review-release-notes",
"description": "Check release notes for missing impact, upgrade steps, and limitations.",
"status": "active",
"category": "documentation",
"tags": ["review", "release"],
"routing_summary": {
"summary": "Use when release notes need a completeness review.",
"examples": ["Review these release notes before publication."]
},
"instruction": {
"body": "Review the supplied release notes. Identify missing impact, upgrade steps, limitations, and verification guidance. Return findings by severity."
},
"parameters_schema": {
"type": "object",
"properties": {
"content": {"type": "string"}
},
"required": ["content"]
}
}'
成功后保存 data.id 和 data.version。技能名称便于查找，后续更新、执行和绑定仍应使用技能 ID。
描述技能的使用条件¶
配置 |
解决的问题 |
写作建议 |
|---|---|---|
|
这项技能完成什么任务？ |
写清对象和结果，不使用“智能处理”等宽泛表述。 |
|
智能体何时应该选择它？ |
写触发条件，并提供一到两个真实请求示例。 |
|
选中后按什么方法执行？ |
使用有顺序、可检查的步骤，写明停止或升级条件。 |
|
运行前需要什么资源？ |
明确技能、工具、知识库、文件和模型能力依赖。 |
|
调用方需要传什么输入？ |
使用 JSON Schema 约束字段和类型。 |
|
结果需要满足什么结构？ |
只声明调用方真正依赖的字段。 |
完整字段见技能 API 参考。
查找和更新技能¶
列表接口可以按关键词、分类、状态、来源、阶段和标签筛选。读取详情后再提交部分更新，避免覆盖刚被其他维护者修改的配置。
curl "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/skills?query=release&status=active&limit=20&offset=0" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID"
更新说明、依赖或输入输出契约后，读取版本列表确认新版本已经生成。需要回到历史版本时，使用“设为当前版本”接口，并传入调用方已知的当前版本，防止并发修改被静默覆盖。
停用和归档¶
暂时不希望智能体选择某项技能时，将其状态设为停用。确认没有智能体、技能或自动化任务依赖后，再将其归档。归档不会删除历史版本，也不会改变已经创建的运行记录。