hubskillz 0.3.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +73 -13
  2. package/dist/index.js +1093 -726
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -4,9 +4,9 @@
4
4
  [![CI](https://github.com/JejeDurden2/hubskillz-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/JejeDurden2/hubskillz-cli/actions/workflows/ci.yml)
5
5
  [![license](https://img.shields.io/npm/l/hubskillz)](https://github.com/JejeDurden2/hubskillz-cli/blob/main/LICENSE)
6
6
 
7
- Keep the Claude Code skills on your machine in sync with your organization's approved directory.
7
+ See every Claude Code skill on your machine in one place, share it, and keep your directory current.
8
8
 
9
- `hubskillz` inventories `~/.claude/skills` and `<repo>/.claude/skills`, reports the state of every skill against the directory, and installs the approved versions after showing you the plan. Skills you customized are never overwritten unless you ask.
9
+ `hubskillz` inventories `~/.claude/skills` and `<repo>/.claude/skills` and 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, the directory is the picture of them.
10
10
 
11
11
  ## Install
12
12
 
@@ -22,8 +22,10 @@ Requires Node 22 or newer.
22
22
 
23
23
  ```sh
24
24
  hubskillz login # paste a device token from Settings, Device tokens
25
+ hubskillz doctor # what is broken or duplicated on this machine
26
+ hubskillz upgrade --all # every skills.sh skill to its latest upstream
25
27
  hubskillz status # what is installed, and how it compares
26
- hubskillz sync --all # install the approved set, adopt what the directory lacks
28
+ hubskillz sync --all # upload every skill of this machine to your directory
27
29
  ```
28
30
 
29
31
  The bare `hubskillz` command prints this quickstart, with your progress, until the first sync completes.
@@ -34,7 +36,12 @@ The bare `hubskillz` command prints this quickstart, with your progress, until t
34
36
  hubskillz login [--token TOKEN] [--base-url URL]
35
37
  hubskillz logout
36
38
  hubskillz status [--path DIR] [--yes]
37
- hubskillz sync [--path DIR] [--all] [--adopt] [--yes] [--dry-run] [--force]
39
+ hubskillz sync [--path DIR] [--all] [--yes]
40
+ hubskillz upgrade [SKILL...] [--path DIR] [--all] [--yes]
41
+ hubskillz doctor [--path DIR]
42
+ hubskillz move <skill> <global|DIR> [--from global|DIR] [--force]
43
+ hubskillz publish <skill>
44
+ hubskillz unpublish <skill>
38
45
  hubskillz push <skill-dir> [-m MESSAGE]
39
46
  hubskillz projects [add|remove [DIR] | discover [--yes] | list]
40
47
  hubskillz help [command]
@@ -59,14 +66,67 @@ What the inventory contains: for every skill, its name, content hash and per-fil
59
66
 
60
67
  ### sync
61
68
 
62
- Installs missing skills and updates drifted ones to the approved version. Shows the plan first and asks for confirmation. Skills you changed locally are left untouched unless you pass `--force`.
69
+ Uploads the skills as they sit on disk and prints their state, like a git push: the directory mirrors the machine. `sync` never writes a local file. A skill the directory does not know yet is added to it automatically: an upstream skill is pinned at its installed hash, a private skill is created from its snapshot. In a team org that step is maintainer only, other roles get a notice and keep syncing.
63
70
 
64
- - `--path DIR`: project directory to act on. Default: the current directory.
65
- - `--all`: act on the global root, the project root and every registered project. With nothing registered yet, it first scans your home directory for repos with `.claude/skills` and asks which ones to register (see `projects discover`). Default: the project root when `DIR/.claude/skills` exists, else the global root.
66
- - `--adopt`: add every importable skill found on this surface to the directory as an approved version, without asking. Importable means installed here and absent from the directory: an upstream skill is pinned at its installed hash, a private skill is created from its snapshot. Maintainer only, other roles get a notice and keep syncing. Without the flag, an interactive run asks the same question once; `--yes` alone answers no and `--dry-run` skips it.
67
- - `--yes`, `-y`: apply without asking.
68
- - `--dry-run`: print the plan and stop.
69
- - `--force`: overwrite locally customized skills.
71
+ - `--path DIR`: project directory to report. Default: the current directory.
72
+ - `--all`: cover the global root, the project root and every registered project. With nothing registered yet, it first scans your home directory for repos with `.claude/skills` and asks which ones to register (see `projects discover`). Default: the project root when `DIR/.claude/skills` exists, else the global root.
73
+ - `--yes`, `-y`: register every discovered project without asking.
74
+
75
+ To change what a repo holds, edit it like any other file and `sync` again: `hubskillz move` carries a skill between roots, `hubskillz upgrade` updates skills.sh skills, deleting the folder removes the skill.
76
+
77
+ ### upgrade
78
+
79
+ Brings every skill installed by `npx skills add` up to its latest upstream.
80
+
81
+ ```sh
82
+ hubskillz upgrade # this project, else the global root
83
+ hubskillz upgrade --all # global root and every registered project
84
+ hubskillz upgrade find-skills # one skill, wherever it lives
85
+ ```
86
+
87
+ hubskillz fetches nothing here. It reads each skills.sh lock to know what is installed, then runs `npx skills update` in each root, which keeps that lock correct. What it adds is the list of roots: `skills update` covers one scope per run and only knows the current directory, while hubskillz knows the global root and every repo you registered with `hubskillz projects`.
88
+
89
+ `upgrade` looks a named skill up in every root, so `hubskillz upgrade find-skills` works from anywhere. A name no lock lists is an error. `--yes` passes `-y` through to skills.sh.
90
+
91
+ This command installs upstream head, whatever version your directory pinned. `hubskillz sync` afterwards reports the new versions to the directory, where you review and approve them.
92
+
93
+ ### doctor
94
+
95
+ Reads every local skills root and reports what no agent loads, and what loads twice. No account needed: it never calls the server.
96
+
97
+ | Level | What it reports |
98
+ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | `error` | A folder with no `SKILL.md`, an empty folder, a symlink whose target is gone. Nothing loads. |
100
+ | `warn` | A `SKILL.md` without a `name` or a `description`, a copy that duplicates or shadows `~/.claude/skills`, the same skill sitting in several projects, a registered repo that lost its `.claude/skills`. |
101
+
102
+ Every warning names what clears it: deleting a redundant project copy, `hubskillz move <skill> global` for a skill repeated across projects, `hubskillz projects remove` for a dead registration.
103
+
104
+ ### move
105
+
106
+ Moves one skill folder between the machine root and a project.
107
+
108
+ ```sh
109
+ hubskillz move find-skills global # project copy goes to ~/.claude/skills
110
+ hubskillz move find-skills . # global copy goes into this repo
111
+ hubskillz move find-skills ~/code/other # into another repo
112
+ ```
113
+
114
+ The destination is `global` or a project directory. `move` finds the source itself, in the project of the working directory then in `~/.claude/skills`, skipping the destination. When the name sits in two other roots, `--from` says which copy to move.
115
+
116
+ A symlinked skill folder (the skills.sh canonical copy under `~/.agents/skills`) moves as a link, so its target stays where it is. When the destination already holds the very same files, `move` removes the spare copy instead. It refuses a destination holding something different unless you pass `--force`.
117
+
118
+ The move is local. Run `hubskillz status` after it to report the new layout.
119
+
120
+ ### publish, unpublish
121
+
122
+ `publish` lists an approved skill on your public page at `hubskillz.com/@handle`, where anyone can read it and install it. `unpublish` takes it off. The skill keeps its place in the directory either way; only your page changes. Same toggle as the button on the skill page in the app.
123
+
124
+ ```sh
125
+ hubskillz publish find-skills
126
+ hubskillz unpublish find-skills
127
+ ```
128
+
129
+ The skill must be approved with a pinned version. Set your handle in the app under Settings before the first publish.
70
130
 
71
131
  ### push
72
132
 
@@ -81,7 +141,7 @@ Registers repos so `sync --all` and `status` cover them from anywhere, in one ru
81
141
  - Global root: `~/.claude/skills`
82
142
  - Project root: `<project>/.claude/skills`
83
143
 
84
- A symlinked skill directory (the skills.sh canonical copy under `~/.agents/skills`) is written through, so every agent on the machine sees the approved version. Links that leave your home directory are refused.
144
+ Claude Code loads the global root in every project on the machine. A skill installed there reports `inherited` on a project surface: it is already inside the project, nothing needs a copy in the repo. A project copy that matches a known version is a redundant shadow of the global one; `doctor` points it out and you delete it when you want.
85
145
 
86
146
  ## CI and containers
87
147
 
@@ -91,7 +151,7 @@ Set `HUBSKILLZ_TOKEN` and no config file is needed:
91
151
  HUBSKILLZ_TOKEN=... npx hubskillz sync --all --yes
92
152
  ```
93
153
 
94
- Prompts are skipped when stdin is not a TTY: `sync` needs `--yes` to apply, `projects discover` registers everything found.
154
+ Prompts are skipped when stdin is not a TTY: `projects discover` registers everything found.
95
155
 
96
156
  ## Configuration
97
157