Skip to content
CF / PROJECT 02

skill-hub

The package manager for AI agent skills

A package manager that treats agent Skills as versioned, installable packages.

Status
Active
Started
2026
Stack
Go · CLI · AI Agent · Developer Tools
Links
01

Why

Coding agents became part of daily work, and each of them learned to load reusable Skills. The Skills themselves, though, lived as copied folders — in repositories, in home directories, in four different runtime layouts.

Once a Skill is copied, nobody knows which version is running, where it came from, or how to undo a bad change. skill-hub exists to give Skills the lifecycle that code packages already have.

02

Problem

  1. 01

    No single source of truth: the same Skill drifts apart across Codex, Claude, Gemini and Hermes directories.

  2. 02

    No versions or history: an update overwrites a folder and leaves nothing to roll back to.

  3. 03

    No discovery: finding a Skill means already knowing its repository path.

  4. 04

    Unsafe by default: writing straight into an agent's runtime directory changes its behaviour immediately.

03

System

skill-hub separates where a Skill is managed from where an agent loads it. Three layers, each with one job.

  1. L1Registry

    Local or Git-backed indexes (skillhub.index.json, schema v2) that describe what can be installed.

  2. L2Managed store

    Installed packages under $SKILLHUB_HOME, pinned in skillhub.lock with version, checksum, source ref and history. Updates and rollbacks happen here.

  3. L3Runtime copy

    Explicit deploys into the Codex, Claude, Gemini or Hermes skills directory — the only layer an agent actually reads.

04

Implementation

  • One Go binary, plus a TUI

    Setup, registries, discovery, lifecycle, deploy, publishing and audit live in a single CLI, with an interactive skillhub tui on top.

  • Package format

    skill.yaml declares name, namespace, version, entry and targets. Folders with only a SKILL.md still install — skill-hub generates the metadata for them.

  • Lockfile and history

    skillhub.lock records checksums and source refs, so installs are reproducible and rollback always has somewhere to return to.

  • Static catalog

    catalog export writes index.html and catalog.json, so a registry can be browsed without running a server.

  • Distribution

    Released through Homebrew, npm and go install, with an npm tarball attached to every tagged release for pinning or mirroring.

05

Decisions

  1. D1

    Updating never touches the runtime

    skillhub update changes the managed store only. Replacing what an agent loads takes an explicit deploy … --force, so an upgrade can never silently change how an agent behaves.

  2. D2

    Semver is enforced, not suggested

    Patch and minor updates apply automatically. Major bumps and versions marked compatibility.breaking are skipped until you pass --major, and requires.skillhub refuses installs the CLI cannot support.

  3. D3

    Discovered is not adopted

    Skills already sitting in project folders appear in list and the TUI, but are never pulled into the managed store behind your back.

  4. D4

    A registry is just files

    An index in a directory or a Git repository is enough. Sharing Skills inside a team needs no hosted service.

06

Result

Release line
v1.4.x
Runtimes
Codex · Claude · Gemini · Hermes
Install
Homebrew · npm · Go

The v1.4 line added publishing (including a fork-and-PR flow), compatibility enforcement, a confirmation policy for major updates, and a local audit log. The official catalog lives in skill-hub-registry.

Registry signing and trust policy are reserved for v1.5.

GitHub