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

# 列出 Skills

> 获取当前账户下所有 Skill 的列表，支持分页。

`GET /api/v1/cloud/skills`

获取当前账户下所有 Skill 的列表，支持分页。

## 请求头

| 头部              | 必选 | 说明             |
| --------------- | -- | -------------- |
| `Authorization` | 是  | `Bearer <PAT>` |

## 查询参数

| 参数          | 类型      | 必选 | 说明                                                            |
| ----------- | ------- | -- | ------------------------------------------------------------- |
| `limit`     | integer | 否  | 每页返回数量上限。默认 20，范围 1-100。超过 100 返回 `400 invalid_request_error` |
| `page`      | string  | 否  | Claude 风格的向后翻页游标，等价于 `after_id`；与 `before_id`、`after_id` 互斥   |
| `after_id`  | string  | 否  | 游标分页：返回此 ID 之后的记录。与 `page`、`before_id` 互斥                     |
| `before_id` | string  | 否  | 游标分页：返回此 ID 之前的记录。与 `page`、`after_id` 互斥                      |
| `name`      | string  | 否  | 按 Skill 名称前缀搜索，不区分大小写                                         |
| `source`    | string  | 否  | 按来源过滤，可选值：`custom`、`qoder`                                    |

完整分页规范详见 [分页](/zh/cloud-agents/api/conventions/pagination)。

## 示例请求

```bash theme={null}
# 获取所有 Skill
curl -X GET "https://api.qoder.com/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_PAT"

# 分页获取
curl -X GET "https://api.qoder.com/api/v1/cloud/skills?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

# 使用游标翻页
curl -X GET "https://api.qoder.com/api/v1/cloud/skills?limit=10&page=skill_019e3bba474b73cfaf19eae9b5f5e66d" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
      "type": "skill",
      "display_title": "test-skill-api-doc",
      "description": "A test skill for API documentation",
      "source": "custom",
      "latest_version": "1",
      "metadata": {
        "team": "docs"
      },
      "created_at": "2026-05-18T15:35:24.248164Z",
      "updated_at": "2026-05-18T15:35:24.248164Z"
    }
  ],
  "next_page": null,
  "first_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "last_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "has_more": false
}
```

空列表响应：

```json theme={null}
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 响应字段

| 字段          | 类型             | 说明                                                                           |
| ----------- | -------------- | ---------------------------------------------------------------------------- |
| `data`      | array          | [Skill 对象](/zh/cloud-agents/api/skills/schemas#skill-对象)数组；列表响应不包含 `content` |
| `next_page` | string \| null | 下一页向后游标；`has_more` 为 `true` 时传给 `page`                                       |
| `first_id`  | string \| null | 当前页第一条记录 ID                                                                  |
| `last_id`   | string \| null | 当前页最后一条记录 ID                                                                 |
| `has_more`  | boolean        | 是否还有更多记录（`true` 时使用 `next_page` 作为下一页的 `page` 值）                             |

## 错误码

| HTTP | type                    | 触发条件                                                        |
| ---- | ----------------------- | ----------------------------------------------------------- |
| 400  | `invalid_request_error` | `limit` 或 `source` 非法，或同时传入多个 `page`、`before_id`、`after_id` |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                                                  |

完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="Agent 技能" icon="sparkles" href="/zh/cloud-agents/skills">
    为 Agent 附加领域专业知识。
  </Card>
</CardGroup>