Skip to main content

Build a skill from a local folder

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

Prerequisites​

  • A skill directory on your machine that contains a SKILL.md file at its root. See Understanding skills for the required structure and frontmatter.
  • A supported AI client registered with ToolHive if you intend to install the build afterwards. See Client configuration.

Build a skill​

  1. Open Skills from the menu bar, select the Local Builds tab, and click Build skill.

  2. Fill in the Build skill dialog:

    • Path (required) - the absolute path to the folder that contains your SKILL.md. Click the folder icon to use the native OS folder picker, or paste/type a path directly. ToolHive validates the path; if the folder doesn't exist, you'll see a Folder does not exist error and the build won't run.
    • Tag (optional) - the OCI tag to apply to the build, for example my-skill:latest or ghcr.io/my-org/skills/my-skill:v1.0.0. If you leave it blank, ToolHive uses a default tag derived from the skill name.

  3. Click Build. ToolHive validates the contents (a SKILL.md with name and description, no symlinks or path traversal), creates the OCI artifact in your local store, and adds it to the Local Builds tab.

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

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.

Install a build​

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 your build's tag, then follow the steps in Configure the install.

You can also install a build later by clicking Install on its row, card, or detail page.

Remove a build​

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.

Push a build to a remote registry​

Pushing to a remote container registry is currently a CLI-only operation. After building, run:

thv skill push <TAG>

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

Next steps​