@ahood/cli 0.5.1 → 0.6.0

package/dist/commands/publish.js

@@ -5,6 +5,7 @@ import { createGzip } from "node:zlib";
 import { apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, SEMVER_RE, validateExternalUrl } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 // Processing (decompress/validate/checksum/scan/upload) now happens in a
 // background workflow, not inline in versions/complete's response (server
 // issue #120) -- complete returns 202 immediately, so this polls
@@ -24,10 +25,10 @@ async function pollVersionStatus(owner, skill, version) {
             return result;
         await sleep(POLL_INTERVAL_MS);
     }
-    throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood view ${owner}/${skill}\` later for the result.`);
+    throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood skill view ${owner}/${skill}\` later for the result.`);
 }
-const USAGE = "Usage: ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]\n" +
-    "   or: ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
+const USAGE = "Usage: 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]\n" +
+    "   or: ahood skill publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
 // Matched by ENTRY NAME at every depth, not by path prefix, so a nested
 // `vendor/thing/.git` is skipped the same as a top-level one. Not a
 // .gitignore parser (out of scope) -- just the fixed set of names that must
@@ -109,25 +110,29 @@ function parsePublishArgs(args) {
     const license = flagValue(args, "--license");
     const homepage = flagValue(args, "--homepage");
     const repository = flagValue(args, "--repository");
+    const kind = flagValue(args, "--kind");
     let legacyPath;
     const first = args[0];
     if (first && !first.startsWith("--")) {
         if (first.includes("/") && first.includes("@")) {
-            // Primary form: ahood publish <owner>/<skill>@<version>
+            // Primary form: ahood skill publish <owner>/<skill>@<version>
             const parsed = parseOwnerSkill(first.slice(0, first.lastIndexOf("@")), USAGE);
             owner = owner ?? parsed.owner;
             skill = skill ?? parsed.skill;
             version = version ?? first.slice(first.lastIndexOf("@") + 1);
         }
         else {
-            // Legacy form: ahood publish <path> --owner ... --slug ... --version ...
+            // Legacy form: ahood skill publish <path> --owner ... --slug ... --version ...
             legacyPath = first;
         }
     }
     if (!owner || !skill || !version)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (!SEMVER_RE.test(version)) {
-        throw new Error(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
+        throw new UsageError(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
+    }
+    if (kind !== undefined && kind !== "skill" && kind !== "agent" && kind !== "mcp") {
+        throw new UsageError(`--kind must be "skill", "agent", or "mcp" (got "${kind}").\n${USAGE}`);
     }
     // Validated here, before any network call (including the tar/gzip of the
     // skill directory) -- these only ever reach the server via
@@ -136,7 +141,7 @@ function parsePublishArgs(args) {
         validateExternalUrl(homepage, "--homepage");
     if (repository !== undefined)
         validateExternalUrl(repository, "--repository");
-    return { owner, skill, version, path: pathFlag ?? legacyPath ?? ".", name, tagline, tags, license, homepage, repository };
+    return { owner, skill, version, path: pathFlag ?? legacyPath ?? ".", name, tagline, tags, license, homepage, repository, kind };
 }
 // Creates the skill under the caller's own account when versions/init 404s
 // -- skill creation is CLI-only now (there is no separate `ahood create`;
@@ -159,6 +164,8 @@ async function createSkillForPublish(owner, skill, opts, jsonOutput) {
         body.homepage = opts.homepage;
     if (opts.repository !== undefined)
         body.repository = opts.repository;
+    if (opts.kind !== undefined)
+        body.kind = opts.kind;
     const created = await apiJson("/api/v1/skills", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -171,7 +178,7 @@ async function createSkillForPublish(owner, skill, opts, jsonOutput) {
     if (created.owner !== owner) {
         throw new Error(`Created ${created.owner}/${created.slug}, but this publish targeted "${owner}/${skill}" -- skills ` +
             `are always created under your own account (${created.owner}). Retry with: ` +
-            `ahood publish ${created.owner}/${skill}@<version>.`);
+            `ahood skill publish ${created.owner}/${skill}@<version>.`);
     }
     if (!jsonOutput) {
         console.log(`Created ${created.owner}/${created.slug} -- publishing its first version now.`);
@@ -205,13 +212,45 @@ async function initVersion(owner, skill, version, packageSizeBytes, createOpts,
 export async function publish(args) {
     const jsonOutput = args.includes("--json");
     try {
-        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository } = parsePublishArgs(args);
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, kind } = parsePublishArgs(args);
         const skillMdPath = join(path, "SKILL.md");
-        if (!existsSync(skillMdPath)) {
-            throw new Error(`No SKILL.md found at ${skillMdPath} -- publish must point at a skill folder's root.`);
+        const agentMdPath = join(path, "AGENT.md");
+        const serverJsonPath = join(path, "server.json");
+        const hasSkillMd = existsSync(skillMdPath);
+        const hasAgentMd = existsSync(agentMdPath);
+        const hasServerJson = existsSync(serverJsonPath);
+        let resolvedKind = kind;
+        if (kind === "agent") {
+            if (!hasAgentMd)
+                throw new Error(`No AGENT.md found at ${agentMdPath} -- publish --kind agent must point at a folder containing AGENT.md.`);
+        }
+        else if (kind === "skill") {
+            if (!hasSkillMd)
+                throw new Error(`No SKILL.md found at ${skillMdPath} -- publish --kind skill must point at a folder containing SKILL.md.`);
+        }
+        else if (kind === "mcp") {
+            if (!hasServerJson)
+                throw new Error(`No server.json found at ${serverJsonPath} -- publish --kind mcp must point at a folder containing server.json.`);
+        }
+        else {
+            // kind === undefined -- infer from whichever root file(s) are actually present
+            const present = [hasSkillMd && "SKILL.md", hasAgentMd && "AGENT.md", hasServerJson && "server.json"].filter(Boolean);
+            if (present.length > 1) {
+                throw new Error(`Multiple root files found at ${path} (${present.join(", ")}) -- pass --kind skill, --kind agent, or --kind mcp to disambiguate.`);
+            }
+            if (present.length === 0) {
+                throw new Error(`No SKILL.md, AGENT.md, or server.json found at ${path} -- publish must point at a skill, agent, or mcp folder's root.`);
+            }
+            if (hasAgentMd) {
+                resolvedKind = "agent"; // inferred: only AGENT.md present, no --kind needed
+            }
+            else if (hasServerJson) {
+                resolvedKind = "mcp"; // inferred: only server.json present, no --kind needed
+            }
+            // else: hasSkillMd only -- resolvedKind stays undefined (unchanged existing behavior, server defaults to 'skill')
         }
         const archive = await tarGzDirectory(path);
-        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository }, jsonOutput);
+        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository, kind: resolvedKind }, jsonOutput);
         // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit
         // "lib" override, so DOM is included alongside the Node types) type-checks
         // Buffer/Uint8Array against `Uint8Array<ArrayBuffer>` specifically as of

package/dist/commands/read.js

@@ -1,19 +1,17 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
-export async function read(args) {
-    const jsonOutput = args.includes("--json");
-    const spec = args.find((a) => !a.startsWith("--"));
-    if (!spec)
-        throw new Error(USAGE);
-    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+export async function readSkillMd(owner, skill) {
     const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
     if (!detail.skill_versions) {
         throw new Error(`${owner}/${skill} has no published version.`);
     }
     // Mirrors view.ts's exact wording/tone for the same warning -- this
     // command reads straight from the same endpoint/version, so it must not
-    // be silent about handing back a yanked version's content.
+    // be silent about handing back a yanked version's content. Written to
+    // stderr, not stdout -- safe for MCP callers too (only stdout is reserved
+    // for the JSON-RPC stream).
     if (detail.skill_versions.yanked_at) {
         console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${detail.skill_versions.yanked_reason}` : "."}`);
     }
@@ -21,8 +19,28 @@ export async function read(args) {
     if (!content) {
         throw new Error(`${owner}/${skill}@${detail.skill_versions.version} has no SKILL.md content available.`);
     }
+    return {
+        version: detail.skill_versions.version,
+        content,
+        // The CLI already warns about a yanked version on stderr above, but an
+        // MCP caller has no visibility into stderr -- unlike skill_view, whose
+        // returned object already surfaces yanked_at/yanked_reason, skill_read
+        // was silently dropping this signal for MCP callers entirely. read()
+        // below still destructures only {version, content} for the CLI's
+        // --json output, so this addition doesn't change that shape.
+        yanked_at: detail.skill_versions.yanked_at ?? null,
+        yanked_reason: detail.skill_versions.yanked_reason ?? null,
+    };
+}
+export async function read(args) {
+    const jsonOutput = args.includes("--json");
+    const spec = args.find((a) => !a.startsWith("--"));
+    if (!spec)
+        throw new UsageError(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    const { version, content } = await readSkillMd(owner, skill);
     if (jsonOutput) {
-        console.log(JSON.stringify({ version: detail.skill_versions.version, content }));
+        console.log(JSON.stringify({ version, content }));
         return;
     }
     // Plain mode prints the raw content verbatim -- no formatting/labels/

package/dist/commands/remove.js

@@ -1,12 +1,13 @@
-import { existsSync, readdirSync, rmSync, rmdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname } from "node:path";
 import { removeLockfileEntry } from "../lockfile.js";
-import { LOCKFILE_PATH, parseOwnerSkill, skillDir } from "../spec.js";
-const USAGE = "Usage: ahood remove <owner>/<skill>";
+import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill remove <owner>/<skill>";
 export async function remove(args) {
     const spec = args[0];
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const key = `${owner}/${skill}`;
     const dir = skillDir(owner, skill);
@@ -20,11 +21,49 @@ export async function remove(args) {
     const ownerDir = dirname(dir);
     if (existsSync(ownerDir) && readdirSync(ownerDir).length === 0)
         rmdirSync(ownerDir);
+    // An agent installs as a single flat file (.claude/agents/<owner>@<skill>.md),
+    // never a directory under .claude/skills/ -- skillDir's rmSync above never
+    // touches it. Without this, removing an installed agent silently left the
+    // file on disk (still loaded by Claude Code forever) while reporting
+    // success and clearing the lockfile entry, so a later `update` wouldn't
+    // catch it either (ahood-cli final review finding #2).
+    const agentFile = agentPath(owner, skill);
+    const agentExisted = existsSync(agentFile);
+    if (agentExisted)
+        unlinkSync(agentFile);
     const hadLockfileEntry = removeLockfileEntry(LOCKFILE_PATH, key);
-    if (!dirExisted && !hadLockfileEntry) {
+    if (!dirExisted && !agentExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
     }
+    // An mcp-kind install has no directory or agent file on disk -- its only
+    // footprint here is the lockfile entry just cleared above and a live
+    // entry in .mcp.json (which add.ts's installMcpEntry merged in, possibly
+    // holding a resolved secret in its `env`). remove() doesn't attempt a real
+    // mcp removal, but staying silent about that entry repeats the exact
+    // false-assurance bug already fixed once for agent installs above: a user
+    // who removes an mcp artifact because they no longer trust it would be
+    // told it's gone while the MCP server (and its credential) still runs on
+    // the next Claude Code start -- and since the lockfile pin is now cleared,
+    // nothing will ever surface this again via `list`/`update`. So: warn
+    // instead of pretending it's gone.
+    if (existsSync(MCP_CONFIG_PATH)) {
+        try {
+            const parsed = JSON.parse(readFileSync(MCP_CONFIG_PATH, "utf-8"));
+            const mcpServers = parsed?.mcpServers;
+            if (mcpServers &&
+                typeof mcpServers === "object" &&
+                !Array.isArray(mcpServers) &&
+                Object.prototype.hasOwnProperty.call(mcpServers, skill)) {
+                console.warn(`WARNING: ${key} still has an entry in ${MCP_CONFIG_PATH} (which may contain secrets you entered) -- remove it manually.`);
+            }
+        }
+        catch {
+            // A malformed .mcp.json isn't this command's problem to fix or crash
+            // on -- add.ts's readMcpConfig is the strict validator for that path.
+            // Skip the warning rather than throw here.
+        }
+    }
     console.log(`Removed ${key}`);
 }

package/dist/commands/search.js

@@ -1,23 +1,29 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
-const USAGE = "Usage: ahood search <query> [--json] [--limit <n>]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
+export async function searchSkills(query, limit) {
+    const qs = new URLSearchParams({ q: query });
+    if (limit !== undefined)
+        qs.set("per_page", String(limit));
+    const { skills } = await apiJson(`/api/v1/skills?${qs}`);
+    return skills ?? [];
+}
 export async function search(args) {
     const jsonOutput = args.includes("--json");
-    const limit = flagValue(args, "--limit");
+    const limitStr = flagValue(args, "--limit");
     const queryParts = args.filter((a, i) => a !== "--json" && a !== "--limit" && args[i - 1] !== "--limit");
     const unknownFlag = queryParts.find((a) => a.startsWith("--"));
     if (unknownFlag)
-        throw new Error(`Unknown flag: ${unknownFlag}\n${USAGE}`);
+        throw new UsageError(`Unknown flag: ${unknownFlag}\n${USAGE}`);
     const query = queryParts.join(" ");
     if (!query)
-        throw new Error(USAGE);
-    if (limit !== undefined && (!/^\d+$/.test(limit) || Number(limit) < 1)) {
-        throw new Error(`--limit must be a positive integer (got "${limit}").\n${USAGE}`);
+        throw new UsageError(USAGE);
+    if (limitStr !== undefined && (!/^\d+$/.test(limitStr) || Number(limitStr) < 1)) {
+        throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${USAGE}`);
     }
-    const qs = new URLSearchParams({ q: query });
-    if (limit !== undefined)
-        qs.set("per_page", limit);
-    const { skills } = await apiJson(`/api/v1/skills?${qs}`);
+    const limit = limitStr !== undefined ? Number(limitStr) : undefined;
+    const skills = await searchSkills(query, limit);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
@@ -29,7 +35,7 @@ export async function search(args) {
     for (const skill of skills) {
         console.log(`${skill.profiles.username}/${skill.slug} - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads)`);
     }
-    if (limit !== undefined && skills.length >= Number(limit)) {
+    if (limit !== undefined && skills.length >= limit) {
         console.log(`(showing up to ${limit} results -- pass a higher --limit for more)`);
     }
 }

package/dist/commands/share.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 // These are skill-entity verbs (reached as `ahood skill share`/`ahood skill
 // unshare`, registered in SKILL_COMMANDS in index.ts), not group verbs --
 // they mutate a skill's sharing, not a group. Grouped together in one file
@@ -16,11 +17,11 @@ const UNSHARE_USAGE = "Usage: ahood skill unshare <owner>/<skill> --group <group
 export async function share(args) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
-        throw new Error(SHARE_USAGE);
+        throw new UsageError(SHARE_USAGE);
     const { owner, skill } = parseOwnerSkill(spec, SHARE_USAGE);
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
-        throw new Error(SHARE_USAGE);
+        throw new UsageError(SHARE_USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -31,11 +32,11 @@ export async function share(args) {
 export async function unshare(args) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
-        throw new Error(UNSHARE_USAGE);
+        throw new UsageError(UNSHARE_USAGE);
     const { owner, skill } = parseOwnerSkill(spec, UNSHARE_USAGE);
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
-        throw new Error(UNSHARE_USAGE);
+        throw new UsageError(UNSHARE_USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share/${encodeURIComponent(groupSlug)}`, { method: "DELETE" });
     console.log(`Unshared ${owner}/${skill} from ${groupSlug}.`);
 }

package/dist/commands/star.js

@@ -6,7 +6,7 @@ import { parseOwnerSkill } from "../spec.js";
 // deletes any matching row), so starring an already-starred skill or
 // unstarring one you never starred is a no-op 200, not an error.
 export async function star(args) {
-    const USAGE = "Usage: ahood star <owner>/<skill>";
+    const USAGE = "Usage: ahood skill star <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "POST",
@@ -14,7 +14,7 @@ export async function star(args) {
     console.log(`Starred ${owner}/${skill}.`);
 }
 export async function unstar(args) {
-    const USAGE = "Usage: ahood unstar <owner>/<skill>";
+    const USAGE = "Usage: ahood skill unstar <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "DELETE",

package/dist/commands/token.js

@@ -1,5 +1,6 @@
 import { apiJson } from "../http.js";
 import { confirm } from "../confirm.js";
+import { UsageError } from "../usage-error.js";
 export async function token(args) {
     const [subcommand, ...rest] = args;
     switch (subcommand) {
@@ -10,13 +11,13 @@ export async function token(args) {
         case "revoke":
             return tokenRevoke(rest);
         default:
-            throw new Error("Usage: ahood token create <name>|list [--json]|revoke <id> [--yes]");
+            throw new UsageError("Usage: ahood token create <name>|list [--json]|revoke <id> [--yes]");
     }
 }
 async function tokenCreate(args) {
     const name = args[0];
     if (!name)
-        throw new Error("Usage: ahood token create <name>");
+        throw new UsageError("Usage: ahood token create <name>");
     // Note: this itself requires an existing session-backed token or a
     // browser login -- per docs/adr/backend/0001-backend-services.md's Phase
     // 3 section, tokens can't mint tokens (POST /auth/tokens is session-only,
@@ -52,7 +53,7 @@ async function tokenRevoke(args) {
     const yes = args.includes("--yes");
     const id = args.find((a) => !a.startsWith("--"));
     if (!id)
-        throw new Error("Usage: ahood token revoke <id> [--yes]");
+        throw new UsageError("Usage: ahood token revoke <id> [--yes]");
     // --yes bypasses both the lookup and the prompt entirely, preserving the
     // original one-shot behavior (a single DELETE call) for scripts/CI that
     // already call `ahood token revoke <id> --yes` unattended.

package/dist/commands/unpublish.js

@@ -2,7 +2,8 @@ import { apiJson } from "../http.js";
 import { confirm } from "../confirm.js";
 import { parseOwnerSkill, parseOwnerSkillVersion } from "../spec.js";
 import { fetchVersionMeta } from "./add.js";
-const USAGE = "Usage: ahood unpublish <owner>/<skill>[@version] [--yes]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill unpublish <owner>/<skill>[@version] [--yes]";
 // A bare "owner/skill" has no "@" at all, so lastIndexOf("@") is -1 and this
 // is a whole-skill unpublish (preserves the exact pre-existing behavior).
 // "owner/skill@1.2.3" has an "@" at index > 0 and is a single-version yank
@@ -16,7 +17,7 @@ export async function unpublish(args) {
     const yes = args.includes("--yes");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (isVersioned(spec)) {
         const { owner, skill, version: parsedVersion } = parseOwnerSkillVersion(spec, USAGE);
         // parseOwnerSkillVersion only validates *syntax* -- an omitted "@version"
@@ -63,7 +64,7 @@ export async function unpublish(args) {
         // the whole request, since the yank already took effect. Discarding the
         // response body would silently drop that signal (ahood-cli#68): the
         // pointer could now be stale with nothing in the terminal to say so, and
-        // a later `ahood add owner/skill` trusts latest_version_id completely.
+        // a later `ahood skill add owner/skill` trusts latest_version_id completely.
         if (result.latest_version_warning) {
             console.warn(`WARNING: ${result.latest_version_warning}`);
         }
@@ -82,5 +83,5 @@ export async function unpublish(args) {
         return;
     }
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, { method: "DELETE" });
-    console.log(`Unpublished ${key}. Run \`ahood remove ${key}\` to also remove your local copy.`);
+    console.log(`Unpublished ${key}. Run \`ahood skill remove ${key}\` to also remove your local copy.`);
 }

package/dist/commands/update.js

@@ -1,7 +1,8 @@
 import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
 import { add, fetchVersionMeta } from "./add.js";
-const USAGE = "Usage: ahood update [<owner>/<skill> ...] [--dry-run] [--json]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]";
 async function previewSkill(ownerSlashSkill, currentVersion) {
     const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
     const meta = await fetchVersionMeta(owner, skill, "latest");
@@ -47,7 +48,7 @@ export async function update(args) {
     const dryRun = args.includes("--dry-run");
     const jsonOutput = args.includes("--json");
     if (jsonOutput && !dryRun) {
-        throw new Error(`--json is only supported together with --dry-run.\n${USAGE}`);
+        throw new UsageError(`--json is only supported together with --dry-run.\n${USAGE}`);
     }
     const targets = args.filter((a) => a !== "--dry-run" && a !== "--json");
     const lockfile = readLockfile(LOCKFILE_PATH);
@@ -88,7 +89,7 @@ export async function update(args) {
     for (const ownerSlashSkill of skillKeys) {
         if (!lockfile[ownerSlashSkill]) {
             // Reachable two ways: an explicitly-named skill that was never
-            // installed (`ahood add` is the right command for that -- `update`
+            // installed (`ahood skill add` is the right command for that -- `update`
             // must not silently install and pin it), or -- when targets came from
             // the lockfile itself -- the lockfile changing out from under us
             // mid-loop. Either way: skip, don't abort.
@@ -96,6 +97,22 @@ export async function update(args) {
             continue;
         }
         try {
+            // add() always hits the .mcp.json collision check for an mcp-kind
+            // entry that's already installed (that's the very definition of
+            // "already installed" for that kind), so calling it unconditionally
+            // here would make `ahood skill update` with no arguments permanently
+            // report a failure and exit 1 for every user who has ever installed
+            // an mcp artifact, even when nothing needs updating. fetchVersionMeta
+            // already resolves `kind` as part of the normal "latest" lookup add()
+            // itself does, so resolving it here first lets this skip cleanly
+            // instead of updating and hitting that guaranteed error. This is a
+            // skip-and-report-cleanly fix, not real mcp-update support.
+            const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
+            const meta = await fetchVersionMeta(owner, skill, "latest");
+            if (meta.kind === "mcp") {
+                console.warn(`Skipping ${ownerSlashSkill}: mcp artifacts aren't updatable via this command yet.`);
+                continue;
+            }
             await add([ownerSlashSkill]); // no @version -- resolves to latest again
         }
         catch (error) {

package/dist/commands/versions.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
-const USAGE = "Usage: ahood versions <owner>/<skill> [--json]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill versions <owner>/<skill> [--json]";
 function formatSize(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -13,13 +14,17 @@ function formatSize(bytes) {
     }
     return `${value.toFixed(1)} ${units[unitIndex]}`;
 }
+export async function listSkillVersions(owner, skill) {
+    const { versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
+    return versions ?? [];
+}
 export async function versions(args) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
-    const { versions: list } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
+    const list = await listSkillVersions(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(list));
         return;

package/dist/commands/view.js

@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
 import { apiJson } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { parseOwnerSkill } from "../spec.js";
-const USAGE = "Usage: ahood view <owner>/<skill> [--json] [--web]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill view <owner>/<skill> [--json] [--web]";
 // Spawned with argv as an array (not a shell string), so a crafted owner/skill
 // can never inject shell syntax -- and both segments are already restricted
 // to a safe charset by parseOwnerSkill before this ever runs.
@@ -22,26 +23,29 @@ function openBrowser(url) {
         console.log(`Open this URL in your browser: ${url}`);
     }
 }
+export async function viewSkill(owner, skill) {
+    return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+}
 export async function view(args) {
     const jsonOutput = args.includes("--json");
     const web = args.includes("--web");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const url = `${getApiUrl()}/${owner}/${skill}`;
     if (web) {
         openBrowser(url);
         return;
     }
-    const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    const detail = await viewSkill(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(detail));
         return;
     }
     const field = (label, value) => console.log(`  ${label.padEnd(13)}${value}`);
     console.log(`${detail.owner}/${detail.slug}`);
-    // Mirrors the wording/tone of `ahood add`'s yanked warning (src/commands/add.ts)
+    // Mirrors the wording/tone of `ahood skill add`'s yanked warning (src/commands/add.ts)
     // and the website's skill detail page banner -- this is the one CLI surface
     // whose entire job is "let me check this out before deciding to install it",
     // so it must not be the one place that stays silent about a yanked version.