The skillpass CLI

Search the directory, inspect passports, and install skills - every install verified byte-for-byte against the validated snapshot before anything touches disk.

Install

npm install -g skillpass

Node 20 or newer. Zero runtime dependencies.

Find: search

skillpass search pdf
skillpass search --packs
skillpass search --target codex --category security-review
skillpass search --ai "turn a video into an article"

Searches the same fields as the website (names, summaries, authors, tools, pack members).--ai searches by meaning through the directory's free AI search, in relevance order, with the same filters. --json emits machine output; piped output is always plain and grep-friendly.

Inspect: report

skillpass report pdf
skillpass report pdf@1.0.0 --json

Prints the version's Skill Passport before you install anything: status, risk, declared vs detected permissions, the permission diff against the previous version, and the pinned source hash. Failed versions are blocked from download.

Author: init

skillpass init my-skill

Scaffolds ./my-skill/ with a SKILL.md and a skill.json that pass the validator as written, then scans it so you see the passport status and risk before you write a line. In a terminal it asks for a description and the permissions the skill will need, and declares them in skill.json; thepermission taxonomy explains each one. It never overwrites an existing folder.

Validate: scan

skillpass scan ./my-skill

Runs the same validator the directory uses on a local folder - check your own skill beforesubmitting it.

Install: add

skillpass add pdf --target claude-code                  # .claude/skills/pdf (project)
skillpass add pdf --target claude-code --global         # ~/.claude/skills/pdf
skillpass add pdf --target cursor                       # .agents/skills/pdf, the shared folder
skillpass add pdf --target claude-code --target agents  # both folders, one pre-flight
skillpass add pdf --dir ./somewhere                     # anywhere you point it
skillpass add ai-blueprint --target codex                # a pack: every member installs

--target takes claude-code, cline, or agents, the shared.agents/skills folder that Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and OpenCode all read (their names work too and land in the same place). --global switches to the tool's user-level folder. Repeat --target to install into several tools at once. The per-agent guides show each tool's folders and command on one page.

The pre-flight report shows first; medium+ risk asks for confirmation; the download re-verifies against the pinned hash; writes are atomic. With no flags in a terminal you get an interactive location picker. Installing a pack fans every member skill out into the tool's skills area using that tool's variant files.

Not running the CLI yourself? Every skill page has a Prompt tab beside the command: paste it into your agent and it runs this same install, pre-flight first, and stops for you when the risk is medium or higher.

Install from any repo

skillpass add github:owner/repo --target claude-code          # the repo root is the skill (or a pack)
skillpass add github:owner/repo/skills/pdf --target cursor    # one folder of a monorepo
skillpass add github:owner/repo@v1.2.0 --target claude-code   # pin a branch, tag, or commit
skillpass add https://github.com/owner/repo/tree/main/skills/pdf --target agents

A skill does not have to be on the directory to go through the gate. The CLI pins the reference to a commit, downloads that commit's archive from GitHub, runs the same validator on it locally, and shows the same pre-flight: status, risk, permissions, findings, and source hash, plus the repo and commit it came from. A failed report blocks the install and medium+ risk asks for confirmation, then the same atomic install path runs with every flag, pack fan-out, and the location picker.

These installs are unlisted: validated on your machine, never submitted or listed, with no maintainer ownership check and no AI review behind them. The receipt records the repo and commit and marks the install unlisted, so list shows the origin, outdated leaves it out of the update count, and update refuses it rather than replace it with a same-named directory skill. To refresh one,remove it and add it again. Public repositories only; add github:... never contacts the directory.

Run once: use

claude "$(skillpass use pdf)"      # open Claude Code with the skill loaded
skillpass use pdf@1.0.0 > prompt.txt  # or save the prompt

Runs a skill once without installing it. The same pre-flight as add runs first: failed versions are blocked and medium or higher risk asks for a yes (or --yes). The verified files are unpacked to a temp folder, and the command prints a prompt (the skill's instructions plus where its files are) on stdout, so it pipes cleanly. The report and the question go to stderr. Nothing goes into a skills folder and no receipt is written. Packs and github: references are not supported; use add for those.

Track: list and outdated

skillpass list        # installed skills with versions, offline
skillpass outdated    # compares to the directory; exits 1 when updates exist

Installs into the known skills areas are recorded in a per-area .skillpass.jsonreceipt. Your own hand-made skills in the same folders are left alone - the CLI only tracks what it installed.

Update

skillpass update pdf
skillpass update pdf@1.0.0     # pinning works for downgrades too
skillpass update ai-blueprint  # packs: members swap, new ones add, dropped ones remove

An update re-runs the whole trust gate and shows the permission diff against the version you actually have installed - not just the previous publish. The swap is atomic: a failure mid-replace restores what you had. Unlisted installs are refused here; remove and add them again instead.

Remove

skillpass remove pdf
skillpass remove ai-blueprint   # removes the whole pack family

Refuses anything that does not look like an installed skill, so a stray --dir can never wipe a real folder.

Configuration and exit codes

SKILLPASS_API - override the API base URL (defaults to the public API).
NO_COLOR - disable colored output; piped output is always plain.
Exit codes: 0 success, 1 failed validation or a blocked version (for outdated: updates available), 2 usage, network, or refused operations.