---
title: "List published skills"
method: GET
path: "/api/v1/catalog/skills"
tags: ["Catalog"]
---

# List published skills

`GET /api/v1/catalog/skills`

## Request

- Base URL: `https://skillrepo.dev`
- URL: `https://skillrepo.dev/api/v1/catalog/skills`
- Auth: HTTP bearer

Paginated list of skills published to the global catalog. Supports free-text search (`q`), sort order, grade filter, and standard offset pagination.

NOTE: `sort` and `grade` query params are currently parsed leniently — unknown values silently fall back to defaults (`name` and `all` respectively). Tightening to return 400 on invalid enum values is a separate change (see epic #1001).

## Query parameters

- `q` string: Free-text search across name, description, and owner.
- `sort` 'name' | 'popular' | 'recent' | 'top-rated' | 'grade' | 'relevance': Sort order for the catalog list endpoint. `grade` orders by safety grade A→F with ungraded skills last; `relevance` is hybrid semantic ranking (keyword + vector similarity) and falls back to `popular` when no `q` is supplied. With a `q`, other sorts re-rank within the relevant set.
- `grade` 'all' | 'A' | 'B' | 'C' | 'D' | 'F' | 'ungraded': Filter value for `?grade=` on the catalog list endpoint. `all` returns every skill; `ungraded` returns skills without analysis.
- `limit` integer: Items per page, 1-100 (default 20).
- `offset` integer: Zero-based offset into the result set (default 0).

## Response `200`

Paginated list of skills.

- CatalogSkillsResponse: Paginated list of published skills.
  - `skills` CatalogSkillListItem[], required
    - `name` string, required
    - `owner` string, required
    - `ownerName` string, required: The publisher's natural, identifiable name for display (#2986). `owner` stays the lowercase identity key used in paths.
    - `description` string, nullable, required
    - `license` string, nullable, required
    - `compatibility` string, nullable, required
    - `installs` integer, required
    - `activations` integer, required: DEPRECATED alias for `installs` — always equal. See detail-route stats object for the same note.
    - `avgRating` number, nullable, required
    - `safetyGrade` 'A' | 'B' | 'C' | 'D' | 'F', required: Skill safety grade derived from static + model analysis.
    - `publishedAt` string, date-time, nullable, required
  - `pagination` Pagination, required: Pagination metadata included alongside a paginated list response.
    - `total` integer, required: Total number of items matching the query (unpaginated).
    - `limit` integer, required: Maximum items returned per page.
    - `offset` integer, required: Zero-based index of the first item in this page.

## Other responses

- `401`: Missing or invalid authentication. For routes that require `bearerAccessKey` or `bearerCatalogKey`.
- `429`: Rate limit exceeded on the route's bucket. Includes `X-RateLimit-*` headers indicating the limit, remaining, and reset time.

---

[API](https://skmtc.dev/skillrepo/apis/skillrepo-api.md) · [All operations](https://skmtc.dev/skillrepo/apis/skillrepo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skillrepo/apis/skillrepo-api/revisions/b62bac246918?raw)