# 创建和管理技能

技能把完成一类任务所需的说明、输入要求、工具依赖和输出约定保存为可复用资源。创建技能不会运行任务；创建成功后，需要保存技能 ID，再将技能绑定到智能体或通过运行接口验证。

## 开始之前

请准备 Product API Base URL、个人访问令牌和工作区 ID。本文假设 `PRODUCT_API_BASE_URL` 已包含 `/newmoi`；认证方式见 [Product API 开始使用](../../product-api/getting-started.md)。

在创建技能前，先确认任务边界：什么输入可以触发这项技能、应该遵循哪些步骤、需要哪些工具或文件，以及期望得到什么结果。只写宽泛目标会让智能体难以判断何时使用技能。

## 创建技能

下面创建一个用于审查发布说明的工作区技能：

```bash
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。

## 描述技能的使用条件

| 配置 | 解决的问题 | 写作建议 |
| --- | --- | --- |
| `description` | 这项技能完成什么任务？ | 写清对象和结果，不使用“智能处理”等宽泛表述。 |
| `routing_summary` | 智能体何时应该选择它？ | 写触发条件，并提供一到两个真实请求示例。 |
| `instruction.body` | 选中后按什么方法执行？ | 使用有顺序、可检查的步骤，写明停止或升级条件。 |
| `requirements` | 运行前需要什么资源？ | 明确技能、工具、知识库、文件和模型能力依赖。 |
| `parameters_schema` | 调用方需要传什么输入？ | 使用 JSON Schema 约束字段和类型。 |
| `output_contract` | 结果需要满足什么结构？ | 只声明调用方真正依赖的字段。 |

完整字段见[技能 API 参考](api-reference.md)。

## 查找和更新技能

列表接口可以按关键词、分类、状态、来源、阶段和标签筛选。读取详情后再提交部分更新，避免覆盖刚被其他维护者修改的配置。

```bash
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"
```

更新说明、依赖或输入输出契约后，读取版本列表确认新版本已经生成。需要回到历史版本时，使用“设为当前版本”接口，并传入调用方已知的当前版本，防止并发修改被静默覆盖。

## 停用和归档

暂时不希望智能体选择某项技能时，将其状态设为停用。确认没有智能体、技能或自动化任务依赖后，再将其归档。归档不会删除历史版本，也不会改变已经创建的运行记录。

## 下一步

- [导入和运行技能](import-run-skills.md)
- [管理工具](../tools/manage-tools.md)
- [查询技能 API](api-reference.md)