@ahood/cli 0.5.0 → 0.5.2

package/README.md

@@ -60,6 +60,8 @@ npm i -g @ahood/cli
 ahood <command>
 ```
 
+**The `-g` flag matters.** `npm i @ahood/cli` (no `-g`) installs into the current directory's `node_modules/` instead, and `ahood` won't be on your `PATH` -- you'll get `ahood: command not found`. If that happens, either re-run with `-g`, or use `npx @ahood/cli@latest <command>` from that directory instead.
+
 Requires Node.js 18 or later.
 
 ## Why ahood
@@ -79,12 +81,13 @@ Requires Node.js 18 or later.
 | `AHOOD_API_URL` | Overrides the registry endpoint (default: `https://ahood.vercel.app`). Must be `https://`, except for `localhost`/`127.0.0.1` or a `.test`/`.invalid`/`.example`/`.localhost` host, which may use plain `http://` for local development. |
 | `XDG_CONFIG_HOME` | If set, browser-login credentials are stored under `$XDG_CONFIG_HOME/ahood/credentials.json` instead of the default `~/.config/ahood/credentials.json`. |
 
-Two files `ahood` reads and writes in your project, neither of which needs to be gitignored (the lockfile is meant to be committed, same as `package-lock.json`):
+Paths `ahood` reads and writes in your project, none of which need to be gitignored (the lockfile is meant to be committed, same as `package-lock.json`):
 
 | Path | What's in it |
 | --- | --- |
 | `.claude/skills/<owner>/<skill>/` | Installed skill files. |
-| `.claude/skills.lock.json` | Exact installed version + checksum per skill, written by `add`/`update`, read by every install to verify integrity. |
+| `.claude/agents/<owner>@<skill>.md` | An installed agent, as a single file (`@` owner/skill separator, since Claude Code's own subagent loader scans `.claude/agents/*.md` flat, non-recursively). |
+| `.claude/skills.lock.json` | Exact installed version + checksum per skill or agent, written by `add`/`update`, read by every install to verify integrity. |
 
 ## Usage examples
 
@@ -218,7 +221,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood skill share <owner>/<skill> --group <group>` | Share a skill you own with a group, without changing its public/private visibility. |
 | `ahood skill unshare <owner>/<skill> --group <group>` | Stop sharing a skill you own with a group. |
 | `ahood skill init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
-| `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]` | Publish a new version of a skill from a folder containing SKILL.md, creating the skill first if it doesn't already exist. |
+| `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill\|agent\|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]` | Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json, creating the skill first if it doesn't already exist. |
 
 ### Group
 

package/dist/commands/add.js

@@ -1,12 +1,14 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
 import { apiFetch, apiJson } from "../http.js";
-import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir } from "../spec.js";
-import { readLockfile, writeLockfileEntry } from "../lockfile.js";
-const USAGE = "Usage: ahood add <owner>/<skill>[@version]";
+import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
+import { readLockfile, writeLockfileEntry, withLock, writeJsonFileAtomic } from "../lockfile.js";
+import { promptSecret } from "../secret-prompt.js";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
 const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; // 200 MB decompressed
 const MAX_ENTRY_COUNT = 10_000;
@@ -24,10 +26,16 @@ const MAX_ENTRY_COUNT = 10_000;
 // rather than assumed.
 export async function fetchVersionMeta(owner, skill, version) {
     if (version === "latest") {
-        const { skill_versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+        // `kind` comes back as a TOP-LEVEL sibling of `skill_versions` on this
+        // route (GET /api/v1/skills/{owner}/{skill}), not nested inside it --
+        // confirmed against the real route.ts response shape. Destructuring only
+        // `skill_versions` (as this used to do) silently drops `kind`, which
+        // makes an agent install fall through to the skill-directory path with
+        // no error anywhere (ahood-cli final review finding #1).
+        const { skill_versions, kind } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
         if (!skill_versions)
             throw new Error(`${owner}/${skill} has no published version`);
-        return { ...skill_versions, yanked_at: null };
+        return { ...skill_versions, kind, yanked_at: null };
     }
     return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/${encodeURIComponent(version)}`);
 }
@@ -163,10 +171,240 @@ async function extractFreshVersion(buffer, destDir) {
     rmSync(destDir, { recursive: true, force: true });
     renameSync(tempDir, destDir);
 }
+// Agent packages install as one file, not a directory (Claude Code's own
+// .claude/agents/*.md convention is flat, non-recursive) -- extracts just
+// AGENT.md's content from the downloaded tarball rather than writing every
+// entry to disk the way extractFreshVersion does for skills.
+async function extractSingleFileContent(buffer, entryName) {
+    let decompressed;
+    try {
+        // Same decompression-bomb guard as extractTarGz above: a highly-
+        // compressed payload whose checksum matches (that check runs on the
+        // compressed bytes) must not be allowed to allocate unboundedly on
+        // decompression.
+        decompressed = gunzipSync(buffer, { maxOutputLength: MAX_EXTRACTED_BYTES });
+    }
+    catch (error) {
+        throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
+    }
+    const extract = tarStream.extract();
+    let found = null;
+    await new Promise((resolvePromise, reject) => {
+        extract.on("entry", (header, stream, next) => {
+            // Normalize a leading "./" the same way extractTarGz and the server's
+            // extract-and-checksum.ts normalizeEntryPath do -- a plain `tar czf`
+            // commonly prefixes entries with "./", which would otherwise pass
+            // server-side validation/publish but then fail to install here with
+            // "AGENT.md not found" (ahood-cli final review finding #3).
+            const normalizedName = header.name.replace(/^\.\//, "");
+            if (normalizedName !== entryName) {
+                stream.resume();
+                next();
+                return;
+            }
+            // Only take the FIRST matching entry, mirroring the server side's
+            // `files.find(...)` lookup -- otherwise a tar with two entries at the
+            // same normalized name would resolve to whichever one happens to come
+            // last here, diverging from what the server validated against
+            // (ahood-cli final review finding #4).
+            if (found !== null) {
+                stream.resume();
+                next();
+                return;
+            }
+            const chunks = [];
+            stream.on("data", (chunk) => chunks.push(chunk));
+            stream.on("end", () => {
+                found = Buffer.concat(chunks);
+                next();
+            });
+            stream.on("error", reject);
+        });
+        extract.on("finish", () => resolvePromise());
+        extract.on("error", reject);
+        extract.end(decompressed);
+    });
+    if (!found)
+        throw new Error(`${entryName} not found in the downloaded archive`);
+    return found;
+}
+// Every manifest field used below reaches the terminal (an error message, or
+// -- worse -- the text printed immediately before a masked secret prompt)
+// but comes verbatim from a third-party-published server.json: server-side
+// validation only checks these are strings, not that they're free of
+// control/escape characters. A malicious description could otherwise smuggle
+// a terminal control sequence (cursor movement, line-clear) that repaints
+// what the user sees at the exact moment they're about to type a credential.
+// Strips C0/C1 control characters (including ESC, \x1b) and caps length so a
+// single field can't also flood the terminal.
+function sanitizeForTerminal(text) {
+    return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
+}
+// Only npm+npx is supported in v1 (docs/superpowers/specs/2026-09-03-mcp-server-artifacts-design.md) --
+// server-side publish validation (lib/publish/parse-server-manifest.ts) already
+// rejects anything else, so this check is defense-in-depth against a
+// manifest that somehow reached this point unvalidated, same posture as
+// extractTarGz's own re-check of path containment "even though the server's
+// publish-time validateEntries is supposed to have rejected it already."
+function buildMcpServerConfig(manifest, env) {
+    const manifestName = sanitizeForTerminal(manifest.name);
+    if (manifest.packages && manifest.packages.length === 1) {
+        const pkg = manifest.packages[0];
+        if (pkg.registry_type !== "npm" || pkg.runtime_hint !== "npx") {
+            throw new Error(`${manifestName}'s server.json uses registry_type "${pkg.registry_type}"/runtime_hint "${pkg.runtime_hint}", which this version of ahood does not know how to install (only npm+npx is supported).`);
+        }
+        const config = { command: "npx", args: ["-y", `${pkg.identifier}@${pkg.version}`] };
+        if (Object.keys(env).length > 0)
+            config.env = env;
+        return config;
+    }
+    if (manifest.remotes && manifest.remotes.length === 1) {
+        const remote = manifest.remotes[0];
+        return remote.headers ? { url: remote.url, headers: remote.headers } : { url: remote.url };
+    }
+    throw new Error(`${manifestName}'s server.json has neither a single 'packages' entry nor a single 'remotes' entry.`);
+}
+// A conflicting .mcp.json entry is summarized back to the user in the
+// collision error below so they can identify what they'd be overwriting --
+// but this entry is, by definition, one ahood did NOT write (that's what
+// makes it a collision), so it's a hand-authored entry that routinely passes
+// a credential as a CLI arg (e.g. `"args": ["-y", "@thing", "--api-key",
+// "sk-live-..."]`) or in a URL query string (`"url": "https://host/sse?
+// token=..."`) -- neither of which a small "env"/"headers"-keyed redaction
+// allowlist would ever touch. Worse than a rare edge case: update.ts calls
+// add() for every locked entry and prints caught error messages, so a leak
+// here would fire on a routine `ahood skill update`, not just a rare manual
+// re-add.
+//
+// So rather than trying to allowlist every place a secret might hide, this
+// prints only structural information: the entry's top-level key names, its
+// `command` (a package identifier, not a secret), the key names inside
+// `env`/`headers` (so the user can see WHICH variable conflicts without its
+// value), and the conflicting URL's hostname (never its full value, since
+// query strings are a common place to find a token). No leaf string value
+// from `args`, a header's value, an env var's value, or a URL's path/query
+// is ever included.
+function summarizeConflictingEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+        return String(entry);
+    const obj = entry;
+    const parts = [`keys: ${Object.keys(obj).join(", ") || "(none)"}`];
+    if (typeof obj.command === "string")
+        parts.push(`command: ${obj.command}`);
+    for (const key of ["env", "headers"]) {
+        const value = obj[key];
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            parts.push(`${key} keys: ${Object.keys(value).join(", ")}`);
+        }
+    }
+    if (typeof obj.url === "string") {
+        try {
+            parts.push(`url host: ${new URL(obj.url).hostname}`);
+        }
+        catch {
+            // Not a parseable URL -- omit rather than risk printing something
+            // sensitive verbatim.
+        }
+    }
+    return parts.join("; ");
+}
+// Reads and validates .mcp.json's shape, defaulting to an empty config when
+// the file doesn't exist yet. Guards `mcpServers` itself (not just the
+// top-level object) against being missing, `null`, or an array: a bare
+// `fileContents.mcpServers === undefined` check alone would let
+// `"mcpServers": null` reach the collision check below as an unactionable
+// raw TypeError, and would let `"mcpServers": []` pass the collision check
+// silently (an array's numeric-index write is then dropped entirely by
+// JSON.stringify), reporting a successful install that wrote nothing.
+function readMcpConfig() {
+    if (!existsSync(MCP_CONFIG_PATH))
+        return { mcpServers: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(MCP_CONFIG_PATH, "utf-8"));
+    }
+    catch {
+        throw new Error(`${MCP_CONFIG_PATH} exists but is not valid JSON -- fix or remove it before running this command.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${MCP_CONFIG_PATH} exists but its top level is not a JSON object.`);
+    }
+    const fileContents = parsed;
+    if (fileContents.mcpServers === undefined) {
+        fileContents.mcpServers = {};
+    }
+    else if (typeof fileContents.mcpServers !== "object" ||
+        fileContents.mcpServers === null ||
+        Array.isArray(fileContents.mcpServers)) {
+        throw new Error(`${MCP_CONFIG_PATH}'s "mcpServers" key exists but is not a JSON object -- fix or remove it before running this command.`);
+    }
+    return fileContents;
+}
+// Keyed by ahood's own validated `skill` slug (SEGMENT_RE-checked in
+// spec.ts), not the manifest's self-reported `name` field: two different
+// published packages could easily share a generic internal name like
+// "weather-server", and a JSON object key built from unvalidated manifest
+// text is a footgun this sidesteps entirely by never using it as a key.
+function assertNoCollision(fileContents, owner, skill) {
+    const mcpServers = fileContents.mcpServers;
+    if (Object.prototype.hasOwnProperty.call(mcpServers, skill)) {
+        throw new Error(`${MCP_CONFIG_PATH} already has an entry named "${skill}" (${summarizeConflictingEntry(mcpServers[skill])}).\n` +
+            `Remove it manually first if you want to reinstall ${owner}/${skill}.`);
+    }
+}
+async function installMcpEntry(owner, skill, meta, buffer) {
+    const content = await extractSingleFileContent(buffer, "server.json");
+    const manifest = JSON.parse(content.toString("utf-8"));
+    // Validate the manifest's shape (unsupported registry_type/runtime_hint,
+    // or neither a single 'packages' nor a single 'remotes' entry) and check
+    // for an existing .mcp.json collision BEFORE prompting for any secret --
+    // an install that's going to be refused anyway must not first cost the
+    // user a masked secret prompt. buildMcpServerConfig is called here with an
+    // empty env purely to run its validation/throw; the result is discarded
+    // and rebuilt below once secretEnv is known.
+    buildMcpServerConfig(manifest, {});
+    assertNoCollision(readMcpConfig(), owner, skill);
+    const envVars = manifest.packages?.[0]?.environment_variables ?? [];
+    const secretEnv = {};
+    for (const variable of envVars) {
+        if (!variable.is_secret)
+            continue;
+        const fromEnv = process.env[variable.name];
+        // Truthiness, not `!== undefined` -- matches credentials.ts's
+        // resolveToken(), the precedent this feature was explicitly modeled on
+        // (per the design spec), which uses `if (process.env.AHOOD_TOKEN)`
+        // specifically so an empty-string env var falls through to the real
+        // source instead of silently installing an empty secret.
+        secretEnv[variable.name] = fromEnv
+            ? fromEnv
+            : await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
+    }
+    const serverConfig = buildMcpServerConfig(manifest, secretEnv);
+    // Read-modify-write under an advisory lock, mirroring lockfile.ts's own
+    // writeLockfileEntry: .mcp.json sits right next to the lockfile and can
+    // hold other servers' secrets, so it gets the same protection against a
+    // truncated write or a concurrent `add` racing the same read-modify-write.
+    // Re-reads and re-checks the collision here rather than trusting the
+    // pre-check above, since arbitrary time may have passed since then --
+    // including, in the interactive case, however long the user took at the
+    // secret prompt -- during which another process could have written the
+    // same entry.
+    withLock(MCP_CONFIG_PATH, () => {
+        const fileContents = readMcpConfig();
+        assertNoCollision(fileContents, owner, skill);
+        fileContents.mcpServers[skill] = serverConfig;
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+    });
+    writeLockfileEntry(LOCKFILE_PATH, `${owner}/${skill}`, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+    console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
+    if (Object.keys(secretEnv).length > 0) {
+        console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
+    }
+}
 export async function add(args) {
     const spec = args[0];
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill, version: requestedVersion } = parseOwnerSkillVersion(spec, USAGE);
     const key = `${owner}/${skill}`;
     const meta = await fetchVersionMeta(owner, skill, requestedVersion);
@@ -184,8 +422,13 @@ export async function add(args) {
     }
     // scripts/ warning: mirrors the web detail page's banner (platform ADR's
     // Open Risk #7) -- a CLI-only user installing via `add` would otherwise
-    // never see this at all.
-    if (meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
+    // never see this at all. Skipped for an agent install: only AGENT.md's
+    // content is ever extracted/written on that path (extractSingleFileContent
+    // never touches anything else in the archive), so a scripts/ entry in the
+    // manifest can never actually land on disk there -- the warning would be
+    // both mislabeled ("skill") and about a risk that can't materialize
+    // (ahood-cli final review finding #5).
+    if (meta.kind !== "agent" && meta.kind !== "mcp" && meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
         console.warn("WARNING: this skill includes a scripts/ directory. Review its contents before use.");
     }
     const downloadRes = await apiFetch(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/download?version=${encodeURIComponent(meta.version)}`, { headers: { "X-Ahood-Source": "cli" }, redirect: "follow" });
@@ -198,6 +441,19 @@ export async function add(args) {
     if (actualChecksum !== meta.checksum_sha256) {
         throw new Error(`Checksum mismatch for ${key}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
     }
+    if (meta.kind === "agent") {
+        const content = await extractSingleFileContent(buffer, "AGENT.md");
+        mkdirSync(AGENTS_ROOT, { recursive: true });
+        const destPath = agentPath(owner, skill);
+        writeFileSync(destPath, content);
+        writeLockfileEntry(LOCKFILE_PATH, key, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+        console.log(`Installed ${key}@${meta.version} to ${destPath}`);
+        return;
+    }
+    if (meta.kind === "mcp") {
+        await installMcpEntry(owner, skill, meta, buffer);
+        return;
+    }
     // Owner-namespaced on disk, mirroring npm's node_modules/@scope/package.
     const destDir = skillDir(owner, skill);
     await extractFreshVersion(buffer, destDir);

package/dist/commands/completion.js

@@ -1,4 +1,5 @@
 import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, COMMAND_ALIASES } from "../help.js";
+import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
 // Position 1 (the word right after "ahood"): every top-level command plus
 // the "skill" entity group itself.
@@ -69,6 +70,6 @@ export async function completion(args) {
             console.log(fishCompletion());
             return;
         default:
-            throw new Error(USAGE);
+            throw new UsageError(USAGE);
     }
 }

package/dist/commands/edit.js

@@ -1,7 +1,8 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, validateExternalUrl } from "../spec.js";
-const USAGE = "Usage: ahood edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private] [--homepage <url>] [--repository <url>]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private] [--homepage <url>] [--repository <url>]";
 // Mirrors PATCH /api/v1/skills/{owner}/{skill}'s allow-list exactly
 // (lib/skills/mutations.ts's UpdateSkillInput) -- only a field the caller
 // explicitly passed a flag for is included in the body, so an omitted flag
@@ -10,7 +11,7 @@ const USAGE = "Usage: ahood edit <owner>/<skill> [--tagline <text>] [--tags <com
 export async function edit(args) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const body = {};
     const tagline = flagValue(args, "--tagline");
@@ -25,7 +26,7 @@ export async function edit(args) {
     const visibility = flagValue(args, "--visibility");
     if (visibility !== undefined) {
         if (visibility !== "public" && visibility !== "private") {
-            throw new Error(`--visibility must be "public" or "private" (got "${visibility}").`);
+            throw new UsageError(`--visibility must be "public" or "private" (got "${visibility}").`);
         }
         body.visibility = visibility;
     }
@@ -40,7 +41,7 @@ export async function edit(args) {
         body.repository = repository;
     }
     if (Object.keys(body).length === 0) {
-        throw new Error("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
+        throw new UsageError("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
     }
     const updated = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, {
         method: "PATCH",

package/dist/commands/group.js

@@ -2,6 +2,7 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { confirm } from "../confirm.js";
 import { getApiUrl } from "../config.js";
+import { UsageError } from "../usage-error.js";
 const CREATE_USAGE = "Usage: ahood group create <name> [--description <text>]";
 const LIST_USAGE = "Usage: ahood group list [--json]";
 const MEMBERS_USAGE = "Usage: ahood group members <group> [--json]";
@@ -18,7 +19,7 @@ const DELETE_USAGE = "Usage: ahood group delete <group> [--yes]";
 export async function createGroup(args) {
     const name = args[0];
     if (!name || name.startsWith("--"))
-        throw new Error(CREATE_USAGE);
+        throw new UsageError(CREATE_USAGE);
     const description = flagValue(args, "--description");
     const body = { name };
     if (description !== undefined)
@@ -52,7 +53,7 @@ export async function groupMembers(args) {
     const jsonOutput = args.includes("--json");
     const slug = args.find((a) => !a.startsWith("--"));
     if (!slug)
-        throw new Error(MEMBERS_USAGE);
+        throw new UsageError(MEMBERS_USAGE);
     const { group, members } = await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}`);
     if (jsonOutput) {
         console.log(JSON.stringify({ group, members }));
@@ -73,7 +74,7 @@ export async function inviteLink(args) {
     const jsonOutput = args.includes("--json");
     const slug = args.find((a) => !a.startsWith("--"));
     if (!slug)
-        throw new Error(INVITE_LINK_USAGE);
+        throw new UsageError(INVITE_LINK_USAGE);
     const { token, expiresAt } = await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/invites`, { method: "POST" });
     const url = `${getApiUrl()}/groups/join?token=${encodeURIComponent(token)}`;
     if (jsonOutput) {
@@ -105,7 +106,7 @@ function extractToken(input) {
 export async function joinGroup(args) {
     const input = args.find((a) => !a.startsWith("--"));
     if (!input)
-        throw new Error(JOIN_USAGE);
+        throw new UsageError(JOIN_USAGE);
     const token = extractToken(input);
     const { groupSlug, groupName } = await apiJson(`/api/v1/groups/invites/${encodeURIComponent(token)}/accept`, { method: "POST" });
     console.log(`Joined ${groupName} (${groupSlug}).`);
@@ -117,7 +118,7 @@ export async function removeMember(args) {
     const positional = args.filter((a) => !a.startsWith("--"));
     const [slug, username] = positional;
     if (!slug || !username)
-        throw new Error(REMOVE_MEMBER_USAGE);
+        throw new UsageError(REMOVE_MEMBER_USAGE);
     await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
     console.log(`Removed ${username} from ${slug}.`);
 }
@@ -135,7 +136,7 @@ async function getOwnUsername() {
 export async function leaveGroup(args) {
     const slug = args.find((a) => !a.startsWith("--"));
     if (!slug)
-        throw new Error(LEAVE_USAGE);
+        throw new UsageError(LEAVE_USAGE);
     const username = await getOwnUsername();
     await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
     console.log(`Left ${slug}.`);
@@ -147,7 +148,7 @@ export async function deleteGroup(args) {
     const yes = args.includes("--yes");
     const slug = args.find((a) => !a.startsWith("--"));
     if (!slug)
-        throw new Error(DELETE_USAGE);
+        throw new UsageError(DELETE_USAGE);
     const confirmed = yes
         ? true
         : await confirm(`This will permanently delete the group "${slug}" for all members. Type "yes" to confirm: `);

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, join, resolve, sep } from "node:path";
-const USAGE = "Usage: ahood init [name]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill init [name]";
 // Mirrors the server's slug convention referenced by ahood-cli#60 (and the
 // same shape as spec.ts's SEGMENT_RE, minus "." and "_" -- skill slugs are
 // strictly lowercase-alnum-and-hyphen). A name that already matches this is
@@ -33,7 +34,7 @@ function buildSkillMd(name) {
     return `---
 # name: a short, unique identifier for this skill (kebab-case is
 # conventional, e.g. "pdf-tools"). Not the same as the <skill> slug you
-# publish under -- ahood publish reads that from the command line -- but
+# publish under -- ahood skill publish reads that from the command line -- but
 # keeping them in sync avoids confusion.
 name: ${name}
 # description: one or two sentences describing what this skill does and
@@ -49,7 +50,7 @@ TODO: describe, step by step, what Claude should do when this skill is invoked.
 }
 // Falls back to "my-skill" when the directory name itself isn't usable as a
 // bare YAML scalar (empty, or starting with a character like "-" or "@" that
-// would need quoting) -- e.g. running `ahood init` with no name directly in
+// would need quoting) -- e.g. running `ahood skill init` with no name directly in
 // "/" (basename "") or in a directory whose name starts with punctuation.
 function skillNameFor(dirPath) {
     const base = basename(dirPath);
@@ -58,7 +59,7 @@ function skillNameFor(dirPath) {
 export async function init(args) {
     let name = args[0];
     if (name !== undefined && name.startsWith("-"))
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (name) {
         // Path containment first (ahood-cli#61), mirroring spec.ts's
         // validateSegment containment discipline used by add/remove: a resolved
@@ -69,7 +70,7 @@ export async function init(args) {
         const cwd = resolve(process.cwd());
         const resolvedName = resolve(cwd, name);
         if (resolvedName !== cwd && !resolvedName.startsWith(cwd + sep)) {
-            throw new Error(`Invalid name "${name}" -- resolves to "${resolvedName}", which is outside the current directory (${cwd}). Refusing to create files outside the project directory.`);
+            throw new UsageError(`Invalid name "${name}" -- resolves to "${resolvedName}", which is outside the current directory (${cwd}). Refusing to create files outside the project directory.`);
         }
         // Then slug normalization (ahood-cli#60): a name that stays within cwd
         // but isn't already a valid slug gets normalized with a note, rather
@@ -77,7 +78,7 @@ export async function init(args) {
         if (!SLUG_RE.test(name)) {
             const normalized = normalizeToSlug(name);
             if (!normalized) {
-                throw new Error(`Invalid name "${name}" -- could not derive a valid name from it (must contain at least one letter or digit).`);
+                throw new UsageError(`Invalid name "${name}" -- could not derive a valid name from it (must contain at least one letter or digit).`);
             }
             console.log(`Note: normalized "${name}" to "${normalized}".`);
             name = normalized;
@@ -92,5 +93,5 @@ export async function init(args) {
     writeFileSync(skillMdPath, buildSkillMd(name ?? skillNameFor(targetDir)));
     console.log(`Created ${skillMdPath}`);
     console.log("Fill in the description, then flesh out the ## Instructions section.");
-    console.log(`Run \`ahood publish <owner>/<skill>@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
+    console.log(`Run \`ahood skill publish <owner>/<skill>@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
 }