axiom-skills 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# axiom (CLI)
+
+Two ways to run it — pick one:
+
+```
+npx axiom-skills <command>      # zero install — must be the full package name, "npx axiom ..." resolves to a
+                                 # different, unrelated package (axiomhq's own SDK is published as "axiom")
+npm install -g axiom-skills     # then just: axiom <command>
+```
+
+That distinction matters more than it looks: `npx <name>` fetches the
+package *literally named* `<name>` — it doesn't search for "whichever
+package happens to expose a bin called that." This package's bin is
+named `axiom` for the short form after a global install, but `npx axiom
+...` would try to run the actual, unrelated `axiom` package that's
+already published on npm (axiomhq's own SDK) — so `package.json` also
+exposes a second bin, `axiom-skills`, matching the package's own name,
+specifically so `npx axiom-skills ...` resolves correctly cold.
+
+```
+axiom registry https://registry.acme.dev   # once — no account needed
+axiom find "browser testing"
+axiom add acme/my-skill                     # -> .agents/skills/my-skill/
+axiom add acme/my-skill@1.2.0               # pin a version
+axiom install                               # reproduce a project's exact skill set
+axiom update acme/my-skill                  # or `axiom update` for everything
+axiom list
+
+axiom register --invite <code>              # or no --invite at all if you're the registry's first-ever account
+axiom publish ./my-skill                     # reads ./my-skill/SKILL.md
+axiom invite                                 # admin only — mint a code for the next publisher
+axiom whoami
+```
+
+(Swap `axiom` for `npx axiom-skills` in any of the above if you'd rather
+not install it globally — same commands, same flags.)
+
+`SKILL.md` needs frontmatter with at least `name` and `description`:
+
+```markdown
+---
+name: pdf-report-builder
+description: Build branded PDF reports from a CSV or JSON data file.
+version: 1.0.0
+---
+
+# PDF Report Builder
+...
+```
+
+## Browsing and installing is public
+
+`axiom find`, `axiom add`, `axiom install`, and `axiom update` don't need
+an account — skills.sh-style. `axiom registry <url>` is the entire setup:
+it just points the CLI at a registry, the way `git remote add origin`
+points at a repo, no credentials involved.
+
+## Accounts — admin-controlled, not open self-service
+
+`axiom register` isn't a free-for-all like a typical `npm adduser` — the
+*first* account on a fresh registry becomes admin automatically (someone
+has to be able to issue the first invite), and every account after that
+needs a single-use invite code (`--invite <code>`, or the CLI prompts for
+one). Handing out invites is `axiom invite` (admin only) — run it with no
+flags to mint a fresh code, or `--list` to see which ones are outstanding
+vs. already used. Trying to register without a valid invite (once the
+registry already has an admin) comes back as a clear 400, not a silent
+failure.
+
+`axiom login` is for a second machine, or anyone else on the team who
+already has credentials — by default it prompts for username/password
+against the registry's `/v1/login`, or pass `--token` to use a pre-issued
+token directly (handy for CI). Either way, the result is a registry URL +
+token written to a local config file once — every later command already
+knows where "origin" is, the same job `.git/config`'s `[remote "origin"]`
+does. This is the *only* thing an account is for here: publishing needs an
+owner to check ownership and immutability against, `axiom whoami` needs an
+identity to report, `axiom invite` needs to know you're an admin —
+browsing/installing needs none of it.
+
+## Reproducible installs — axiom-skills.json / axiom-skills-lock.json
+
+`axiom add` doesn't just download a skill — it also records it, the same
+way `npm install foo` touches both `package.json` and `package-lock.json`:
+
+- **`axiom-skills.json`** — the manifest. What this project depends on,
+  hand-editable, meant to be committed. `{ "skills": { "acme/my-skill":
+  "1.2.0" } }`.
+- **`axiom-skills-lock.json`** — the lockfile. The exact version *and* a
+  `sha256` hash of the tarball that was actually installed, written by the
+  CLI, also meant to be committed.
+
+After cloning a project that has both files, run **`axiom install`**: it
+downloads exactly what's in the lockfile and verifies each tarball's hash
+before extracting it. If the registry ever served something that doesn't
+match — a corrupted download, or a version that got re-resolved
+differently than expected — install fails loudly instead of extracting
+something nobody reviewed. It does *not* go looking for anything newer;
+that's what `axiom update` is for.
+
+**`axiom update [owner/name]`** re-resolves one skill (or all of them, with
+no argument) to the registry's current latest — or to `--version <v>` if
+you want to pin a specific one — and moves both files forward. Nothing
+else touches the lockfile once it exists; `install` only ever reproduces
+it, `update` is the one command that deliberately changes it.
+
+```
+axiom add acme/my-skill          # writes/updates axiom-skills.json + lock
+git add axiom-skills.json axiom-skills-lock.json
+git commit -m "add acme/my-skill"
+
+# teammate, after cloning:
+axiom install                    # gets exactly acme/my-skill@<locked version>
+
+# later, deliberately:
+axiom update acme/my-skill       # -> latest, or --version 2.0.0 to pin
+```

package/bin/axiom.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { publish } from "../src/commands/publish.js";
+import { add } from "../src/commands/add.js";
+import { install } from "../src/commands/install.js";
+import { update } from "../src/commands/update.js";
+import { find } from "../src/commands/find.js";
+import { list } from "../src/commands/list.js";
+import { login } from "../src/commands/login.js";
+import { register } from "../src/commands/register.js";
+import { registry } from "../src/commands/registry.js";
+import { invite } from "../src/commands/invite.js";
+import { whoami } from "../src/commands/whoami.js";
+
+const program = new Command();
+
+program
+  .name("axiom")
+  .description("Publish and install agent Skills from your team's registry")
+  .version("0.1.0");
+
+program
+  .command("registry <url>")
+  .description("Point the CLI at a registry — no account needed for browsing/installing")
+  .action(registry);
+
+program
+  .command("register")
+  .description("Create an account on a registry and log in as it — needs an invite code (except the registry's very first account, which becomes admin)")
+  .option("--registry <url>", "registry API URL")
+  .option("--invite <code>", "invite code from an admin")
+  .action(register);
+
+program
+  .command("login")
+  .description("Log in to a registry with username/password (or --token) and store your credentials")
+  .option("--registry <url>", "registry API URL")
+  .option("--token <token>", "use a pre-issued token instead of username/password")
+  .action(login);
+
+program
+  .command("invite")
+  .description("Admin only: mint a single-use invite code (or --list to see outstanding/used ones)")
+  .option("--list", "list invite codes instead of minting a new one")
+  .action(invite);
+
+program
+  .command("publish [dir]")
+  .description("Pack and publish a skill directory (default: current directory)")
+  .action((dir) => publish(dir || "."));
+
+program
+  .command("add <skill>")
+  .description("Install a skill, e.g. `axiom add acme/pdf-report-builder@1.2.0` — also records it in axiom-skills.json / axiom-skills-lock.json")
+  .option("--dir <path>", "install target", ".agents/skills")
+  .action(add);
+
+program
+  .command("install")
+  .description("Install every skill in axiom-skills.json, reproducibly — uses axiom-skills-lock.json's exact versions + integrity when present")
+  .option("--dir <path>", "install target", ".agents/skills")
+  .action(install);
+
+program
+  .command("update [skill]")
+  .description("Update one skill (or all, if omitted) to the latest version — or --version <v> — and refresh the lockfile")
+  .option("--dir <path>", "install target", ".agents/skills")
+  .option("--version <version>", "pin to a specific version instead of latest")
+  .action(update);
+
+program
+  .command("find <query>")
+  .description("Search the registry")
+  .action(find);
+
+program
+  .command("list")
+  .description("List skills installed locally")
+  .option("--dir <path>", "skills directory", ".agents/skills")
+  .action(list);
+
+program
+  .command("whoami")
+  .description("Show the currently logged-in user and registry")
+  .action(whoami);
+
+program.parseAsync(process.argv);

package/fixtures/fake-registry.mjs

@@ -0,0 +1,97 @@
+import http from "node:http";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as tar from "tar";
+
+export const PORT = 8792;
+export const BASE = `http://127.0.0.1:${PORT}`;
+
+// owner/name -> available versions. Mutable so a test can add a version to
+// simulate "a newer release showed up" and confirm `axiom update` finds it.
+export const store = {
+  "alice/greeting-skill": ["1.0.0"],
+};
+
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  return 0;
+}
+const latestOf = (versions) => [...versions].sort(compareVersions).at(-1);
+
+const tarballs = new Map();
+async function buildTarball(name, version) {
+  const key = `${name}@${version}`;
+  if (tarballs.has(key)) return tarballs.get(key);
+
+  const srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "axiom-fixture-"));
+  fs.writeFileSync(
+    path.join(srcDir, "SKILL.md"),
+    `---\nname: ${name}\ndescription: Test fixture.\nversion: ${version}\n---\n\nHello from ${version}.\n`
+  );
+  const tmpFile = path.join(os.tmpdir(), `axiom-fixture-${key.replace("/", "-")}.tgz`);
+  await tar.create({ gzip: true, file: tmpFile, cwd: srcDir }, ["SKILL.md"]);
+  const buf = fs.readFileSync(tmpFile);
+  fs.unlinkSync(tmpFile);
+  fs.rmSync(srcDir, { recursive: true, force: true });
+  tarballs.set(key, buf);
+  return buf;
+}
+
+export function startFakeRegistry() {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, BASE);
+
+    let m = url.pathname.match(/^\/v1\/search$/);
+    if (m && req.method === "GET") {
+      const q = (url.searchParams.get("q") || "").toLowerCase();
+      const results = Object.entries(store)
+        .filter(([key]) => !q || key.toLowerCase().includes(q))
+        .map(([key, versions]) => {
+          const [owner, name] = key.split("/");
+          return { owner, name, latest: latestOf(versions) };
+        });
+      return json(res, 200, results);
+    }
+
+    m = url.pathname.match(/^\/v1\/skills\/([^/]+)\/([^/]+)$/);
+    if (m && req.method === "GET") {
+      const [, owner, name] = m;
+      const versions = store[`${owner}/${name}`];
+      if (!versions) return json(res, 404, { error: "not found" });
+
+      const requested = url.searchParams.get("version");
+      const version = requested || latestOf(versions);
+      if (!versions.includes(version)) {
+        return json(res, 404, { error: `no version ${version}`, availableVersions: versions });
+      }
+      return json(res, 200, {
+        owner,
+        name,
+        version,
+        downloadUrl: `${BASE}/tarball/${name}/${version}.tgz`,
+        expiresIn: 300,
+        availableVersions: versions,
+      });
+    }
+
+    m = url.pathname.match(/^\/tarball\/([^/]+)\/([^/]+)\.tgz$/);
+    if (m && req.method === "GET") {
+      const [, name, version] = m;
+      const buf = await buildTarball(name, version);
+      res.writeHead(200, { "content-type": "application/gzip" });
+      return res.end(buf);
+    }
+
+    res.writeHead(404);
+    res.end("not found");
+  });
+  return new Promise((resolve) => server.listen(PORT, () => resolve(server)));
+}
+
+function json(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "axiom-skills",
+  "version": "0.1.0",
+  "description": "CLI for the Axiom Skills registry — publish and install agent SKILL.md packages, backed by S3.",
+  "type": "module",
+  "bin": {
+    "axiom": "bin/axiom.js",
+    "axiom-skills": "bin/axiom.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "conf": "^13.0.1",
+    "node-fetch": "^3.3.2",
+    "prompts": "^2.4.2",
+    "tar": "^7.4.3",
+    "yaml": "^2.5.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import chalk from "chalk";
+import { fetchAndExtract } from "../lib/skillInstall.js";
+import { readManifest, writeManifest, readLockfile, writeLockfile } from "../lib/manifest.js";
+
+// Accepts "owner/name", "owner/name@version", or bare "name" (owner defaults
+// to "community", mirroring skills.sh's public-registry convention).
+function parseSpec(spec) {
+  const [ownerName, version] = spec.split("@");
+  const parts = ownerName.split("/");
+  const [owner, name] = parts.length === 2 ? parts : ["community", parts[0]];
+  return { owner, name, version };
+}
+
+export async function add(spec, opts) {
+  const { owner, name, version } = parseSpec(spec);
+  const key = `${owner}/${name}`;
+
+  const { resolvedVersion, integrity } = await fetchAndExtract({ owner, name, version }, opts.dir);
+  console.log(chalk.green(`✓ installed ${key}@${resolvedVersion} -> ${path.join(opts.dir, name)}`));
+
+  // The point of add isn't just "download it" — it's "make this project
+  // depend on it," so a teammate who runs `axiom install` after cloning
+  // gets the exact same thing. axiom-skills.json is what was asked for;
+  // axiom-skills-lock.json is what was actually verified and installed.
+  const manifest = readManifest();
+  manifest.skills[key] = resolvedVersion;
+  writeManifest(manifest);
+
+  const lock = readLockfile();
+  lock.skills[key] = { version: resolvedVersion, integrity };
+  writeLockfile(lock);
+
+  console.log(chalk.dim(`  recorded in axiom-skills.json and axiom-skills-lock.json`));
+}

package/src/commands/find.js

@@ -0,0 +1,15 @@
+import chalk from "chalk";
+import { search } from "../lib/api.js";
+
+export async function find(query) {
+  const results = await search(query);
+  if (!results.length) {
+    console.log(`No skills matched "${query}".`);
+    return;
+  }
+  // No metadata store means no stored description to show — just what
+  // exists in the bucket: owner/name and the newest version found there.
+  for (const r of results) {
+    console.log(`${chalk.bold(`${r.owner}/${r.name}`)}  ${chalk.dim(`v${r.latest}`)}`);
+  }
+}

package/src/commands/install.js

@@ -0,0 +1,42 @@
+import chalk from "chalk";
+import { fetchAndExtract } from "../lib/skillInstall.js";
+import { readManifest, readLockfile, writeLockfile } from "../lib/manifest.js";
+
+export async function install(opts) {
+  const manifest = readManifest();
+  const keys = Object.keys(manifest.skills);
+  if (!keys.length) {
+    console.log("No skills in axiom-skills.json — nothing to install. Run `axiom add <owner/name>` first.");
+    return;
+  }
+
+  const lock = readLockfile();
+  let lockChanged = false;
+
+  for (const key of keys) {
+    const [owner, name] = key.split("/");
+    const locked = lock.skills[key];
+
+    // A locked entry means "install exactly this" — the whole reason this
+    // command exists. Only fall back to the manifest's version (which
+    // might just say "latest") when there's nothing locked yet, e.g. a
+    // skill someone added to axiom-skills.json by hand without running
+    // `axiom add`.
+    const version = locked ? locked.version : manifest.skills[key];
+    const expectedIntegrity = locked?.integrity;
+
+    const { resolvedVersion, integrity } = await fetchAndExtract(
+      { owner, name, version: version === "latest" ? undefined : version },
+      opts.dir,
+      expectedIntegrity
+    );
+    console.log(chalk.green(`✓ ${key}@${resolvedVersion}`));
+
+    if (!locked || locked.version !== resolvedVersion || locked.integrity !== integrity) {
+      lock.skills[key] = { version: resolvedVersion, integrity };
+      lockChanged = true;
+    }
+  }
+
+  if (lockChanged) writeLockfile(lock);
+}

package/src/commands/invite.js

@@ -0,0 +1,29 @@
+import chalk from "chalk";
+import { createInviteRemote, listInvitesRemote } from "../lib/api.js";
+
+export async function invite(opts) {
+  try {
+    if (opts.list) {
+      const invites = await listInvitesRemote();
+      if (!invites.length) {
+        console.log("No invites yet — run `axiom invite` to mint one.");
+        return;
+      }
+      for (const inv of invites) {
+        const status = inv.used ? chalk.dim("used") : chalk.green("unused");
+        console.log(`${inv.code}  ${status}  (from ${inv.createdBy})`);
+      }
+      return;
+    }
+
+    const { code } = await createInviteRemote();
+    console.log(chalk.green(`✓ invite code: ${code}`));
+    console.log(chalk.dim("  Single-use — send it to the person you want to give publisher access to."));
+  } catch (err) {
+    // Same reasoning as everywhere else in this CLI: a 403 here almost
+    // always means "you're logged in, but not an admin," so let the
+    // server's own message carry that instead of guessing at it here.
+    console.error(chalk.red("Couldn't manage invites."), err.message);
+    process.exit(1);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readSkillFrontmatter } from "../lib/skillFile.js";
+
+export function list(opts) {
+  if (!fs.existsSync(opts.dir)) {
+    console.log(`No skills installed yet (looked in ${opts.dir}).`);
+    return;
+  }
+  for (const entry of fs.readdirSync(opts.dir)) {
+    const full = path.join(opts.dir, entry);
+    if (!fs.statSync(full).isDirectory()) continue;
+    try {
+      const meta = readSkillFrontmatter(full);
+      console.log(`${entry}  v${meta.version}`);
+    } catch {
+      console.log(`${entry}  (no SKILL.md)`);
+    }
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,67 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import { setConfig } from "../lib/config.js";
+import { loginRemote, whoamiRemote } from "../lib/api.js";
+
+export async function login(opts) {
+  const answers = await prompts([
+    {
+      type: opts.registry ? null : "text",
+      name: "registry",
+      message: "Registry URL",
+      initial: "https://registry.acme.dev",
+    },
+    // --token skips username/password entirely — for CI or anywhere you
+    // already have a token (e.g. one printed by `axiom register`) and
+    // just need the CLI to pick it up without a live login exchange.
+    {
+      type: opts.token ? null : "text",
+      name: "username",
+      message: "Username",
+    },
+    {
+      type: opts.token ? null : "password",
+      name: "password",
+      message: "Password",
+    },
+  ]);
+
+  const registry = (opts.registry || answers.registry || "").replace(/\/+$/, "");
+  if (!registry) {
+    console.error("Login cancelled — need a registry URL.");
+    process.exit(1);
+  }
+
+  if (opts.token) {
+    // Pre-issued token path: save it, then confirm it's actually valid by
+    // asking the registry who it belongs to (also fills in `username`,
+    // which is what `axiom publish` uses as the default owner).
+    setConfig({ registry, token: opts.token });
+    try {
+      const { username } = await whoamiRemote();
+      setConfig({ username });
+      console.log(chalk.green(`✓ logged in as ${username} on ${registry}`));
+    } catch (err) {
+      setConfig({ registry: null, token: null });
+      console.error(chalk.red("Login failed — registry rejected that token."), err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const username = answers.username;
+  const password = answers.password;
+  if (!username || !password) {
+    console.error("Login cancelled — need a username and password.");
+    process.exit(1);
+  }
+
+  try {
+    const result = await loginRemote(registry, { username, password });
+    setConfig({ registry, token: result.token, username: result.username });
+    console.log(chalk.green(`✓ logged in as ${result.username} on ${registry}`));
+  } catch (err) {
+    console.error(chalk.red("Login failed — wrong username/password, or registry unreachable."), err.message);
+    process.exit(1);
+  }
+}

package/src/commands/publish.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import * as tar from "tar";
+import { readSkillFrontmatter } from "../lib/skillFile.js";
+import { requestUploadUrl, uploadToPresignedUrl } from "../lib/api.js";
+import { getConfig } from "../lib/config.js";
+
+export async function publish(dir) {
+  const { username } = getConfig();
+  const meta = readSkillFrontmatter(dir);
+  const owner = meta.owner || username;
+
+  console.log(`Packing ${chalk.bold(`${owner}/${meta.name}@${meta.version}`)} from ${dir} ...`);
+
+  const tmpFile = path.join(os.tmpdir(), `axiom-${meta.name}-${meta.version}.tgz`);
+  await tar.create(
+    {
+      gzip: true,
+      file: tmpFile,
+      cwd: dir,
+      filter: (p) => !/(^|\/)(node_modules|\.git)(\/|$)/.test(p),
+    },
+    fs.readdirSync(dir)
+  );
+  const { size } = fs.statSync(tmpFile);
+  console.log(chalk.green(`✓ packed ${fs.readdirSync(dir).length} entries (${(size / 1024).toFixed(1)} kB)`));
+
+  // 1. ask the registry where to put it (presigned S3 PUT URL)
+  const { uploadUrl, key } = await requestUploadUrl({
+    owner,
+    name: meta.name,
+    version: meta.version,
+  });
+
+  // 2. upload straight to S3 — that's the whole publish. No index/database
+  // to update: S3 is what `axiom add` and `axiom find` look at directly.
+  await uploadToPresignedUrl(uploadUrl, tmpFile);
+  fs.unlinkSync(tmpFile);
+  console.log(chalk.green(`✓ uploaded to s3://${key}`));
+
+  console.log(chalk.green(`✓ published ${owner}/${meta.name}@${meta.version}`));
+  console.log(`  Install it with ${chalk.cyan(`axiom add ${owner}/${meta.name}`)}`);
+}

package/src/commands/register.js

@@ -0,0 +1,74 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import { setConfig } from "../lib/config.js";
+import { registerRemote } from "../lib/api.js";
+
+export async function register(opts) {
+  const first = await prompts([
+    {
+      type: opts.registry ? null : "text",
+      name: "registry",
+      message: "Registry URL",
+      initial: "https://registry.acme.dev",
+    },
+    {
+      type: "text",
+      name: "username",
+      message: "Choose a username",
+    },
+    {
+      type: "password",
+      name: "password",
+      message: "Choose a password (min 8 characters)",
+    },
+  ]);
+
+  const registry = (opts.registry || first.registry || "").replace(/\/+$/, "");
+
+  if (!registry || !first.username || !first.password) {
+    console.error("Registration cancelled.");
+    process.exit(1);
+  }
+
+  const second = await prompts({
+    type: "password",
+    name: "confirm",
+    message: "Confirm password",
+    validate: (value) =>
+      value === first.password ? true : "Passwords don't match",
+  });
+
+  if (second.confirm === undefined) {
+    console.error("Registration cancelled.");
+    process.exit(1);
+  }
+
+  // Every account after the registry's first needs one.
+  const inviteAnswers = await prompts({
+    type: opts.invite ? null : "text",
+    name: "inviteCode",
+    message:
+      "Invite code (leave blank only if this is a brand-new registry with no admin yet)",
+  });
+
+  const inviteCode = opts.invite || inviteAnswers.inviteCode || undefined;
+
+  try {
+    const { username, token } = await registerRemote(registry, {
+      username: first.username,
+      password: first.password,
+      inviteCode,
+    });
+
+    setConfig({ registry, token, username });
+
+    console.log(
+      chalk.green(
+        `✓ account created — logged in as ${username} on ${registry}`
+      )
+    );
+  } catch (err) {
+    console.error(chalk.red("Registration failed."), err.message);
+    process.exit(1);
+  }
+}

package/src/commands/registry.js

@@ -0,0 +1,13 @@
+import chalk from "chalk";
+import { setConfig } from "../lib/config.js";
+
+// The "no login required" on-ramp — skills.sh-style. `axiom login`/`axiom
+// register` also set this as a side effect, but neither is needed just to
+// browse and install: this is the whole setup for that.
+export function registry(url) {
+  const normalized = url.replace(/\/+$/, "");
+  setConfig({ registry: normalized });
+  console.log(chalk.green(`✓ registry set to ${normalized}`));
+  console.log(chalk.dim("  axiom find / axiom add / axiom install work now — no account needed."));
+  console.log(chalk.dim("  Run `axiom register` or `axiom login` only when you want to `axiom publish`."));
+}

package/src/commands/update.js

@@ -0,0 +1,51 @@
+import chalk from "chalk";
+import { fetchAndExtract } from "../lib/skillInstall.js";
+import { readManifest, writeManifest, readLockfile, writeLockfile } from "../lib/manifest.js";
+
+export async function update(name, opts) {
+  const manifest = readManifest();
+
+  if (name && !manifest.skills[name]) {
+    const known = Object.keys(manifest.skills);
+    console.error(
+      `"${name}" isn't in axiom-skills.json.` +
+        (known.length ? ` Known skills: ${known.join(", ")}` : " (axiom-skills.json has no skills yet)")
+    );
+    process.exit(1);
+  }
+
+  const keys = name ? [name] : Object.keys(manifest.skills);
+  if (!keys.length) {
+    console.log("Nothing to update — axiom-skills.json has no skills yet.");
+    return;
+  }
+
+  const lock = readLockfile();
+
+  for (const key of keys) {
+    const [owner, skillName] = key.split("/");
+    const previousVersion = lock.skills[key]?.version || manifest.skills[key];
+
+    // Deliberately ignores whatever's currently locked — that's the
+    // difference from `axiom install`. Update means "go get something
+    // newer (or the pinned --version)," not "reproduce exactly what's
+    // locked." No expectedIntegrity is passed for the same reason: there's
+    // nothing to verify against yet, the new download IS the new truth.
+    const { resolvedVersion, integrity } = await fetchAndExtract(
+      { owner, name: skillName, version: opts.version },
+      opts.dir
+    );
+
+    manifest.skills[key] = resolvedVersion;
+    lock.skills[key] = { version: resolvedVersion, integrity };
+
+    if (previousVersion === resolvedVersion) {
+      console.log(chalk.dim(`= ${key}@${resolvedVersion} (already up to date)`));
+    } else {
+      console.log(chalk.green(`↑ ${key} ${previousVersion} → ${resolvedVersion}`));
+    }
+  }
+
+  writeManifest(manifest);
+  writeLockfile(lock);
+}

package/src/commands/whoami.js

@@ -0,0 +1,14 @@
+import chalk from "chalk";
+import { getConfig } from "../lib/config.js";
+import { whoamiRemote } from "../lib/api.js";
+
+export async function whoami() {
+  const { registry } = getConfig();
+  try {
+    const { username } = await whoamiRemote();
+    console.log(`${chalk.bold(username)} on ${registry}`);
+  } catch (err) {
+    console.error(chalk.red("Not logged in or token is invalid."), err.message);
+    process.exit(1);
+  }
+}

package/src/lib/api.js

@@ -0,0 +1,89 @@
+import fetch from "node-fetch";
+import fs from "node:fs";
+import { requireConfig, requireRegistry } from "./config.js";
+
+async function rawCall(registry, path, { method = "GET", body, headers = {} } = {}) {
+  const res = await fetch(`${registry}${path}`, {
+    method,
+    headers: { "content-type": "application/json", ...headers },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`${method} ${path} -> ${res.status} ${text}`);
+  }
+  return res.json();
+}
+
+async function call(path, opts = {}) {
+  const { registry, token } = requireConfig();
+  return rawCall(registry, path, {
+    ...opts,
+    headers: { authorization: `Bearer ${token}`, ...(opts.headers || {}) },
+  });
+}
+
+// Same shape as call(), but for the routes the server doesn't gate behind
+// auth at all (search, skill/download resolution) — no token attached, no
+// login required, just "where's the registry."
+async function publicCall(path, opts = {}) {
+  const { registry } = requireRegistry();
+  return rawCall(registry, path, opts);
+}
+
+// register/login happen before there's a token to send, so they bypass
+// requireConfig() (which would fail with "not logged in") and take the
+// registry URL directly instead.
+export function registerRemote(registry, { username, password, inviteCode }) {
+  return rawCall(registry, "/v1/register", { method: "POST", body: { username, password, inviteCode } });
+}
+
+export function loginRemote(registry, { username, password }) {
+  return rawCall(registry, "/v1/login", { method: "POST", body: { username, password } });
+}
+
+// Step 1 of publish: ask the API where to upload. It hands back a short-lived
+// presigned S3 PUT URL — the CLI never needs S3 credentials of its own.
+export function requestUploadUrl({ owner, name, version }) {
+  return call(`/v1/skills/${owner}/${name}/versions`, {
+    method: "POST",
+    body: { version },
+  });
+}
+
+// Step 2: the CLI PUTs the tarball straight to S3 using the presigned URL.
+// That's the whole publish — there's no separate "confirm" call, because
+// there's no index to update. The next `axiom add` just lists the bucket.
+export async function uploadToPresignedUrl(uploadUrl, filePath) {
+  const body = fs.readFileSync(filePath);
+  const res = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "content-type": "application/gzip" },
+    body,
+  });
+  if (!res.ok) throw new Error(`Upload to S3 failed: ${res.status}`);
+}
+
+export function getSkill({ owner, name, version }) {
+  const q = version ? `?version=${encodeURIComponent(version)}` : "";
+  return publicCall(`/v1/skills/${owner}/${name}${q}`);
+}
+
+export function search(query) {
+  return publicCall(`/v1/search?q=${encodeURIComponent(query)}`);
+}
+
+export function whoamiRemote() {
+  return call(`/v1/whoami`);
+}
+
+// Admin-only on the server; the CLI doesn't know or check role itself, it
+// just makes the call and lets a 403 speak for itself if the logged-in
+// account isn't an admin.
+export function createInviteRemote() {
+  return call(`/v1/invites`, { method: "POST" });
+}
+
+export function listInvitesRemote() {
+  return call(`/v1/invites`);
+}

package/src/lib/config.js

@@ -0,0 +1,51 @@
+import Conf from "conf";
+
+// Lives at ~/.config/axiom-skills-nodejs/config.json (platform-appropriate).
+// This is the "git remote" / ~/.npmrc equivalent: once you `axiom login`,
+// every other command just reads this instead of asking you for a URL again.
+const store = new Conf({
+  projectName: "axiom-skills",
+  defaults: {
+    registry: null,
+    token: null,
+    username: null,
+  },
+});
+
+export function getConfig() {
+  return {
+    registry: store.get("registry"),
+    token: store.get("token"),
+    username: store.get("username"),
+  };
+}
+
+export function setConfig({ registry, token, username }) {
+  if (registry !== undefined) store.set("registry", registry);
+  if (token !== undefined) store.set("token", token);
+  if (username !== undefined) store.set("username", username);
+}
+
+export function requireConfig() {
+  const cfg = getConfig();
+  if (!cfg.registry || !cfg.token) {
+    console.error(
+      "Not logged in — needed for `axiom publish` / `axiom whoami`. Run `axiom register` (new account) or `axiom login` (existing one)."
+    );
+    process.exit(1);
+  }
+  return cfg;
+}
+
+// Browsing and installing skills is public — skills.sh-style, no account
+// needed — so this only requires knowing *where* the registry is, not who
+// you are. Set with `axiom registry <url>`, or as a side effect of
+// `axiom login`/`axiom register` if you're doing that anyway.
+export function requireRegistry() {
+  const cfg = getConfig();
+  if (!cfg.registry) {
+    console.error("No registry configured. Run `axiom registry <url>` first.");
+    process.exit(1);
+  }
+  return cfg;
+}

package/src/lib/integrity.js

@@ -0,0 +1,10 @@
+import crypto from "node:crypto";
+
+// Not SRI (that's base64 + supports multiple algorithms) — just a plain
+// sha256 hex digest of the tarball bytes, prefixed so the lockfile is
+// self-describing if the algorithm ever changes. Good enough for "did I
+// get the exact same bytes a teammate already tested," which is all a
+// lockfile needs to guarantee.
+export function computeIntegrity(buffer) {
+  return `sha256-${crypto.createHash("sha256").update(buffer).digest("hex")}`;
+}

package/src/lib/manifest.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// axiom-skills.json is the "package.json" of this pair — what the project
+// wants, hand-editable, meant to be committed. axiom-skills-lock.json is
+// the "package-lock.json" — exact resolved version + a content hash per
+// skill, written by the CLI, also meant to be committed. Together they're
+// what makes `axiom install` after a fresh clone reproducible instead of
+// "whatever's latest today."
+const MANIFEST_FILE = "axiom-skills.json";
+const LOCK_FILE = "axiom-skills-lock.json";
+
+function readJSON(file, fallback) {
+  if (!fs.existsSync(file)) return fallback;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeJSON(file, value) {
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+
+export function readManifest(cwd = process.cwd()) {
+  const manifest = readJSON(path.join(cwd, MANIFEST_FILE), { skills: {} });
+  manifest.skills = manifest.skills || {};
+  return manifest;
+}
+
+export function writeManifest(manifest, cwd = process.cwd()) {
+  writeJSON(path.join(cwd, MANIFEST_FILE), manifest);
+}
+
+export function readLockfile(cwd = process.cwd()) {
+  const lock = readJSON(path.join(cwd, LOCK_FILE), { lockfileVersion: 1, skills: {} });
+  lock.skills = lock.skills || {};
+  return lock;
+}
+
+export function writeLockfile(lock, cwd = process.cwd()) {
+  writeJSON(path.join(cwd, LOCK_FILE), lock);
+}

package/src/lib/skillFile.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+// Mirrors registry-api/src/lib/version.js's SEMVER_RE — kept as a small
+// duplicated regex rather than a shared package, since these are two
+// separate npm-published things. Checking here means a bad version fails
+// before packing/uploading a tarball, not after a round trip to the API.
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+// SKILL.md starts with YAML frontmatter, same convention skills.sh and
+// Claude's own Skills use:
+//
+//   ---
+//   name: pdf-report-builder
+//   description: Build branded PDF reports from a data file.
+//   version: 1.0.0
+//   ---
+export function readSkillFrontmatter(dir) {
+  const file = path.join(dir, "SKILL.md");
+  if (!fs.existsSync(file)) {
+    throw new Error(`No SKILL.md found in ${dir}`);
+  }
+  const raw = fs.readFileSync(file, "utf8");
+  const match = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error(`SKILL.md in ${dir} has no YAML frontmatter block`);
+  }
+  const meta = YAML.parse(match[1]);
+  for (const field of ["name", "description"]) {
+    if (!meta[field]) throw new Error(`SKILL.md is missing required field "${field}"`);
+  }
+  meta.version = meta.version || "0.0.0";
+  if (!SEMVER_RE.test(meta.version)) {
+    throw new Error(`SKILL.md has an invalid version "${meta.version}" (expected semver, e.g. 1.2.3)`);
+  }
+  return meta;
+}

package/src/lib/skillInstall.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import fetch from "node-fetch";
+import * as tar from "tar";
+import { getSkill } from "./api.js";
+import { computeIntegrity } from "./integrity.js";
+
+// Resolves owner/name[@version] against the registry, downloads the
+// tarball, and extracts it into <targetDir>/<name>. Returns the version
+// the registry actually resolved to (useful when `version` was omitted
+// and the server picked "latest") plus the tarball's content hash.
+//
+// If expectedIntegrity is given, a mismatch throws instead of installing
+// — that's the difference between `axiom add` (nothing to check against
+// yet) and `axiom install` (must match what's in the lockfile). A bad
+// match means either the registry served something other than what was
+// locked, or the download was corrupted in transit; either way it's not
+// safe to extract and run.
+export async function fetchAndExtract({ owner, name, version }, targetDir, expectedIntegrity) {
+  const { downloadUrl, version: resolvedVersion } = await getSkill({ owner, name, version });
+
+  const res = await fetch(downloadUrl);
+  if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  const integrity = computeIntegrity(buf);
+  if (expectedIntegrity && integrity !== expectedIntegrity) {
+    throw new Error(
+      `Integrity check failed for ${owner}/${name}@${resolvedVersion}: ` +
+        `axiom-skills-lock.json expects ${expectedIntegrity}, got ${integrity}. Refusing to install.`
+    );
+  }
+
+  const dir = path.join(targetDir, name);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpFile = path.join(os.tmpdir(), `axiom-${name}-${resolvedVersion}-${process.pid}.tgz`);
+  fs.writeFileSync(tmpFile, buf);
+  await tar.extract({ file: tmpFile, cwd: dir });
+  fs.unlinkSync(tmpFile);
+
+  return { resolvedVersion, integrity };
+}

package/test/cli.test.js

@@ -0,0 +1,95 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { startFakeRegistry, store, BASE } from "../fixtures/fake-registry.mjs";
+
+// Isolate the CLI's `conf`-backed config store from the real machine's
+// ~/.config — env-paths (which `conf` uses) honors XDG_CONFIG_HOME on
+// Linux. Must happen before config.js is ever imported, hence the dynamic
+// imports below instead of static ones (static imports are hoisted above
+// any code in this file, which would set the env var too late).
+const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), "axiom-config-"));
+process.env.XDG_CONFIG_HOME = fakeHome;
+
+const { setConfig } = await import("../src/lib/config.js");
+const { search } = await import("../src/lib/api.js");
+const { add } = await import("../src/commands/add.js");
+const { install } = await import("../src/commands/install.js");
+const { update } = await import("../src/commands/update.js");
+const { readManifest, readLockfile, writeLockfile } = await import("../src/lib/manifest.js");
+
+test("add / install / update — manifest, lockfile, integrity", async (t) => {
+  const server = await startFakeRegistry();
+  const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "axiom-project-"));
+  const skillsDir = path.join(projectDir, ".agents", "skills");
+  process.chdir(projectDir);
+
+  // Deliberately no token — browsing and installing skills is public now
+  // (skills.sh-style), so `axiom registry <url>` is the whole setup; an
+  // account is only for `axiom publish`. This is the actual scenario the
+  // whole test file runs under, not a one-off case: every add/install/
+  // update below has to work without ever calling setConfig({ token }).
+  setConfig({ registry: BASE });
+
+  await t.test("search works with no account configured at all", async () => {
+    const results = await search("greeting");
+    assert.deepEqual(results, [{ owner: "alice", name: "greeting-skill", latest: "1.0.0" }]);
+  });
+
+  await t.test("add records the exact resolved version in manifest + lockfile", async () => {
+    await add("alice/greeting-skill@1.0.0", { dir: skillsDir });
+
+    const manifest = readManifest(projectDir);
+    assert.equal(manifest.skills["alice/greeting-skill"], "1.0.0");
+
+    const lock = readLockfile(projectDir);
+    assert.equal(lock.skills["alice/greeting-skill"].version, "1.0.0");
+    assert.match(lock.skills["alice/greeting-skill"].integrity, /^sha256-[0-9a-f]{64}$/);
+
+    const skillMd = fs.readFileSync(path.join(skillsDir, "greeting-skill", "SKILL.md"), "utf8");
+    assert.match(skillMd, /Hello from 1\.0\.0/);
+  });
+
+  await t.test("install reproduces the locked version, not whatever is latest now", async () => {
+    // A newer version appears in the registry after `add` ran...
+    store["alice/greeting-skill"] = ["1.0.0", "1.1.0"];
+
+    // ...but a fresh `axiom install` (simulating a teammate's clone) must
+    // still get exactly what's locked: 1.0.0, not 1.1.0.
+    fs.rmSync(skillsDir, { recursive: true, force: true });
+    await install({ dir: skillsDir });
+
+    const skillMd = fs.readFileSync(path.join(skillsDir, "greeting-skill", "SKILL.md"), "utf8");
+    assert.match(skillMd, /Hello from 1\.0\.0/);
+
+    const lock = readLockfile(projectDir);
+    assert.equal(lock.skills["alice/greeting-skill"].version, "1.0.0");
+  });
+
+  await t.test("update moves the lock forward to the new latest", async () => {
+    await update("alice/greeting-skill", { dir: skillsDir });
+
+    const manifest = readManifest(projectDir);
+    assert.equal(manifest.skills["alice/greeting-skill"], "1.1.0");
+
+    const lock = readLockfile(projectDir);
+    assert.equal(lock.skills["alice/greeting-skill"].version, "1.1.0");
+
+    const skillMd = fs.readFileSync(path.join(skillsDir, "greeting-skill", "SKILL.md"), "utf8");
+    assert.match(skillMd, /Hello from 1\.1\.0/);
+  });
+
+  await t.test("install refuses a tarball that doesn't match the lockfile's integrity", async () => {
+    const lock = readLockfile(projectDir);
+    lock.skills["alice/greeting-skill"].integrity = "sha256-" + "0".repeat(64);
+    writeLockfile(lock, projectDir);
+
+    await assert.rejects(() => install({ dir: skillsDir }), /Integrity check failed/);
+  });
+
+  server.close();
+  fs.rmSync(projectDir, { recursive: true, force: true });
+  fs.rmSync(fakeHome, { recursive: true, force: true });
+});