---
title: "List available registry skills"
method: GET
path: "/registry/{registryName}/v0.1/x/dev.toolhive/skills"
tags: ["registry-skills"]
---

# List available registry skills

`GET /registry/{registryName}/v0.1/x/dev.toolhive/skills`

Get a paginated list of skills from the registry. Supports optional full-text search and pagination.

## Path parameters

- `registryName` string, required

## Query parameters

- `q` string
- `page` integer
- `limit` integer

## Response `200`

OK

- PkgApiV1SkillsV01Response — Paginated list of skills from the registry
  - `metadata` PkgApiV1PaginationV01Metadata — Metadata contains pagination information
    - `limit` integer — Limit is the maximum number of items per page
    - `page` integer — Page is the current page number (1-based)
    - `total` integer — Total is the total number of items matching the query
  - `skills` RegistrySkill[] — Skills is the list of skills on the current page
    - `_meta` object — Meta is an opaque payload with extended meta data details of the skill.
    - `allowedTools` string[] — AllowedTools is the list of tools that the skill is compatible with. This is experimental.
    - `compatibility` string — Compatibility is the environment requirements of the skill.
    - `description` string — Description is the description of the skill.
    - `icons` RegistrySkillIcon[] — Icons is the list of icons for the skill.
      - `label` string — Label is the label of the icon.
      - `size` string — Size is the size of the icon.
      - `src` string — Src is the source of the icon.
      - `type` string — Type is the type of the icon.
    - `license` string — License is the SPDX license identifier of the skill.
    - `metadata` object — Metadata is the official metadata of the skill as reported in the SKILL.md file.
    - `name` string — Name is the name of the skill. The format is that of identifiers, e.g. "my-skill".
    - `namespace` string — Namespace is the namespace of the skill. The format is reverse-DNS, e.g. "io.github.user".
    - `packages` RegistrySkillPackage[] — Packages is the list of packages for the skill.
      - `commit` string — Commit is the commit of the package.
      - `digest` string — Digest is the digest of the package.
      - `identifier` string — Identifier is the OCI identifier of the package.
      - `mediaType` string — MediaType is the media type of the package.
      - `ref` string — Ref is the reference of the package.
      - `registryType` string — RegistryType is the type of registry the package is from. Can be "oci" or "git".
      - `subfolder` string — Subfolder is the subfolder of the package.
      - `url` string — URL is the URL of the package.
    - `provenance` RegistryProvenance — Provenance is the expected signer identity for this skill, checked on first install instead of trust-on-first-use. Absent means unconstrained — most catalog entries won't have this for a while, and that must not break installs; it's an opt-in tightening per entry, not a requirement. Each field constrains independently, and an empty string leaves that dimension unconstrained. Attestation is the exception: setting it at all, even to an empty struct, requires the artifact to be attested, so verification fails against a signature carrying no statement. Its own PredicateType and Predicate then follow the usual rule and constrain only when set. Predicate must be a JSON object; anything else can never match, and Validate rejects it rather than letting it through as a constraint that silently fails every artifact.
      - `attestation` RegistryVerifiedAttestation
        - `predicate` unknown
        - `predicate_type` string
      - `cert_issuer` string
      - `repository_ref` string
      - `repository_uri` string
      - `runner_environment` string
      - `signer_identity` string
      - `sigstore_url` string
    - `repository` RegistrySkillRepository — Repository is the source repository of the skill.
      - `type` string — Type is the type of the repository.
      - `url` string — URL is the URL of the repository.
    - `status` string — Status is the status of the skill. Can be one of "active", "deprecated", or "archived".
    - `title` string — Title is the title of the skill. This is for human consumption, not an identifier.
    - `version` string — Version is the version of the skill. Any non-empty string is valid, but ideally it should be either a semantic version or a commit hash.

## Other responses

- `500` — Internal server error
- `503` — Registry authentication required or upstream registry unavailable

## Changes

- **2026-08-27** `5ba8236d7c1c` — 1 info
  - added the optional property `skills/items/provenance` to the response with the `200` status
- **2026-04-14** `ca11af4c8248` — 1 info
  - endpoint added
- **2026-01-29** `ff6ce8dd8f3a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/stacklok/apis/toolhive-api/changes/registry/:registryName/v0.1/x/dev.toolhive/skills/get.md)

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/e9f942effcda/schema)