hubskillz 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jérôme Desmares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,41 +1,69 @@
 # hubskillz
 
-Keep the Claude Code skills on your machine in sync with your organization's approved catalog.
+[![npm](https://img.shields.io/npm/v/hubskillz)](https://www.npmjs.com/package/hubskillz)
+[![CI](https://github.com/JejeDurden2/hubskillz/actions/workflows/ci.yml/badge.svg)](https://github.com/JejeDurden2/hubskillz/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/hubskillz)](https://github.com/JejeDurden2/hubskillz/blob/main/LICENSE)
+
+Keep the Claude Code skills on your machine in sync with your organization's approved directory.
+
+`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.
 
 ## Install
 
 ```sh
 npm i -g hubskillz
-# or run without installing
-npx hubskillz --help
+# or without installing
+npx hubskillz help
 ```
 
 Requires Node 22 or newer.
 
+## Quickstart
+
+```sh
+hubskillz login        # paste a device token from Settings, Device tokens
+hubskillz status       # what is installed, and how it compares
+hubskillz sync --all   # install the approved set, adopt what the directory lacks
+```
+
+The bare `hubskillz` command prints this quickstart, with your progress, until the first sync completes.
+
 ## Commands
 
 ```
-hubskillz login  [--base-url URL]
-hubskillz status [--path DIR]
-hubskillz sync   [--path DIR] [--all] [--yes] [--dry-run] [--force]
-hubskillz push   <skill-dir> [-m MESSAGE]
+hubskillz login    [--token TOKEN] [--base-url URL]
+hubskillz logout
+hubskillz status   [--path DIR] [--yes]
+hubskillz sync     [--path DIR] [--all] [--adopt] [--yes] [--dry-run] [--force]
+hubskillz push     <skill-dir> [-m MESSAGE]
+hubskillz projects [add|remove [DIR] | discover [--yes] | list]
+hubskillz help     [command]
 hubskillz --version
 ```
 
+Every command accepts `--help`.
+
 ### login
 
-Prompts for a device token (create one in the web app at `/app/settings/tokens`), verifies it against the server and writes it to the config file.
+Prompts for a device token (create one in the web app at `/app/settings/tokens`), verifies it against the server and writes it to the config file. `--token` skips the prompt. When stdin is a pipe, the token is read from it.
+
+### logout
+
+Removes the config file, so the token and the registered projects.
 
 ### status
 
-Scans the local skills root, sends the inventory (names and content hashes only, never file contents) and prints the state of every skill: `synced`, `drifted`, `customized`, `missing` or `unmanaged`.
+Scans the global root and every registered project (running `projects discover` first when none is registered), sends each inventory and prints the state of every skill: `synced`, `drifted`, `customized`, `missing` or `unmanaged`. Reads only.
+
+What the inventory contains: for every skill, its name, content hash and per-file hashes and sizes. Skills installed from skills.sh (found in the lock file) travel as hashes only, the server fetches their content upstream. Private skills (no upstream) also ship the content of their files, up to 200,000 characters per skill, so the web app can adopt them into the directory. The server keeps that snapshot with the installation and replaces it on every new inventory.
 
 ### sync
 
 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`.
 
 - `--path DIR`: project directory to act on. Default: the current directory.
-- `--all`: act on the global root and the project root. Default: the project root when `DIR/.claude/skills` exists, else the global root.
+- `--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.
+- `--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.
 - `--yes`, `-y`: apply without asking.
 - `--dry-run`: print the plan and stop.
 - `--force`: overwrite locally customized skills.
@@ -44,13 +72,45 @@ Installs missing skills and updates drifted ones to the approved version. Shows
 
 Uploads a skill directory as a draft version for review. `-m`, `--message` attaches a message to the draft.
 
+### projects
+
+Registers repos so `sync --all` and `status` cover them from anywhere, in one run. `add` records the current directory (or `DIR`), which must contain `.claude/skills`; `remove` forgets it; `list` prints them; `discover` scans your home directory (three levels deep, skipping `node_modules`, `.git`, `Library` and hidden folders) for repos with `.claude/skills` and lets you pick which ones to register, `--yes` registers them all. Without a TTY the prompt selects everything. A registered path that no longer has a skills root is skipped with a note.
+
 ## Surfaces
 
 - Global root: `~/.claude/skills`
 - Project root: `<project>/.claude/skills`
 
+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.
+
+## CI and containers
+
+Set `HUBSKILLZ_TOKEN` and no config file is needed:
+
+```sh
+HUBSKILLZ_TOKEN=... npx hubskillz sync --all --yes
+```
+
+Prompts are skipped when stdin is not a TTY: `sync` needs `--yes` to apply, `projects discover` registers everything found.
+
 ## Configuration
 
-`~/.hubskillz/config.json` stores `{ "baseUrl", "token", "machineId" }`. It is written by `login`.
+| Source                     | What                                                                                                                                                                                    |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `~/.hubskillz/config.json` | `{ "baseUrl", "token", "machineId", "projects", "firstSyncAt" }`, mode `0600`. `login` writes it, `hubskillz projects` edits `projects`, the first completed `sync` sets `firstSyncAt`. |
+| `HUBSKILLZ_TOKEN`          | Device token. Takes precedence over the file.                                                                                                                                           |
+| `HUBSKILLZ_BASE_URL`       | Server URL for self-hosted instances.                                                                                                                                                   |
+| `NO_COLOR`                 | Disables colours. Colours are also off when stdout is not a TTY.                                                                                                                        |
+
+The server URL resolves in this order: `--base-url` flag, `HUBSKILLZ_BASE_URL`, the config file, then `https://hubskillz.com`.
+
+## Exit codes
+
+`0` on success, `1` on any failure. The failure is one line on stderr, prefixed with `hubskillz:`.
+
+## Links
 
-The server URL resolves in this order: `--base-url` flag, `HUBSKILLZ_BASE_URL` environment variable, the config file, then `https://hubskillz.com`.
+- Docs: https://hubskillz.com/docs/cli
+- Changelog: https://github.com/JejeDurden2/hubskillz/blob/main/CHANGELOG.md
+- Issues: https://github.com/JejeDurden2/hubskillz/issues
+- License: MIT

package/dist/index.js

@@ -19,6 +19,14 @@ function contentHash(files) {
   return hash2.digest("hex");
 }
 
+// ../shared/src/cli/skill-file.ts
+var BINARY = /\.(png|jpe?g|gif|webp|svg|ico|pdf|zip|gz|tar|woff2?|ttf|otf|mp[34]|wav|bin|exe|dylib|so)$/i;
+var SKIPPED = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function isSkillFile(path) {
+  const segments = path.split("/");
+  return !segments.some((s) => s.startsWith(".") || SKIPPED.has(s)) && !BINARY.test(path);
+}
+
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -14550,10 +14558,12 @@ var skillFilePathSchema = external_exports.string().min(1).max(200).refine(
 var MAX_FILES_PER_SKILL = 100;
 var MAX_FILE_CONTENT_CHARS = 2e5;
 var MAX_SKILLS_PER_REQUEST = 500;
+var MAX_SNAPSHOT_CHARS = MAX_FILE_CONTENT_CHARS;
 var inventoryFileSchema = external_exports.object({
   path: skillFilePathSchema,
   hash: external_exports.string().min(1),
-  size: external_exports.number().int().nonnegative()
+  size: external_exports.number().int().nonnegative(),
+  content: external_exports.string().max(MAX_FILE_CONTENT_CHARS).optional()
 });
 var skillFileSchema = external_exports.object({
   path: skillFilePathSchema,
@@ -14631,6 +14641,11 @@ var approvedSkillSchema = external_exports.object({
 var approvedResponseSchema = external_exports.object({
   skills: external_exports.array(approvedSkillSchema)
 });
+var adoptRequestSchema = external_exports.object({ surfaceId: external_exports.string().min(1) });
+var adoptResponseSchema = external_exports.object({
+  adopted: external_exports.array(external_exports.string()),
+  skipped: external_exports.array(external_exports.object({ name: external_exports.string(), code: external_exports.string() }))
+});
 var draftRequestSchema = external_exports.object({
   name: skillNameSchema,
   files: external_exports.array(skillFileSchema).min(1).max(MAX_FILES_PER_SKILL),
@@ -14744,7 +14759,7 @@ async function apiRequest(request) {
     const message = decodeBody(text, apiErrorSchema)?.message ?? `${response.status} ${response.statusText}`;
     return Result.fail(
       new CliError(
-        response.status === 401 ? "UNAUTHORIZED" : "HTTP",
+        response.status === 401 ? "UNAUTHORIZED" : response.status === 403 ? "FORBIDDEN" : "HTTP",
         `${request.method} ${request.path} failed: ${message}`
       )
     );
@@ -14767,14 +14782,18 @@ function decodeBody(text, schema) {
 
 // src/config.ts
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, hostname as hostname3 } from "node:os";
 import { join } from "node:path";
 var DEFAULT_BASE_URL = "https://hubskillz.com";
 var configSchema = external_exports.object({
   baseUrl: external_exports.string().min(1),
   token: external_exports.string().min(1),
-  machineId: external_exports.string().min(1)
+  machineId: external_exports.string().min(1),
+  /** Absolute repo paths that `--all` includes next to the global root. */
+  projects: external_exports.array(external_exports.string()).default([]),
+  /** ISO date of the first completed `sync`. Absent until then: the quickstart shows. */
+  firstSyncAt: external_exports.string().optional()
 });
 function configDir() {
   return join(homedir(), ".hubskillz");
@@ -14783,16 +14802,30 @@ function configPath() {
   return join(configDir(), "config.json");
 }
 async function readConfig() {
+  const envToken = process.env["HUBSKILLZ_TOKEN"];
   let raw;
   try {
     raw = await readFile(configPath(), "utf8");
   } catch {
+    if (envToken !== void 0 && envToken !== "") {
+      return Result.ok({
+        baseUrl: resolveBaseUrl(void 0),
+        token: envToken,
+        machineId: hostname3(),
+        projects: []
+      });
+    }
     return Result.fail(
       new CliError("NOT_SIGNED_IN", "Not signed in. Run `hubskillz login`.")
     );
   }
-  const parsed = configSchema.safeParse(JSON.parse(raw));
-  if (!parsed.success) {
+  let parsed = null;
+  try {
+    parsed = configSchema.safeParse(JSON.parse(raw));
+  } catch {
+    parsed = null;
+  }
+  if (parsed === null || !parsed.success) {
     return Result.fail(
       new CliError(
         "BAD_CONFIG",
@@ -14800,7 +14833,17 @@ async function readConfig() {
       )
     );
   }
-  return Result.ok(parsed.data);
+  return Result.ok(
+    envToken === void 0 || envToken === "" ? parsed.data : { ...parsed.data, token: envToken }
+  );
+}
+async function deleteConfig() {
+  try {
+    await rm(configPath());
+    return true;
+  } catch {
+    return false;
+  }
 }
 async function writeConfig(config2) {
   await mkdir(configDir(), { recursive: true, mode: 448 });
@@ -14913,6 +14956,66 @@ async function readAll(stream) {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
+function parseSelection(answer, count) {
+  const text = answer.trim().toLowerCase();
+  if (text === "" || text === "all" || text === "a") {
+    return Array.from({ length: count }, (_, index) => index);
+  }
+  if (text === "none" || text === "n") return [];
+  const picked = /* @__PURE__ */ new Set();
+  for (const token of text.split(/[\s,]+/u)) {
+    const index = Number(token) - 1;
+    if (Number.isInteger(index) && index >= 0 && index < count) {
+      picked.add(index);
+    }
+  }
+  return [...picked].sort((left, right) => left - right);
+}
+async function selectMany(question, choices) {
+  if (process.stdin.isTTY !== true) return choices;
+  process.stdout.write(`${question}
+`);
+  choices.forEach((choice, index) => {
+    process.stdout.write(`  ${index + 1}. ${choice}
+`);
+  });
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Select [all]: ");
+    const picked = new Set(parseSelection(answer, choices.length));
+    return choices.filter((_, index) => picked.has(index));
+  } finally {
+    rl.close();
+  }
+}
+
+// src/quickstart.ts
+function quickstart(config2) {
+  const signedIn = config2.isSuccess;
+  const synced = signedIn && config2.value.firstSyncAt !== void 0;
+  const step = (done, text, command) => `  ${done ? dim("[x]") : "[ ]"} ${done ? dim(text) : text}
+      ${dim("$")} ${done ? dim(command) : bold(command)}
+`;
+  return `${bold("Quickstart")}
+` + step(
+    signedIn,
+    "Sign in with a device token (create one under Settings, Device tokens)",
+    "hubskillz login"
+  ) + step(
+    synced,
+    "See what is installed on this machine and how it compares to the directory",
+    "hubskillz status"
+  ) + step(
+    synced,
+    "Install the approved set everywhere, adopt what the directory lacks",
+    "hubskillz sync --all"
+  ) + `
+${dim("Run `hubskillz help` for every command, `hubskillz help <command>` for its flags.")}
+`;
+}
+function quickstartPending(config2) {
+  return config2.isFailure || config2.value.firstSyncAt === void 0;
+}
 
 // src/commands/login.ts
 async function login(options) {
@@ -14921,9 +15024,12 @@ async function login(options) {
     options.baseUrl,
     existing.isSuccess ? existing.value.baseUrl : void 0
   );
-  process.stdout.write(`${dim(`Signing in to ${baseUrl}`)}
-`);
-  const token = await promptSecret("Device token: ");
+  process.stdout.write(
+    `${dim(`Signing in to ${baseUrl}`)}
+${dim(`Create a device token at ${baseUrl}/app/settings/tokens`)}
+`
+  );
+  const token = options.token ?? await promptSecret("Device token: ");
   if (token === "") {
     return Result.fail(new CliError("EMPTY_TOKEN", "No device token given."));
   }
@@ -14934,19 +15040,51 @@ async function login(options) {
     schema: meResponseSchema
   });
   if (me.isFailure) return Result.fail(me.error);
-  await writeConfig({ baseUrl, token, machineId: await machineId() });
+  const config2 = {
+    baseUrl,
+    token,
+    machineId: await machineId(),
+    projects: existing.isSuccess ? existing.value.projects : []
+  };
+  if (existing.isSuccess && existing.value.firstSyncAt !== void 0) {
+    config2.firstSyncAt = existing.value.firstSyncAt;
+  }
+  await writeConfig(config2);
   process.stdout.write(
     `Signed in as ${me.value.user.email} on ${me.value.org.name}.
 ${dim(`Token written to ${configPath()}`)}
+
 `
   );
+  if (config2.firstSyncAt === void 0) {
+    process.stdout.write(quickstart(Result.ok(config2)));
+  }
   return Result.ok(void 0);
 }
 
+// src/commands/logout.ts
+async function logout() {
+  const removed = await deleteConfig();
+  process.stdout.write(
+    removed ? `Signed out. ${dim(`Removed ${configPath()}`)}
+` : `${dim("Not signed in.")}
+`
+  );
+  return Result.ok(void 0);
+}
+
+// src/commands/projects.ts
+import { resolve as resolve4 } from "node:path";
+
+// src/discover.ts
+import { readdir as readdir2 } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { join as join4, resolve as resolve3 } from "node:path";
+
 // src/scan.ts
 import { createHash as createHash2 } from "node:crypto";
 import { readdir, readFile as readFile3, realpath, stat } from "node:fs/promises";
-import { homedir as homedir3, hostname as hostname3 } from "node:os";
+import { homedir as homedir3, hostname as hostname4 } from "node:os";
 import { basename, dirname, join as join3, resolve as resolve2 } from "node:path";
 
 // src/lock.ts
@@ -14992,7 +15130,6 @@ async function readLock(path) {
 }
 
 // src/scan.ts
-var SKIPPED_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
 function globalSkillsRoot() {
   return join3(homedir3(), ".claude", "skills");
 }
@@ -15000,10 +15137,10 @@ function projectSkillsRoot(dir) {
   return join3(resolve2(dir), ".claude", "skills");
 }
 function globalSurfaceLabel() {
-  return hostname3();
+  return hostname4();
 }
 function projectSurfaceLabel(dir) {
-  return `${hostname3()}:${basename(resolve2(dir))}`;
+  return `${hostname4()}:${basename(resolve2(dir))}`;
 }
 async function exists(path) {
   try {
@@ -15050,7 +15187,7 @@ async function scanSkills(root) {
   }
   const skills = [];
   for (const entry of entries) {
-    if (entry.name.startsWith(".") || SKIPPED_DIRS.has(entry.name)) continue;
+    if (!isSkillFile(entry.name)) continue;
     const dir = join3(root, entry.name);
     const symlink = entry.isSymbolicLink();
     if (!entry.isDirectory() && !(symlink && await isDir(dir))) continue;
@@ -15080,9 +15217,9 @@ async function walk(dir, prefix, visited) {
   let link = false;
   const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
   for (const entry of entries) {
-    if (entry.name.startsWith(".") || SKIPPED_DIRS.has(entry.name)) continue;
     const full = join3(dir, entry.name);
     const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (!isSkillFile(relative)) continue;
     const symlink = entry.isSymbolicLink();
     if (entry.isDirectory() || symlink && await isDir(full)) {
       const nested = await walk(full, relative, visited);
@@ -15092,7 +15229,9 @@ async function walk(dir, prefix, visited) {
     }
     if (!entry.isFile() && !symlink) continue;
     const content = await readFile3(full, "utf8").catch(() => null);
-    if (content === null) continue;
+    if (content === null || content.includes("\0") || content.length > MAX_FILE_CONTENT_CHARS) {
+      continue;
+    }
     files.push({
       path: relative,
       content,
@@ -15109,14 +15248,19 @@ function inventoryRequestOf(surface) {
   return {
     surface: surface.descriptor,
     skills: surface.skills.map((skill) => {
+      const snapshot = skill.upstream === void 0 && skill.files.reduce((sum, file2) => sum + file2.content.length, 0) <= MAX_SNAPSHOT_CHARS;
       const item = {
         name: skill.name,
         contentHash: skill.contentHash,
-        files: skill.files.map((file2) => ({
-          path: file2.path,
-          hash: file2.hash,
-          size: file2.size
-        }))
+        files: skill.files.map((file2) => {
+          const entry = {
+            path: file2.path,
+            hash: file2.hash,
+            size: file2.size
+          };
+          if (snapshot) entry.content = file2.content;
+          return entry;
+        })
       };
       if (skill.upstream !== void 0) item.upstream = skill.upstream;
       return item;
@@ -15124,6 +15268,120 @@ function inventoryRequestOf(surface) {
   };
 }
 
+// src/discover.ts
+var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "Library", ".Trash", ".cache"]);
+async function discoverProjects(roots = [homedir4()], maxDepth = 3) {
+  const found = /* @__PURE__ */ new Set();
+  const walk2 = async (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = await readdir2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (!entry.isDirectory() || SKIP.has(name)) continue;
+      if (name.startsWith(".") && name !== ".claude") continue;
+      const child = join4(dir, name);
+      if (name === ".claude" && depth > 0) {
+        if (await exists(projectSkillsRoot(dir))) found.add(dir);
+        continue;
+      }
+      await walk2(child, depth + 1);
+    }
+  };
+  for (const root of roots) await walk2(resolve3(root), 0);
+  return [...found].sort();
+}
+
+// src/commands/projects.ts
+async function discoverAndRegister(config2, yes) {
+  const known = new Set(config2.projects);
+  const found = (await discoverProjects()).filter((dir) => !known.has(dir));
+  if (found.length === 0) {
+    process.stdout.write(dim("No new project with .claude/skills found.\n"));
+    return config2.projects;
+  }
+  const chosen = yes ? found : await selectMany("Projects with skills found. Register:", found);
+  if (chosen.length === 0) return config2.projects;
+  const projects2 = [...config2.projects, ...chosen];
+  await writeConfig({ ...config2, projects: projects2 });
+  process.stdout.write(
+    `Registered ${chosen.length} project${chosen.length === 1 ? "" : "s"}. They are now part of \`hubskillz sync --all\`.
+`
+  );
+  return projects2;
+}
+async function projects(options) {
+  const config2 = await readConfig();
+  if (config2.isFailure) return Result.fail(config2.error);
+  const current = config2.value.projects;
+  const dir = resolve4(options.dir ?? process.cwd());
+  switch (options.action ?? "list") {
+    case "list": {
+      if (current.length === 0) {
+        process.stdout.write(
+          dim(
+            "No registered projects. Run `hubskillz projects add` inside a repo.\n"
+          )
+        );
+        return Result.ok(void 0);
+      }
+      for (const project of current) process.stdout.write(`${project}
+`);
+      return Result.ok(void 0);
+    }
+    case "add": {
+      if (!await exists(projectSkillsRoot(dir))) {
+        return Result.fail(
+          new CliError(
+            "NO_SKILLS_ROOT",
+            `${dir} has no .claude/skills directory.`
+          )
+        );
+      }
+      if (current.includes(dir)) {
+        process.stdout.write(dim(`${dir} is already registered.
+`));
+        return Result.ok(void 0);
+      }
+      await writeConfig({ ...config2.value, projects: [...current, dir] });
+      process.stdout.write(
+        `Registered ${dir}. It is now part of \`hubskillz sync --all\`.
+`
+      );
+      return Result.ok(void 0);
+    }
+    case "discover": {
+      await discoverAndRegister(config2.value, options.yes);
+      return Result.ok(void 0);
+    }
+    case "remove": {
+      if (!current.includes(dir)) {
+        return Result.fail(
+          new CliError("NOT_REGISTERED", `${dir} is not registered.`)
+        );
+      }
+      await writeConfig({
+        ...config2.value,
+        projects: current.filter((project) => project !== dir)
+      });
+      process.stdout.write(`Forgot ${dir}.
+`);
+      return Result.ok(void 0);
+    }
+    default:
+      return Result.fail(
+        new CliError(
+          "USAGE",
+          `hubskillz projects: unknown action "${options.action}". Use add, remove, discover or list.`
+        )
+      );
+  }
+}
+
 // src/commands/push.ts
 async function push(options) {
   const config2 = await readConfig();
@@ -15163,18 +15421,44 @@ ${dim(`skill ${draft.value.skillId} version ${draft.value.versionId}`)}
 }
 
 // src/surfaces.ts
-async function localSurfaces(path, both, machineId2) {
-  const projectDir = path ?? process.cwd();
+import { resolve as resolve5 } from "node:path";
+async function localSurfaces(path, both, machineId2, registered = []) {
+  const projectDir = resolve5(path ?? process.cwd());
   const projectRoot = projectSkillsRoot(projectDir);
   const hasProject = await exists(projectRoot);
-  const project = async () => scanSurface(projectRoot, projectSurfaceLabel(projectDir), machineId2);
+  const project = async (dir) => scanSurface(projectSkillsRoot(dir), projectSurfaceLabel(dir), machineId2);
   const global = async () => scanSurface(globalSkillsRoot(), globalSurfaceLabel(), machineId2);
-  if (both) {
-    const surfaces = [await global()];
-    if (hasProject || path !== void 0) surfaces.push(await project());
-    return surfaces;
+  if (!both) return [hasProject ? await project(projectDir) : await global()];
+  const surfaces = [await global()];
+  const dirs = projectDirs(
+    hasProject || path !== void 0 ? projectDir : void 0,
+    registered
+  );
+  for (const dir of dirs) {
+    if (await exists(projectSkillsRoot(dir))) {
+      surfaces.push(await project(dir));
+      continue;
+    }
+    process.stdout.write(
+      dim(
+        `skipping ${dir}: no .claude/skills here, run \`hubskillz projects remove ${dir}\` to forget it
+`
+      )
+    );
   }
-  return [hasProject ? await project() : await global()];
+  return surfaces;
+}
+function projectDirs(current, registered) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const dir of [current, ...registered]) {
+    if (dir === void 0) continue;
+    const abs = resolve5(dir);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
 }
 
 // src/commands/status.ts
@@ -15185,16 +15469,22 @@ async function status(options) {
     baseUrl: resolveBaseUrl(options.baseUrl, config2.value.baseUrl),
     token: config2.value.token
   };
+  const projects2 = config2.value.projects.length === 0 ? await discoverAndRegister(config2.value, options.yes) : config2.value.projects;
   const surfaces = await localSurfaces(
     options.path,
     true,
-    config2.value.machineId
+    config2.value.machineId,
+    projects2
   );
   for (const surface of surfaces) {
     const inventory = await postInventory(session, surface);
     if (inventory.isFailure) return Result.fail(inventory.error);
     printSurface(surface, inventory.value);
   }
+  if (quickstartPending(config2)) {
+    process.stdout.write(`
+${quickstart(config2)}`);
+  }
   return Result.ok(void 0);
 }
 async function postInventory(session, surface) {
@@ -15212,57 +15502,58 @@ function originOf(surface, name) {
   return skill.upstream === void 0 ? "private" : `skills.sh ${skill.upstream.source}`;
 }
 function printNotes(surface, items) {
-  for (const item of items) {
-    if (item.importable) {
-      process.stdout.write(
-        `${item.name}: not in directory yet (${originOf(surface, item.name)}), add it from the web app
+  const importable = items.filter((item) => item.importable).map((item) => item.name);
+  if (importable.length > 0) {
+    process.stdout.write(
+      `${dim(`${importable.length} not in the directory yet, run npx hubskillz sync to adopt them:`)} ${importable.join(", ")}
 `
-      );
-    }
-    if (item.upstreamAhead === true) {
-      process.stdout.write(
-        `${item.name}: upstream ahead of approved version, waiting for review
+    );
+  }
+  const ahead = items.filter((item) => item.upstreamAhead === true).map((item) => `${item.name} (${originOf(surface, item.name)})`);
+  if (ahead.length > 0) {
+    process.stdout.write(
+      `${dim("upstream ahead of approved version, waiting for review:")} ${ahead.join(", ")}
 `
-      );
-    }
+    );
   }
 }
-function printSurface(surface, inventory) {
-  const links = new Set(
-    surface.skills.filter((skill) => skill.link).map((skill) => skill.name)
+function printHeader(surface) {
+  process.stdout.write(
+    `
+${bold(surface.descriptor.label)}  ${dim(surface.descriptor.path)}
+`
   );
+}
+function printSurface(surface, inventory) {
   const rows = inventory.items.map((item) => [
-    links.has(item.name) ? `${item.name} ${dim("(link)")}` : item.name,
+    item.name,
     originOf(surface, item.name),
     item.required ? `${item.state} ${dim("(required)")}` : item.state,
     shortHash(item.installedHash),
     item.approvedVersion === void 0 ? "-" : `v${item.approvedVersion}`
   ]);
-  process.stdout.write(
-    `
-${bold(surface.descriptor.label)} ${dim(surface.descriptor.path)}
-`
-  );
+  printHeader(surface);
   if (rows.length === 0) {
     process.stdout.write(`${dim("no skills")}
 `);
     return;
   }
   process.stdout.write(
-    `${table(["SKILL", "ORIGIN", "STATE", "INSTALLED", "APPROVED"], rows)}
+    `${table(["SKILL", "ORIGIN", "STATE", "LOCAL", "APPROVED"], rows)}
+
 `
   );
   printNotes(surface, inventory.items);
 }
 
 // src/commands/sync.ts
-import { lstat, readdir as readdir2, realpath as realpath2 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { join as join5, resolve as resolve3, sep as sep2 } from "node:path";
+import { lstat, readdir as readdir3, realpath as realpath2 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { join as join6, resolve as resolve6, sep as sep2 } from "node:path";
 
 // src/apply.ts
-import { mkdir as mkdir2, mkdtemp, rename, rm, rmdir, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname2, join as join4, sep } from "node:path";
+import { mkdir as mkdir2, mkdtemp, rename, rm as rm2, rmdir, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname2, join as join5, sep } from "node:path";
 async function applySkill(input) {
   for (const path of [...input.files.map((f) => f.path), ...input.remove]) {
     if (!isSafeRelativePath(path)) {
@@ -15275,25 +15566,25 @@ async function applySkill(input) {
     }
   }
   await mkdir2(input.dir, { recursive: true });
-  const staging = await mkdtemp(join4(dirname2(input.dir), ".hubskillz-"));
+  const staging = await mkdtemp(join5(dirname2(input.dir), ".hubskillz-"));
   try {
     for (const file2 of input.files) {
-      const staged = join4(staging, ...file2.path.split("/"));
+      const staged = join5(staging, ...file2.path.split("/"));
       await mkdir2(dirname2(staged), { recursive: true });
       await writeFile2(staged, file2.content, "utf8");
     }
     for (const file2 of input.files) {
-      const target = join4(input.dir, ...file2.path.split("/"));
+      const target = join5(input.dir, ...file2.path.split("/"));
       await mkdir2(dirname2(target), { recursive: true });
-      await rename(join4(staging, ...file2.path.split("/")), target);
+      await rename(join5(staging, ...file2.path.split("/")), target);
     }
     for (const path of input.remove) {
-      const target = join4(input.dir, ...path.split("/"));
-      await rm(target, { force: true });
+      const target = join5(input.dir, ...path.split("/"));
+      await rm2(target, { force: true });
       await pruneEmptyDirs(dirname2(target), input.dir);
     }
   } finally {
-    await rm(staging, { recursive: true, force: true });
+    await rm2(staging, { recursive: true, force: true });
   }
   return Result.ok(void 0);
 }
@@ -15372,21 +15663,35 @@ async function sync(options) {
     baseUrl: resolveBaseUrl(options.baseUrl, config2.value.baseUrl),
     token: config2.value.token
   };
+  const projects2 = options.all && config2.value.projects.length === 0 ? await discoverAndRegister(config2.value, options.yes) : config2.value.projects;
   const surfaces = await localSurfaces(
     options.path,
     options.all,
-    config2.value.machineId
+    config2.value.machineId,
+    projects2
   );
   for (const surface of surfaces) {
     const result = await syncSurface(session, surface, options);
     if (result.isFailure) return result;
   }
+  if (!options.dryRun && config2.value.firstSyncAt === void 0 && process.env["HUBSKILLZ_TOKEN"] === void 0) {
+    const stored = await readConfig();
+    if (stored.isSuccess && stored.value.firstSyncAt === void 0) {
+      await writeConfig({
+        ...stored.value,
+        projects: [...projects2],
+        firstSyncAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+  }
   return Result.ok(void 0);
 }
 async function syncSurface(session, surface, options) {
-  const inventory = await postInventory(session, surface);
+  const first = await postInventory(session, surface);
+  if (first.isFailure) return Result.fail(first.error);
+  const surfaceId = first.value.surfaceId;
+  const inventory = await maybeAdopt(session, surface, first.value, options);
   if (inventory.isFailure) return Result.fail(inventory.error);
-  const surfaceId = inventory.value.surfaceId;
   const approved = await apiRequest({
     session,
     method: "GET",
@@ -15401,18 +15706,8 @@ async function syncSurface(session, surface, options) {
     local: surface.skills,
     force: options.force
   });
-  process.stdout.write(
-    `
-${bold(surface.descriptor.label)} ${dim(surface.descriptor.path)}
-`
-  );
-  printPlan(plans, surface);
-  for (const skill of blocked) {
-    process.stdout.write(
-      `${skill.name}: blocked by org policy (${skill.blockedReason ?? "no reason given"})
-`
-    );
-  }
+  printHeader(surface);
+  printPlan(plans, blocked, surface);
   printNotes(surface, inventory.value.items);
   if (options.dryRun || !planHasWrites(plans)) return Result.ok(void 0);
   if (!options.yes && !await confirm("Apply?")) {
@@ -15430,6 +15725,44 @@ ${bold(surface.descriptor.label)} ${dim(surface.descriptor.path)}
   if (reposted.isFailure) return Result.fail(reposted.error);
   return clearPending(session, surfaceId);
 }
+async function maybeAdopt(session, surface, inventory, options) {
+  const importable = inventory.items.filter((item) => item.importable);
+  if (importable.length === 0 || options.dryRun) return Result.ok(inventory);
+  const wanted = options.adopt || !options.yes && await confirm(
+    `Adopt ${plural(importable.length)} found here as approved in your directory?`
+  );
+  if (!wanted) return Result.ok(inventory);
+  const adopted = await apiRequest({
+    session,
+    method: "POST",
+    path: "/api/cli/adopt",
+    schema: adoptResponseSchema,
+    body: { surfaceId: inventory.surfaceId }
+  });
+  if (adopted.isFailure && adopted.error.code === "FORBIDDEN") {
+    process.stdout.write(
+      `${dim("not adopted: ask a maintainer to adopt these skills")}
+`
+    );
+    return Result.ok(inventory);
+  }
+  if (adopted.isFailure) return Result.fail(adopted.error);
+  const names = adopted.value.adopted;
+  process.stdout.write(
+    names.length === 0 ? `${dim("nothing adopted")}
+` : `adopted ${plural(names.length)} as approved: ${names.join(", ")}
+`
+  );
+  for (const skip of adopted.value.skipped) {
+    process.stdout.write(dim(`skipped ${skip.name} (${skip.code})
+`));
+  }
+  if (adopted.value.adopted.length === 0) return Result.ok(inventory);
+  return postInventory(session, surface);
+}
+function plural(n) {
+  return `${n} skill${n === 1 ? "" : "s"}`;
+}
 async function applyPlan(surface, plans, approved) {
   for (const plan of plans) {
     if (plan.action !== "install" && plan.action !== "update") continue;
@@ -15458,12 +15791,12 @@ async function applyPlan(surface, plans, approved) {
   return Result.ok(void 0);
 }
 async function writeTarget(root, name) {
-  const dir = join5(root, name);
+  const dir = join6(root, name);
   const stats = await lstat(dir).catch(() => null);
   if (stats === null || !stats.isSymbolicLink()) return Result.ok(dir);
   const target = await realpath2(dir).catch(() => null);
-  const home = await realpath2(homedir4()).catch(() => homedir4());
-  if (target === null || !isInside(target, home) || isInside(target, await realpath2(root).catch(() => resolve3(root)))) {
+  const home2 = await realpath2(homedir5()).catch(() => homedir5());
+  if (target === null || !isInside(target, home2) || isInside(target, await realpath2(root).catch(() => resolve6(root)))) {
     return Result.fail(
       new CliError(
         "UNSAFE_LINK",
@@ -15474,7 +15807,7 @@ async function writeTarget(root, name) {
   return Result.ok(target);
 }
 async function containsSymlink(dir) {
-  const entries = await readdir2(dir, {
+  const entries = await readdir3(dir, {
     recursive: true,
     withFileTypes: true
   }).catch(() => []);
@@ -15502,104 +15835,273 @@ async function clearPending(session, surfaceId) {
   }
   return Result.ok(void 0);
 }
-function printPlan(plans, surface) {
-  if (plans.length === 0) {
+function printPlan(plans, blocked, surface) {
+  const rows = [
+    ...plans.map((plan) => [
+      plan.action,
+      plan.name,
+      originOf(surface, plan.name),
+      `v${plan.version}`,
+      detailOf(plan)
+    ]),
+    ...blocked.map((skill) => [
+      accent("blocked"),
+      skill.name,
+      originOf(surface, skill.name),
+      `v${skill.version}`,
+      `org policy: ${skill.blockedReason ?? "no reason given"}`
+    ])
+  ];
+  if (rows.length === 0) {
     process.stdout.write(`${dim("nothing to sync")}
+
 `);
     return;
   }
-  const rows = plans.map((plan) => [
-    plan.action,
-    plan.name,
-    originOf(surface, plan.name),
-    `v${plan.version}`,
-    diffSummary(plan)
-  ]);
   process.stdout.write(
     `${table(["ACTION", "SKILL", "ORIGIN", "VERSION", "FILES"], rows)}
 `
   );
   for (const plan of plans) {
+    if (plan.action !== "update") continue;
     for (const [marker, paths] of [
       ["+", plan.added],
       ["~", plan.changed],
       ["-", plan.removed]
     ]) {
-      if (plan.action === "keep" || plan.action === "skip") continue;
       for (const path of paths) {
-        process.stdout.write(`  ${marker} ${plan.name}/${path}
-`);
+        process.stdout.write(dim(`  ${marker} ${plan.name}/${path}
+`));
       }
     }
   }
-  const skipped = plans.filter((plan) => plan.action === "skip");
-  if (skipped.length > 0) {
-    process.stdout.write(
-      `${accent("warning")}: customized locally, left untouched: ${skipped.map((plan) => plan.name).join(", ")}. Use --force to overwrite.
+  const counts = [
+    [plans.filter((plan) => plan.action === "install").length, "to install"],
+    [plans.filter((plan) => plan.action === "update").length, "to update"],
+    [plans.filter((plan) => plan.action === "keep").length, "up to date"],
+    [plans.filter((plan) => plan.action === "skip").length, "skipped"],
+    [blocked.length, "blocked"]
+  ];
+  process.stdout.write(
+    `${counts.filter(([n]) => n > 0).map(([n, label]) => `${n} ${label}`).join(", ")}
+
 `
-    );
-  }
+  );
 }
-function diffSummary(plan) {
+function detailOf(plan) {
   if (plan.action === "keep") return dim("up to date");
-  if (plan.action === "skip") return dim("customized");
+  if (plan.action === "skip") {
+    return `${accent("customized locally")}, use --force to overwrite`;
+  }
+  if (plan.action === "install") return `+${plan.added.length}`;
   return `+${plan.added.length} ~${plan.changed.length} -${plan.removed.length}`;
 }
 
 // src/index.ts
-var USAGE = `hubskillz - keep your agent skills in sync
+var GLOBAL_FLAGS = [
+  {
+    spec: "--base-url URL",
+    help: "Server to talk to (default: config file, then https://hubskillz.com)"
+  },
+  { spec: "-h, --help", help: "Show help" },
+  { spec: "-v, --version", help: "Show the version" }
+];
+var COMMANDS = [
+  {
+    name: "login",
+    usage: "hubskillz login [--token TOKEN] [--base-url URL]",
+    summary: "Sign in with a device token",
+    flags: [
+      { spec: "--token TOKEN", help: "Device token, instead of the prompt" }
+    ]
+  },
+  {
+    name: "logout",
+    usage: "hubskillz logout",
+    summary: "Forget the device token on this machine",
+    flags: []
+  },
+  {
+    name: "status",
+    usage: "hubskillz status [--path DIR] [--yes]",
+    summary: "Report the state of every installed skill",
+    flags: [
+      {
+        spec: "--path DIR",
+        help: "Project directory (default: current directory)"
+      },
+      {
+        spec: "-y, --yes",
+        help: "Register every discovered project without asking"
+      }
+    ]
+  },
+  {
+    name: "sync",
+    usage: "hubskillz sync [--path DIR] [--all] [--adopt] [--yes] [--dry-run] [--force]",
+    summary: "Install and update skills to the approved versions",
+    flags: [
+      {
+        spec: "--path DIR",
+        help: "Project directory (default: current directory)"
+      },
+      {
+        spec: "--all",
+        help: "Global root, this project and every registered project"
+      },
+      {
+        spec: "--adopt",
+        help: "Add importable skills to the directory as approved (maintainers)"
+      },
+      { spec: "-y, --yes", help: "Apply without asking" },
+      { spec: "--dry-run", help: "Print the plan and stop" },
+      { spec: "--force", help: "Overwrite skills you customized locally" }
+    ]
+  },
+  {
+    name: "push",
+    usage: "hubskillz push <skill-dir> [-m MESSAGE]",
+    summary: "Upload a skill directory as a draft for review",
+    flags: [{ spec: "-m, --message TEXT", help: "Note attached to the draft" }]
+  },
+  {
+    name: "projects",
+    usage: "hubskillz projects [add|remove [DIR] | discover [--yes] | list]",
+    summary: "Repos that `sync --all` and `status` cover",
+    flags: [{ spec: "-y, --yes", help: "discover: register everything found" }]
+  }
+];
+function flagLines(flags) {
+  const width = Math.max(...flags.map((flag) => flag.spec.length));
+  return flags.map((flag) => `  ${flag.spec.padEnd(width)}  ${dim(flag.help)}
+`).join("");
+}
+function usage() {
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  return `${bold("hubskillz")} ${dim(`v${"0.2.0"}`)}  keep your agent skills in sync
+
+${bold("Usage")}
+  hubskillz <command> [flags]
 
-  hubskillz login [--base-url URL]
-  hubskillz status [--path DIR]
-  hubskillz sync [--path DIR] [--all] [--yes] [--dry-run] [--force]
-  hubskillz push <skill-dir> [-m MESSAGE]
-  hubskillz --version
+${bold("Commands")}
+` + COMMANDS.map(
+    (command) => `  ${command.name.padEnd(width)}  ${dim(command.summary)}
+`
+  ).join("") + `
+${bold("Flags")}
+${flagLines(GLOBAL_FLAGS)}
+${dim("Environment: HUBSKILLZ_TOKEN, HUBSKILLZ_BASE_URL, NO_COLOR. Docs: https://hubskillz.com/docs/cli")}
 `;
+}
+function commandHelp(command) {
+  const flags = [...command.flags, ...GLOBAL_FLAGS];
+  return `${bold("Usage")}
+  ${command.usage}
+
+${command.summary}.
+
+${bold("Flags")}
+${flagLines(flags)}`;
+}
+function help(name) {
+  if (name === void 0) {
+    process.stdout.write(usage());
+    return Result.ok(void 0);
+  }
+  const command = COMMANDS.find((entry) => entry.name === name);
+  if (command === void 0) {
+    return Result.fail(
+      new CliError(
+        "USAGE",
+        `Unknown command "${name}". Run \`hubskillz help\`.`
+      )
+    );
+  }
+  process.stdout.write(commandHelp(command));
+  return Result.ok(void 0);
+}
+async function home() {
+  const config2 = await readConfig();
+  process.stdout.write(
+    quickstartPending(config2) ? `${usage()}
+${quickstart(config2)}` : usage()
+  );
+  return Result.ok(void 0);
+}
 async function run() {
-  const { values, positionals } = parseArgs({
-    args: process.argv.slice(2),
-    allowPositionals: true,
-    options: {
-      "base-url": { type: "string" },
-      path: { type: "string" },
-      all: { type: "boolean", default: false },
-      yes: { type: "boolean", short: "y", default: false },
-      "dry-run": { type: "boolean", default: false },
-      force: { type: "boolean", default: false },
-      message: { type: "string", short: "m" },
-      help: { type: "boolean", short: "h", default: false },
-      version: { type: "boolean", short: "v", default: false }
-    }
-  });
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args: process.argv.slice(2),
+      allowPositionals: true,
+      options: {
+        "base-url": { type: "string" },
+        token: { type: "string" },
+        path: { type: "string" },
+        all: { type: "boolean", default: false },
+        adopt: { type: "boolean", default: false },
+        yes: { type: "boolean", short: "y", default: false },
+        "dry-run": { type: "boolean", default: false },
+        force: { type: "boolean", default: false },
+        message: { type: "string", short: "m" },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false }
+      }
+    }));
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return Result.fail(
+      new CliError("USAGE", `${detail}
+Run \`hubskillz help\` for usage.`)
+    );
+  }
   if (values.version === true) {
-    process.stdout.write(`${"0.1.0"}
+    process.stdout.write(`${"0.2.0"}
 `);
     return Result.ok(void 0);
   }
   const command = positionals[0];
-  if (values.help === true || command === void 0) {
-    process.stdout.write(USAGE);
-    return Result.ok(void 0);
+  if (command === void 0)
+    return values.help === true ? help(void 0) : home();
+  if (values.help === true || command === "help") {
+    return help(command === "help" ? positionals[1] : command);
   }
   switch (command) {
     case "login":
-      return login({ baseUrl: values["base-url"] });
+      return login({ baseUrl: values["base-url"], token: values.token });
+    case "logout":
+      return logout();
     case "status":
-      return status({ baseUrl: values["base-url"], path: values.path });
+      return status({
+        baseUrl: values["base-url"],
+        path: values.path,
+        yes: values.yes === true
+      });
     case "sync":
       return sync({
         baseUrl: values["base-url"],
         path: values.path,
         all: values.all === true,
+        adopt: values.adopt === true,
         yes: values.yes === true,
         dryRun: values["dry-run"] === true,
         force: values.force === true
       });
+    case "projects":
+      return projects({
+        action: positionals[1],
+        dir: positionals[2],
+        yes: values.yes === true
+      });
     case "push": {
       const dir = positionals[1];
       if (dir === void 0) {
         return Result.fail(
-          new CliError("USAGE", "hubskillz push needs a skill directory.")
+          new CliError(
+            "USAGE",
+            "hubskillz push needs a skill directory. Run `hubskillz help push`."
+          )
         );
       }
       return push({
@@ -15610,8 +16112,10 @@ async function run() {
     }
     default:
       return Result.fail(
-        new CliError("USAGE", `Unknown command "${command}".
-${USAGE}`)
+        new CliError(
+          "USAGE",
+          `Unknown command "${command}". Run \`hubskillz help\`.`
+        )
       );
   }
 }

package/package.json

@@ -1,21 +1,36 @@
 {
   "name": "hubskillz",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keep your Claude Code skills in sync with your organization's approved catalog.",
   "license": "MIT",
+  "author": "Jérôme Desmares",
+  "homepage": "https://hubskillz.com/docs/cli",
   "repository": {
     "type": "git",
     "url": "https://github.com/JejeDurden2/hubskillz",
     "directory": "packages/cli"
   },
-  "keywords": ["claude-code", "skills", "cli", "agent", "sync"],
+  "bugs": {
+    "url": "https://github.com/JejeDurden2/hubskillz/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skills",
+    "agent-skills",
+    "cli",
+    "sync",
+    "skills.sh"
+  ],
   "type": "module",
   "bin": {
     "hubskillz": "./dist/index.js"
   },
   "main": "./dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=22"
@@ -23,19 +38,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@types/node": "^26.3.0",
+    "esbuild": "0.28.2",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3",
+    "@hubskillz/shared": "0.0.1"
+  },
   "scripts": {
     "dev": "pnpm build --watch",
     "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --alias:@hubskillz/shared=../shared/src/index.ts --outfile=dist/index.js --define:__VERSION__=\"'$npm_package_version'\" && chmod +x dist/index.js",
     "lint": "oxlint src/",
     "type-check": "tsc --noEmit",
     "test": "vitest run"
-  },
-  "devDependencies": {
-    "@hubskillz/shared": "workspace:*",
-    "@types/node": "^26.3.0",
-    "esbuild": "0.28.2",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "zod": "^4.4.3"
   }
-}
+}