The hubskillz CLI

The CLI inventories every skill in ~/.claude/skills and in each repo’s .claude/skills, then uploads that layout to your directory, the way a git push sends your files to GitHub. It never writes a local file: your repos are the source of truth.

Last updated: September 1, 2026

Install

Node 22 required. Install it once, or run every command through npx.

npm i -g hubskillz
npx hubskillz <command>
hubskillz help [command]

Sign in

Create a device token in Settings, Device tokens, then paste it when the CLI asks. Device tokens

hubskillz login [--token TOKEN] [--base-url URL]
hubskillz logout

Flags of hubskillz login
Flag	What it does
--token TOKEN	Device token, instead of the prompt.
--base-url URL	Server to talk to. Defaults to the config file, then https://api.hubskillz.com.

Self-hosted? Pass --base-url or set HUBSKILLZ_BASE_URL. The CLI keeps its settings in ~/.hubskillz/config.json.

In CI or a container, set HUBSKILLZ_TOKEN instead of signing in: no file is written. hubskillz logout removes the stored token.

Commands

Every command and what it touches. hubskillz help <command> prints the same reference in your terminal.

The hubskillz commands
Command	What it does
status	Reports the state of every installed skill. Reads only.
sync	Uploads the skills as they are, like a git push.
upgrade	Updates skills.sh skills to their latest upstream.
doctor	Reports what an agent fails to load in your skills roots.
move	Moves a skill between the global root and a repo.
publish	Lists an approved skill on your public page, or takes it off.
push	Uploads a skill folder to the directory as a draft.
projects	Records the repos that sync --all and status cover.

status

Check the state

hubskillz status [--path DIR] [--yes]

Scans the .claude/skills of the current directory (or --path DIR), falls back to ~/.claude/skills, then prints one line per skill: state, installed hash, approved version. Reads only.

Flags of hubskillz status
Flag	What it does
--path DIR	Project directory. Defaults to the current directory.
-y, --yes	Answers yes to the questions the command asks.

sync

Upload your skills

hubskillz sync [--path DIR] [--all] [--yes]

Sends the skills as they sit on disk and prints their state, like a git push: the directory mirrors the machine. It never writes a local file.

A skill the directory does not know yet is added to it automatically: a skills.sh skill is pinned at the installed version, a private skill is created from the copy the CLI sent with the inventory. In a team org that step is for maintainers; other roles get a notice and the sync continues.

Flags of hubskillz sync
Flag	What it does
--path DIR	Project directory. Defaults to the current directory.
--all	Covers the global root, this project and every registered project.
-y, --yes	Answers yes to the questions the command asks.

upgrade

Update from skills.sh

hubskillz upgrade [SKILL...] [--path DIR] [--all] [--yes]

Brings every skill installed by npx skills add up to its latest upstream. hubskillz reads each skills.sh lock to find them, then runs npx skills update in each root, which keeps that lock correct.

What hubskillz adds is the list of roots: skills update covers one scope per run, and only knows the current directory. A named skill is looked up in every root, and a name no lock lists is an error.

It installs upstream head, whatever version the directory pinned. The next sync reports the new versions to the directory, where you review and approve them.

Flags of hubskillz upgrade
Flag	What it does
--path DIR	Project directory. Defaults to the current directory.
--all	Covers the global root, this project and every registered project.
-y, --yes	Answers yes to the questions the command asks.

doctor

Check the machine

hubskillz doctor [--path DIR]

Reads every local skills root and reports what no agent loads, and what loads twice: a folder with no SKILL.md, an empty folder, a symlink whose target is gone, a SKILL.md with no description, a project copy that duplicates or shadows ~/.claude/skills, the same skill in several repos, a registered repo that lost its .claude/skills. It never calls the server, so it runs before you sign in. Every line names the command that clears it.

Flags of hubskillz doctor
Flag	What it does
--path DIR	Project directory. Defaults to the current directory.

move

Move a skill

hubskillz move <skill> <global|DIR> [--from global|DIR] [--force]

Moves one skill folder between ~/.claude/skills and a repo. The destination is global or a project directory. move finds the source itself, in the current project then in the global root, and --from picks the copy when the name exists twice. A symlinked folder moves as a link, so its target stays where it is. When the destination already holds the same files, move removes the spare copy instead.

Flags of hubskillz move
Flag	What it does
--from ROOT	Which copy to move when the name exists in both roots.
--force	Replaces a skill of the same name at the destination.

publish

Share a skill on your page

hubskillz publish <skill>
hubskillz unpublish <skill>

publish lists an approved skill on your public page at hubskillz.com/@handle, where anyone can read and install it. unpublish takes it off. The skill keeps its place in the directory either way. Same toggle as the button on the skill page in the app.

push

Push a draft

hubskillz push <skill-dir> [-m MESSAGE]

Uploads one skill folder to the directory as a new draft version. A maintainer reviews it from there.

Flags of hubskillz push
Flag	What it does
-m, --message TEXT	Note attached to the draft.

projects

hubskillz projects [add|remove [DIR] | discover [--yes] | list]

Records the current directory (or DIR) so sync --all and status cover it from anywhere. discover scans your home directory for repos with .claude/skills and lets you pick which ones to register (--yes takes them all). The first sync --all or status with nothing registered runs that scan for you. A registered path without .claude/skills is skipped with a note.

Flags of hubskillz projects
Flag	What it does
-y, --yes	Answers yes to the questions the command asks.

Global flags

Every command takes these.

Flags of hubskillz
Flag	What it does
--base-url URL	Server to talk to. Defaults to the config file, then https://api.hubskillz.com.
-h, --help	Shows the usage of a command.
-v, --version	Prints the version.

Environment

Read at startup, after a flag on the command line and before ~/.hubskillz/config.json.

Environment variables the CLI reads
Variable	What it does
HUBSKILLZ_TOKEN	Device token. Set it in CI or a container and skip hubskillz login: no file is written.
HUBSKILLZ_BASE_URL	Server to talk to, for a self-hosted instance.
NO_COLOR	Drops the colors and the bold from the output.

States

status and sync label every skill with one of these six states.

Skill states reported by the CLI
State	Rule
in sync	Installed content matches the approved version.
drifted	Installed content matches an older version of the same skill.
customized	Installed content matches no known version.
missing	Not installed, and one of your teams requires or recommends it.
inherited	~/.claude/skills has it, so Claude Code loads it in every project. The skill counts as already inside the project. A customized copy keeps its own state.
unmanaged	Installed, and the directory has no skill with that name.