> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills API

Skills API 支持上传自定义 Skill、查询当前用户可以选择的 Skill，再把 `skill_id` 传给 Agent Run。推荐流程是：上传（如有需要）→ 查询可选列表 → 启动 Run。

基础地址：`https://meoo.com/open/v1`

## 上传或更新私有 Skill

```text theme={null}
POST /skills
```

所需权限：`skill.write`

请求体必须是 JSON。ZIP 以标准 Base64 放在 `package_base64` 中；解码后最大 32 MiB。ZIP 内必须有 `SKILL.md`，该文件解压后最大 1 MiB，且其 frontmatter `name` 必须与 `skill_name` 完全一致。

**字段说明**

* `skill_name`（string，必填）：1～255 位字母、数字、`.`、`_` 或 `-`；不能是 `.`、`..`，也不能与运行时内置 Skill 重名
* `package_base64`（string，必填）：Skill ZIP 的标准 Base64
* `skill_name_for_user`（string，可选）：展示名称，最长 100 字符
* `description`（string，可选）：描述，最长 2000 字符
* `description_for_user`（string，可选）：展示描述，最长 2000 字符
* `change_note`（string，可选）：版本说明，最长 500 字符
* `visibility`（private | tenant，可选）：默认 private，仅自己可见；tenant 将提交团队发布审核，审核通过后当前团队内可见。不支持 public。

`visibility=tenant`要求调用者为当前团队的 active 成员，且该团队具备可用的 Skill 权益，否则返回 403 forbidden。

```text theme={null}
base64 < ./resume-reviewer.zip | tr -d '\n' > /tmp/meoo-skill-package.base64
jq --rawfile package /tmp/meoo-skill-package.base64 '{
  skill_name: "resume-reviewer",
  package_base64: $package,
  skill_name_for_user: "简历审阅"
}' > /tmp/meoo-skill-upload.json

curl --request POST \
  --url "https://meoo.com/open/v1/skills" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @/tmp/meoo-skill-upload.json
```

成功返回 HTTP `201`：

```text theme={null}
{
  "skill_id": "101",
  "skill_name": "resume-reviewer",
  "version_id": "501",
  "version": "1",
  "is_new": true,
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "created_at": 1787014923000
}
```

同名更新规则：

● 当前用户已有 active 的 private 或 tenant Skill 时，可以创建后续版本

● 省略 visibility 时保持该 Skill 的原可见性

● 将已有 tenant Skill 改为 private，须仍在原团队内且具备写权限；审核中的团队版本会被取消，队友将不再可见

● 当前用户已有同名 public、已删除的 Skill，或已绑定其他团队的 tenant Skill 时，返回 409，不会转换、恢复或改挂到当前团队。换团队后，原团队下的同名 Skill 会继续占住该 skill\_name

## 查询当前可选择的 Skills

```text theme={null}
GET /skills?scope=mine&page_size=20
```

所需权限：`agent.run`，不新增 OAuth Scope。OAuth 和用户级 API Key 可以调用；项目级 API Key 绑定单一项目，不能访问此用户/租户级列表。

`scope` 可取以下值：

| 值        | 说明                                     |
| :------- | :------------------------------------- |
| `mine`   | 当前用户拥有且可消费的 Skills；默认值                 |
| `team`   | 当前租户内可消费的团队 Skills；要求 active 成员资格和可用权益 |
| `public` | 已发布且可消费的公开 Skills                      |
| `all`    | 合并以上来源                                 |

`page_size` 不传或传 `0` 时为 20，最大 100。`page_token` 是不透明游标，只能原样传回；游标绑定当前用户、租户和 `scope`，失效或混用会返回 `400 invalid_page_token`。

```text theme={null}
curl --request GET \
  --url "https://meoo.com/open/v1/skills?scope=all&page_size=20" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}"
```

```text theme={null}
{
  "skills": [
    {
      "skill_id": "101",
      "skill_name": "resume-reviewer",
      "display_name": "简历审阅",
      "description": "分析并审阅简历",
      "source": "owned",
      "visibility": "private"
    }
  ],
  "next_page_token": "opaque-token"
}
```

列表只包含当前可选择、具有可消费版本或包并通过既有安全策略的非内置 Skill，不返回 OSS 地址、owner/tenant 标识、权益明细或审核明细。它是查询时快照；Run 准入和 SkillTool 运行时仍会重新校验成员资格、权益、可见性和安全策略。

## 在 Agent Run 中使用

从查询结果中选择 `skill_id`，放入 Run 的 `skills` 数组。每个显式选择的技能都会被强制加载：

```text theme={null}
{
  "message": "使用简历审阅技能分析附件",
  "skills": [{ "skill_id": "101" }]
}
```

运行 Skill 只需要 `agent.run`；不要求 `skill.write`。当前不支持版本锁定，也不支持需要 MCP OAuth 的 Skill 授权流程。继承、清空和显式替换规则见 [Agent 附件与 Skills](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/a051cfb9-8c14-42bf-b4c0-b6a0a00fe2af)。

## 常见错误

| HTTP 状态 | 说明                                                                              |
| :------ | :------------------------------------------------------------------------------ |
| `400`   | 请求字段、分页游标、Base64、ZIP、SKILL.md 大小或 name 不符合要求                                    |
| `403`   | `GET /skills` 缺少 `agent.run`，项目级 API Key 调用列表，或 `POST /skills` 缺少 `skill.write` |
| `404`   | 当前授权用户不可用                                                                       |
| `409`   | 当前用户已有同名 public/tenant 或已删除的 Skill                                              |
| `502`   | Skill 包上传存储失败                                                                   |
| `503`   | 内容安全检查或依赖服务暂不可用                                                                 |