Reference

CLI reference

Every command of the skills command line, its options, credential handling and exit codes.

skills is the command-line client of the registry. It validates and packs locally with the same code the server uses, and it never executes anything from a package.

Getting it

The CLI is a single dependency-free JavaScript file for Node.js 20 or newer. It is not yet published to npm; download it from the registry and verify it:

curl -fsSLO https://skills.spboucher.ai/cli/skills.mjs
curl -fsSL https://skills.spboucher.ai/cli/skills.mjs.sha256 | shasum -a 256 -c -
chmod +x skills.mjs && mv skills.mjs ~/.local/bin/skills   # any directory on your PATH
skills --version

From a checkout of the registry repository you can also run pnpm skills <command> (from source) or pnpm cli:build (rebuilds the bundle).

The registry URL must be https://; plain http:// is accepted only for localhost and 127.0.0.1.

Global options

Option	Meaning
`--registry <url>`	Registry to talk to. Default `https://skills.spboucher.ai`; also `SKILLS_REGISTRY`
`--json`	Machine-readable output
`--yes`	Answer confirmations affirmatively. Use only after a human approved

Exit codes: 0 success · 1 error · 2 validation failed · 3 authentication or authorization problem.

Credentials

Lookup order:

SKILLS_TOKEN environment variable (process-scoped use; do not export it in a profile).
OS credential store — macOS Keychain, service skills-registry, account = registry host; secret-tool on Linux.
~/.config/skills/credentials.json with mode 0600, only when you opted in with --insecure-file.

The CLI never prints a stored token.

Command	What it does
`skills login [--token-stdin] [--insecure-file]`	Reads a token from a hidden prompt or standard input, checks it against the registry, stores it
`skills logout`	Removes the stored credential for this registry
`skills whoami`	Identity, scopes, namespaces and expiry of the current credential
`skills auth status`	Whether a credential is stored, where, for which registry, and whether it is still valid

Tokens

Command	What it does
`skills auth token create --name N --scopes a,b --namespace ns [--expires-in 90d] [--ip CIDR] [--store]`	Creates a token. Prints it once, or with `--store` saves it as the current credential without printing. Needs `tokens:write`; cannot grant more than the calling credential holds
`skills auth token list` (alias `skills token list`)	Lists your tokens: name, prefix, scopes, namespaces, expiry, status. Needs `tokens:read`
`skills auth token revoke <id\|prefix> [--yes]`	Revokes a token. The current token can always revoke itself
`skills auth token rotate [<id\|prefix>] [--yes]`	New secret, same grants; the old token stops working at once. Without an argument, rotates the current credential, stores the replacement and prints nothing

Durations: 30m, 12h, 90d. Maximum 366 days. Scopes are listed in the API reference.

Authoring

Command	What it does
`skills init [dir] --type <type> --name @ns/slug`	Creates a starter package with `agent-registry.json` and the entry file for the type
`skills validate <dir>`	Runs every local check and prints findings. Exit code 2 if any is blocking
`skills pack <dir> [-o file]`	Writes the deterministic `.tar.gz` and prints its SHA-256 and size

Files skipped when packing: .git, node_modules, .DS_Store, Thumbs.db, __pycache__, .venv, .idea, .vscode, anything matched by .skillsignore, and every symbolic link.

.skillsignore takes one pattern per line: a name (notes.txt), a directory (drafts/), a path from the package root (/data/raw), or a * wildcard within one path segment (*.csv). Lines starting with # are comments.

Publishing

skills publish <dir> [--visibility public|unlisted|private] [--dry-run] [--yes] [--notes TEXT | --notes-file F]

Collects and validates the directory. Stops on blocking findings.
Prints the report: target @ns/slug, version, visibility, files and sizes, skipped files, declared permissions, findings, archive SHA-256 and size.
With --dry-run, stops here. Nothing is uploaded and no credential is needed for local checks.
Creates the artifact if it does not exist. A public artifact, or a change of visibility, asks for confirmation.
Begins the upload, sends the archive, finalizes.
Verifies the published checksum and prints the URL, version and state.

If the server quarantines the release for review, the CLI says so; the release is not public yet.

Command	What it does
`skills deprecate @ns/slug --reason "…" [--yes]`	Marks the artifact deprecated with a public reason. Needs `artifacts:deprecate`
`skills revoke @ns/slug@<version> --reason "…" [--yes]`	Revokes a version permanently. Needs `releases:revoke`

Discovering

Command	What it does
`skills search "<query>" [--type t] [--client c]`	Full-text search
`skills versions @ns/slug`	Release history with state and checksum
`skills inspect @ns/slug [--version v] [--file path]`	Metadata, permissions, files, findings; with `--file`, prints one text file of the release

Downloading and installing

skills download @ns/slug[@version] [-o file] [--extract dir]
skills install  @ns/slug[@version] --client claude-code|codex|cursor|generic-agent-skills|generic-mcp [--project] [--dir path] [--yes] [--force]
skills update   @ns/slug --client <client> [--project] [--yes]

download fetches the archive, verifies its SHA-256 against the release metadata, and optionally extracts it into a new directory.

install, for skills:

Shows the version, publisher, declared permissions, findings and the destination.
Asks for confirmation.
Downloads, verifies the checksum, re-validates every path.
If the destination exists, stops unless --force is given; an existing copy is first moved to ~/.skills-registry/backups/.
Copies the files and writes .skills-registry.json (name, version, checksum, registry, time).

It never runs a script from the package.

Destinations:

Client	User scope	`--project`
`claude-code`	`~/.claude/skills/<slug>`	`.claude/skills/<slug>`
`codex`	`~/.agents/skills/<slug>`	`.agents/skills/<slug>`
`cursor`	`~/.cursor/skills/<slug>`	`.cursor/skills/<slug>`
`generic-agent-skills`	`~/.agents/skills/<slug>`	`.agents/skills/<slug>`

--dir sets the parent skills directory: the skill is written to <dir>/<slug>, so the folder name always equals the skill name, as the Agent Skills specification requires. update accepts --dir too. For artifact types that are neither a skill nor an MCP server, install prints the matching skills download … --extract command and exits 1, because nothing was installed.

For MCP servers, install prints the configuration for the chosen client and the environment variables to set. It does not start the server.

update installs the current latest over an installed copy after showing what changes, keeping a backup.

Examples

skills search "manuscript review" --type skill --client claude-code
skills inspect @research/citation-check --file SKILL.md
skills install @research/citation-check@1.2.0 --client claude-code --project
skills validate ./citation-check && skills publish ./citation-check --visibility public --dry-run
SKILLS_REGISTRY=http://localhost:8570 skills whoami