Skip to main content

Browse and install skills

The Registry tab on the Skills page is your catalog for ready-made agent skills. From there you can search the registry, open a detail page to read what a skill does, and install it into one or more of your AI clients without leaving the app.

Prerequisites​

Browse the registry​

Open Skills from the menu bar, then select the Registry tab.

The catalog shows each skill's name, namespace, description, and an Install action. Use the controls in the top-right corner of the tab to:

  • Search: type in the search box to filter skills server-side. The query is debounced so you don't see results flicker as you type.
  • Switch view: toggle between a card grid and a table. The table view adds an Author column (namespace) on larger viewports.
  • Paginate: registry results are paginated, with 24 entries per page by default. The active page is preserved when you navigate to a detail page and back, so you don't lose your place.

If a search returns no results, the tab shows an empty state inviting you to adjust the query.

View skill details​

Click any skill in the list to open its detail page. The layout has two columns:

  • Left: the skill name, namespace, source repository, version and license badges, a short summary, and the Install action.
  • Right: the rendered SKILL.md content. ToolHive fetches the skill body from the registry and renders it as Markdown, including code blocks, tables, and Mermaid diagrams.

Click the Back button to return to the Registry tab on the page and position you left it on.

Install a skill​

You can start an install in two ways:

  • From the Registry tab, click the Install button (with the + icon) directly on a skill card or table row.
  • From a skill detail page, click Install in the sticky summary panel.

In both cases, ToolHive opens the Install skill dialog with the reference field pre-filled. When you start from a registry skill, the OCI reference and version are split into the appropriate fields automatically.

Configure the install​

The Install skill dialog asks for:

  1. Reference [Required]
    The skill source. ToolHive accepts:

    • A registry name (for example, toolhive-cli-user).
    • A full OCI reference (for example, ghcr.io/<OWNER>/skills/<SKILL_NAME>:<TAG>).
    • A Git URL of the form git://host/owner/repo[@ref][#path/to/skill].

  2. Version [Optional]
    Provided automatically when you start from a registry skill. Leave blank to install the latest version.

  3. Scope [Required]
    Where the skill files are written on disk. Hover the (i) icon to see the inline tooltip:

    • User: installed globally in your home directory and available across all projects.
    • Project: installed in the root of a specific project folder and scoped to that project only.

  4. Project root [Required when scope is Project]
    The absolute path to a Git repository on your machine. ToolHive validates that the folder is a Git repo before installing, so it doesn't drop skill files in arbitrary directories. Use the folder picker or paste a path.

  5. Clients [Optional]
    The AI clients that should receive the skill. The dropdown lists only clients you have installed and that support skills, so you don't pick a target ToolHive can't write to. Select one or more boxes to target a subset.
    Leave the field blank to install for all detected clients. ToolHive sends an empty list to the API, which the server interprets as "every skill-supporting client this user has registered".

Click Install to write the skill files into each selected client's skills directory and record the install in ToolHive's database.

If the install fails, an inline destructive alert appears inside the dialog with the error message returned by the API. Common causes are an invalid reference, a missing version, or a project root that isn't a Git repository.

What's happening?

When you click Install, ToolHive:

  1. Resolves the reference (registry, OCI, or Git).
  2. Downloads and extracts the skill files.
  3. Writes SKILL.md and any supporting files to each selected client's skills directory (for example, ~/.claude/skills/<SKILL_NAME>/ for Claude Code in user scope, or <PROJECT_ROOT>/.claude/skills/... in project scope).
  4. Records the install so you can manage it from the Installed tab.

Your AI client picks up the skill the next time it scans its skills directory.

Next steps​