Skills
Skills are folders with a SKILL.md (and sometimes scripts) that a coding tool loads: yours from
~/.claude/skills/<name>/, a project's from <project>/.claude/skills/<name>/. Claude Code reads both, and so does
OpenCode (it also reads ~/.agents/skills, which hoprig workspace link points at the brain's skills). A skill is
instructions an AI agent follows with your permissions, so taking one is like installing software from the internet. Hoprig
suggests skills that fit a project, finds others, and installs one only after you have seen it.
One command or two taps
hoprig skills suggest # what fits this project, and why ("package.json has next 16.0.1")
hoprig skills add <id> # fetch → review → yes → installed
In the dashboard: Skills, pick the project under Skills for:, open Suggested, Review on a suggestion, read it, Install.
Commands
| Command | What it does |
|---|---|
skills list [--project <dir>] [--offline] | installed skills: name, description, source and commit, "update available", "edited here" |
skills find <words> | the built-in catalog and the public skills.sh search, with installs and license |
skills suggest [dir] | reads the project's manifests (no AI) and proposes catalog skills with the reason |
skills add <spec> [--project <dir> | --user] [--yes] | <spec>: a catalog id, owner/repo[/path], owner/repo@skill, a GitHub URL, or any git URL with #path |
skills approve <review id> | install a review printed earlier when no terminal could ask |
skills update [name] [--check] [--overwrite-local] | newer versions: the diff and the scan again, then a yes per skill; also the tools below |
skills undo <name> | back to the version before the last update or removal (and again: forward) |
skills rm <name> [--yes] | remove (kept for undo) |
skills tools [--update <id>] | command-line tools catalog skills need: installed and latest version, the exact update command |
How a skill is taken
- Fetched into quarantine (
<state>/skillhub/quarantine/<id>), never straight into a skills folder: plaingit, one commit, only that commit's tree and the skill folder's files. No hooks, no submodules, no LFS filters. Nothing from the skill runs, at any step. - Reviewed: every file with its size and kind (text, script, binary, link), the full
SKILL.md, the license, the source and commit, and a scan that points at risky lines: downloading and running (curl … | sh), commands Claude Code runs when the skill loads (!`…`), reading credentials or.env, recursive deletes, start-up files, network calls, encoded blobs, hidden Unicode, instructions to ignore rules, to hide things from you or to send data away,allowed-toolsandhooksin the front matter. A link out of the folder, a setuid file, an unsafe name or a missingSKILL.mdblocks the install. The scan cannot prove a skill safe; it makes the lines worth reading easy to find. - Approved once.
--yesis accepted only for catalog entries at their reviewed commit (and the bundled skill). Anything else needs you to read it. - Installed: the files are checked against the review again (changed since? nothing is installed), staged
next to the skills folder and swapped in with a rename.
.hoprig-skills.jsonnext to the skills records the source, commit, the git tree of the skill folder and a SHA-256 per file.
Updates
skills update --check asks the source for its newest commit and compares the git tree of the skill's folder,
so a repository that moved without touching the skill is "up to date". An update shows what changed (files added,
removed, changed, and the changed lines), the scan again with new findings marked, and waits for a yes per skill.
A skill you edited is never replaced silently: the update says what you changed and needs --overwrite-local
(the edited version is kept for undo). The dashboard can check once a week (Skills → Advanced); it only
tells you (a notification and a badge), it never installs.
The catalog
src/skillhub/catalog.json lists skills that were opened and read before they were listed, each pinned to the
commit that was read, with what it is for, its license and the signals that make it relevant
(npm:next, pub:flutter, stack:web, artifact:apk, file:docker, always). One entry is bundled: the
hoprig skill in templates/skills/hoprig, which teaches Claude Code to use Hoprig; its version is the
package's and it is offered first for every project, for you (--user). To add an entry: read the skill at a
commit, add the entry with that full commit id, and run the tests (they validate the catalog).
What leaves the computer
git ls-remote/git fetchto the skill's host (GitHub for catalog entries).find: the words tohttps://skills.sh/api/search(the same search theskillsCLI uses;SKILLS_API_URLchanges it), and the repository names of the results toapi.github.comfor their license.- Tools: the package name to the npm registry (
npm view <package> version).
The skills CLI (npx skills) itself is not used: it needs Node 22.20+, links skills from ~/.agents, sends
telemetry unless turned off, and has no quarantine review. Skills it installed are listed with the source from
its lock file.
For the guided first run
hoprig setup runs this as its skills part (INSTALL.md): for the project chosen in the same
run, or, without one, the skill that comes with Hoprig. hoprig setup --only skills runs it again.
src/skillhub/hub.mjs exports:
skillsStatus({ project?, check = true })→{ user: { dir, installed, suggested }, project: { root, dir, installed, suggested, ideas } | null, updates: [{ scope, name, latest, edited }], checked }runSkillsStep({ ui, project, yes, dryRun })→{ ok, added, skipped };uiis{ say(line), confirm(question) → Promise<boolean> }. One review and one question per suggested skill; withyes, only bundled or catalog-pinned entries are added.