---
title: "Search published skills via the CLI's account-key auth"
method: GET
path: "/api/v1/skills/search"
tags: ["Skills"]
---

# Search published skills via the CLI's account-key auth

`GET /api/v1/skills/search`

## Request

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

Account-authenticated skill search. Returns a slim list view (no inline file content) — clients that need full SKILL.md should follow up with `GET /api/v1/skills/{owner}/{name}`.

Delegates to the same underlying query as the catalog-key `/api/v1/catalog/skills` endpoint. This route exists so the CLI can search without requiring a separate catalog key.

The `sort` query param is parsed leniently — unknown values silently fall back to `popular` rather than returning 400. Don't rely on the fallback; use one of the listed values.

## 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.
- `limit` integer: Items per page, 1-100 (default 20).
- `offset` integer: Zero-based offset into the result set (default 0).

## Response `200`

Search results.

- SkillsSearchResponse: Paginated list of skills matching the search query.
  - `skills` SkillSearchItem[], required
    - `name` string, required
    - `owner` string, required
    - `ownerName` string, required
    - `description` string, nullable, required
    - `version` string, nullable, required
    - `license` string, nullable, required
    - `compatibility` string, nullable, required
    - `installs` integer, required
    - `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`.
- `403`: Authenticated, but the key lacks the required scope or the account is suspended. Use `code` to distinguish: `insufficient_scope`, `account_suspended`, `plan_limit`.
- `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)