Skip to main content

Build a skill from a local folder

The Local Builds tab on the Skills page lets you turn a folder on your machine into an OCI artifact you can install into your AI clients, share with teammates, or push to a registry later. Use it to develop skills iteratively without leaving the app.

Prerequisites​

Open the Local Builds tab​

Open Skills from the menu bar, then select the Local Builds tab.

When the local store is empty, the tab shows an empty state with a single Build skill button. Once you've built at least one artifact, the tab also shows a search input, a card/table view toggle, and a Build skill button in the top-right corner.

Build a skill​

Click Build skill to open the Build skill dialog and fill in:

  1. Path [Required]
    The absolute path to the folder that contains your SKILL.md. You can:

    • Click the folder icon to open the native OS folder picker.
    • Paste or type a path directly into the field.

    ToolHive validates the path against the file system. If the folder doesn't exist, you'll see a Folder does not exist error under the field and the build is not dispatched.

    Hidden folders

    The native folder picker on macOS and Windows hides dot-folders such as .agents or .claude by default. If your skill lives inside one of those, paste the absolute path directly into the Path field instead of using the picker.

  2. Tag [Optional]
    The OCI tag to apply to the build, for example ghcr.io/my-org/skills/my-skill:v1.0.0 or my-skill:latest. If you leave it blank, ToolHive uses a default tag derived from the skill name.

Click Build to package the folder. ToolHive validates the skill contents (a SKILL.md with name and description, no symlinks or path traversal), creates an OCI artifact in the local store, and records the build so it appears in the tab.

If validation fails, an error message stays inline in the dialog so you can correct the input without losing your typed values.

Install a build right away​

A successful build shows a toast with an Install now action. Click it to open the Install skill dialog with the reference pre-filled with the local build tag, then follow the steps in Browse and install skills.

You can also install a build later from the Local Builds tab or from the build's detail page.

View build details​

Click any row or card in the Local Builds tab to open the build detail page. The layout matches the registry skill detail page:

  • Left: the build name, version (or a latest badge when no version is set), tag, digest (truncated with a hover tooltip showing the full hash), an Install action, and a Remove action.
  • Right: the rendered SKILL.md content. ToolHive strips the YAML frontmatter from the rendered body, since the same fields already appear in the summary panel.

Click the Back button to return to the Local Builds tab.

List and remove local builds​

The Local Builds tab shows every artifact you've built locally:

  • In card view, each build card displays the name, version or latest badge, tag, and a truncated digest, with Install and Remove actions in the footer.
  • In table view, columns include Build, Version, Digest, About, and the same Install + Remove actions per row.

Use the search input to filter the list by tag, name, or digest.

To remove an artifact, click Remove on any row, card, or detail page and confirm the dialog. ToolHive deletes the artifact from the local OCI store. When multiple tags share the same digest, the underlying blobs are retained until every tag pointing to that digest is removed. Removing a build from the detail page redirects you back to the Local Builds list.

Push a local build to a remote registry​

Pushing local OCI artifacts to a remote container registry is currently a command-line operation. Once you've built a skill in the UI, switch to a terminal and run:

thv skill push <TAG>

For details, including authenticating with the remote registry, see Push to a registry.

Next steps​