@ahood/cli 0.6.0 → 0.7.1

package/README.md

@@ -211,9 +211,11 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood skill view\|show <owner>/<skill> [--json] [--web]` | Show a single skill's details -- tags, license, homepage, repository, dates, and more -- without installing it (alias: ahood skill show). |
 | `ahood skill read <owner>/<skill> [--json]` | Print a skill's full SKILL.md content, without installing it. |
 | `ahood skill versions <owner>/<skill> [--json]` | List a skill's published-version history -- version, changelog, size, and publish date. |
+| `ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]` | Show what changed between two published versions -- a SKILL.md diff plus an added/removed/changed file summary. |
 | `ahood skill list [--json]` | List your own skills, public and private. |
 | `ahood skill add <owner>/<skill>[@version]` | Install a skill into .claude/skills/, pinned in the lockfile. |
 | `ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]` | Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once. |
+| `ahood skill outdated [<owner>/<skill> ...] [--json]` | Read-only staleness check comparing current and latest versions (with changelog) for installed skills. |
 | `ahood skill remove <owner>/<skill>` | Uninstall and unpin a skill (local only). |
 | `ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a skill you own, changing only the flags you pass. |
 | `ahood skill unpublish <owner>/<skill>[@version] [--yes]` | Delete a skill from the registry for every consumer, or yank a single version, not just your local install (prompts for confirmation unless --yes is passed). |
@@ -222,7 +224,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>] [--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. |
+| `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>] [--changelog <text>] [--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

@@ -174,8 +174,11 @@ async function extractFreshVersion(buffer, 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) {
+// entry to disk the way extractFreshVersion does for skills. Exported so
+// `diff.ts` can reuse the exact same in-memory single-file extraction to
+// pull SKILL.md out of two downloaded version archives without ever writing
+// either to disk (ahood-cli#88).
+export async function extractSingleFileContent(buffer, entryName) {
     let decompressed;
     try {
         // Same decompression-bomb guard as extractTarGz above: a highly-
@@ -401,6 +404,24 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
     }
 }
+// Downloads a specific version's archive and verifies it against the
+// checksum in `meta`, WITHOUT extracting anything -- the shared first half
+// of add()'s download flow below, pulled out so `diff.ts` (ahood-cli#88) can
+// fetch two versions' archives the same verified way without duplicating
+// the download/checksum logic.
+export async function downloadVerifiedArchive(owner, skill, meta) {
+    const downloadRes = await apiFetch(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/download?version=${encodeURIComponent(meta.version)}`, { headers: { "X-Ahood-Source": "cli" }, redirect: "follow" });
+    if (!downloadRes.ok) {
+        const body = await downloadRes.text().catch(() => "");
+        throw new Error(`Download failed with status ${downloadRes.status}${body ? `: ${body}` : ""}`);
+    }
+    const buffer = await readBoundedBody(downloadRes, MAX_DOWNLOAD_BYTES);
+    const actualChecksum = createHash("sha256").update(buffer).digest("hex");
+    if (actualChecksum !== meta.checksum_sha256) {
+        throw new Error(`Checksum mismatch for ${owner}/${skill}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
+    }
+    return buffer;
+}
 export async function add(args) {
     const spec = args[0];
     if (!spec)
@@ -431,16 +452,7 @@ export async function add(args) {
     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" });
-    if (!downloadRes.ok) {
-        const body = await downloadRes.text().catch(() => "");
-        throw new Error(`Download failed with status ${downloadRes.status}${body ? `: ${body}` : ""}`);
-    }
-    const buffer = await readBoundedBody(downloadRes, MAX_DOWNLOAD_BYTES);
-    const actualChecksum = createHash("sha256").update(buffer).digest("hex");
-    if (actualChecksum !== meta.checksum_sha256) {
-        throw new Error(`Checksum mismatch for ${key}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
-    }
+    const buffer = await downloadVerifiedArchive(owner, skill, meta);
     if (meta.kind === "agent") {
         const content = await extractSingleFileContent(buffer, "AGENT.md");
         mkdirSync(AGENTS_ROOT, { recursive: true });

package/dist/commands/diff.js

@@ -0,0 +1,92 @@
+import { createPatch } from "diff";
+import { fetchVersionMeta, downloadVerifiedArchive, extractSingleFileContent } from "./add.js";
+import { parseOwnerSkill, SEMVER_RE } from "../spec.js";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]";
+// Both versions must be explicit semver here, unlike `add`'s
+// parseOwnerSkillVersion which lets "latest" default the version -- a diff
+// is meaningless without two concrete, unambiguous versions to compare, and
+// "latest" would silently mean two different things if the registry gained
+// a new version between resolving vA and vB.
+function validateVersion(version, spec) {
+    if (!SEMVER_RE.test(version)) {
+        throw new UsageError(`Invalid version "${version}" in "${spec}" -- expected a semver like 1.2.3.\n${USAGE}`);
+    }
+}
+// Extracts SKILL.md's content from a downloaded version archive. Unlike an
+// agent's AGENT.md (always present, since that's the only file an agent
+// package ever installs), a skill package could in principle omit
+// SKILL.md's presence from the manifest we already fetched -- checked
+// up front so a missing file produces a clean message instead of
+// extractSingleFileContent's generic "not found in the downloaded archive".
+async function fetchSkillMdContent(owner, skill, meta) {
+    if (!meta.manifest.some((f) => f.path === "SKILL.md" || f.path === "./SKILL.md")) {
+        throw new Error(`${owner}/${skill}@${meta.version} has no SKILL.md in its manifest.`);
+    }
+    const buffer = await downloadVerifiedArchive(owner, skill, meta);
+    const content = await extractSingleFileContent(buffer, "SKILL.md");
+    return content.toString("utf-8");
+}
+// Compares two versions' manifests by path. VersionMeta.manifest only
+// carries `{path}` (no per-file size or checksum), so "added"/"removed" are
+// fully determined by path presence, but "changed" can only be reported for
+// SKILL.md itself (the one file whose content we've already downloaded and
+// diffed above) -- there is no way to tell whether some other common path's
+// *content* differs without downloading and comparing it too, which is out
+// of scope for this command (see the resolution-plan comment on issue #88).
+function diffManifests(manifestA, manifestB, skillMdChanged) {
+    const pathsA = new Set(manifestA.map((f) => f.path));
+    const pathsB = new Set(manifestB.map((f) => f.path));
+    const added = [...pathsB].filter((p) => !pathsA.has(p)).sort();
+    const removed = [...pathsA].filter((p) => !pathsB.has(p)).sort();
+    const changed = [];
+    if (skillMdChanged && pathsA.has("SKILL.md") && pathsB.has("SKILL.md")) {
+        changed.push("SKILL.md");
+    }
+    return { added, removed, changed };
+}
+export async function diff(args) {
+    const jsonOutput = args.includes("--json");
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const [spec, versionA, versionB] = positional;
+    if (!spec || !versionA || !versionB)
+        throw new UsageError(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    validateVersion(versionA, `${spec} ${versionA}`);
+    validateVersion(versionB, `${spec} ${versionB}`);
+    const [metaA, metaB] = await Promise.all([
+        fetchVersionMeta(owner, skill, versionA),
+        fetchVersionMeta(owner, skill, versionB),
+    ]);
+    const [contentA, contentB] = await Promise.all([
+        fetchSkillMdContent(owner, skill, metaA),
+        fetchSkillMdContent(owner, skill, metaB),
+    ]);
+    const skillmdDiff = createPatch("SKILL.md", contentA, contentB, versionA, versionB);
+    const skillMdChanged = contentA !== contentB;
+    const manifest = diffManifests(metaA.manifest, metaB.manifest, skillMdChanged);
+    if (jsonOutput) {
+        console.log(JSON.stringify({ skillmd_diff: skillMdChanged ? skillmdDiff : "", manifest }));
+        return;
+    }
+    console.log(`${owner}/${skill}: ${versionA} -> ${versionB}`);
+    console.log("");
+    if (skillMdChanged) {
+        console.log(skillmdDiff);
+    }
+    else {
+        console.log("SKILL.md is unchanged between these versions.");
+    }
+    const summaryParts = [];
+    if (manifest.added.length > 0)
+        summaryParts.push(`Files added: ${manifest.added.join(", ")}`);
+    if (manifest.removed.length > 0)
+        summaryParts.push(`Files removed: ${manifest.removed.join(", ")}`);
+    if (manifest.changed.length > 0)
+        summaryParts.push(`Files changed: ${manifest.changed.join(", ")}`);
+    if (summaryParts.length > 0) {
+        console.log("");
+        for (const line of summaryParts)
+            console.log(line);
+    }
+}

package/dist/commands/init.js

@@ -18,14 +18,17 @@ function normalizeToSlug(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
-// publish.ts's only client-side check on SKILL.md is that the file exists
-// (see publish.ts's `existsSync(skillMdPath)`) -- actual frontmatter
+// publish.ts's only hard client-side check on SKILL.md is that the file
+// exists (see publish.ts's `existsSync(skillMdPath)`) -- actual frontmatter
 // validation happens server-side, after upload, as part of the processing
-// workflow described in publish.ts's POLL_INTERVAL_MS comment. There's no
-// parser to match locally, so this template instead follows the documented
-// Claude Code skill format: YAML frontmatter delimited by `---` lines, with
-// a `name` and a `description` field -- the same shape every real SKILL.md
-// in this ecosystem uses (see e.g. any installed skill under
+// workflow described in publish.ts's POLL_INTERVAL_MS comment. (Publish does
+// also do a best-effort, non-blocking scan of `description` at publish time
+// -- ahood-cli#93 -- but that's a warning, not a parser, and this scaffold's
+// job is to steer authors clear of it in the first place.) There's no real
+// YAML parser to match locally, so this template instead follows the
+// documented Claude Code skill format: YAML frontmatter delimited by `---`
+// lines, with a `name` and a `description` field -- the same shape every
+// real SKILL.md in this ecosystem uses (see e.g. any installed skill under
 // .claude/skills/<owner>/<skill>/SKILL.md). Keeping to exactly those two
 // fields, rather than inventing extra ones, means nothing here needs
 // updating just because publish.ts's own validation happens to be looser
@@ -40,6 +43,11 @@ name: ${name}
 # description: one or two sentences describing what this skill does and
 # when Claude should use it. This is the primary text Claude reads to
 # decide whether to invoke the skill, so be specific rather than generic.
+# Keep it on a single line, under 1024 characters, and free of "<"/">"
+# characters -- ahood skill publish warns about all three, because in
+# registry-first usage (no local file, loaded via the registry/MCP server)
+# this description is the *only* signal deciding whether the skill is ever
+# triggered at all.
 description: TODO -- describe what this skill does and when Claude should use it.
 ---
 

package/dist/commands/publish.js

@@ -27,7 +27,7 @@ async function pollVersionStatus(owner, skill, version) {
     }
     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 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" +
+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>] [--changelog <text>] [--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
@@ -63,6 +63,113 @@ function isExcluded(name) {
         return true;
     return EXCLUDED_PREFIXES.some((prefix) => name === prefix || name.startsWith(`${prefix}.`));
 }
+// ahood-cli#93: in registry-first usage (an agent consuming this skill via
+// the MCP server/registry, with no local SKILL.md ever loaded) the
+// frontmatter `description` is the *only* signal an agent sees to decide
+// whether to trigger this skill at all. A missing, oversized, or
+// malformed-enough-to-mis-parse description means the skill silently never
+// fires, and nothing today tells the author. This is a best-effort, targeted
+// text scan -- not a real YAML parser (see init.ts's comment above
+// buildSkillMd for why this codebase doesn't carry one) -- so it only needs
+// to catch what a real skill author would plausibly write, not every legal
+// YAML shape for `description:`.
+const MAX_DESCRIPTION_LENGTH = 1024;
+// Pulls just the `description:` value out of a SKILL.md's `---`-delimited
+// frontmatter block. Returns undefined when the frontmatter or the key
+// itself can't be found -- callers treat that the same as an empty
+// description rather than throwing, since this scan is advisory only.
+function extractSkillDescription(skillMd) {
+    const frontmatterMatch = skillMd.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!frontmatterMatch)
+        return undefined;
+    const lines = frontmatterMatch[1].split(/\r?\n/);
+    const descIndex = lines.findIndex((line) => /^description:/.test(line));
+    if (descIndex === -1)
+        return undefined;
+    const firstLineValue = lines[descIndex].slice("description:".length).trim();
+    // YAML block scalar ("description: >" folded, or "description: |"
+    // literal), optionally with a chomping/indentation indicator like ">-" or
+    // "|2". Everything indented under it, until a dedented or blank line, is
+    // the value -- this is the *correct* way to write a genuinely multi-line
+    // description, so it does not trip the rawMultiLine heuristic below.
+    const blockScalarMatch = firstLineValue.match(/^([>|])[+-]?\d*$/);
+    if (blockScalarMatch) {
+        const folded = blockScalarMatch[1] === ">";
+        const collected = [];
+        for (let i = descIndex + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.trim() === "") {
+                collected.push("");
+                continue;
+            }
+            if (!/^\s/.test(line))
+                break; // dedented back to frontmatter's top level -- block scalar is over
+            collected.push(line.trim());
+        }
+        const value = folded ? collected.filter(Boolean).join(" ") : collected.join("\n");
+        return { value, rawMultiLine: false };
+    }
+    // Plain (or quoted) single-line form. Strip a matching pair of wrapping
+    // quotes for the length/character checks below -- not a full YAML string
+    // unescape, just enough to not count the quote characters themselves.
+    let value = firstLineValue;
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            value = value.slice(1, -1);
+        }
+    }
+    // Heuristic for "the author typed real newlines into what should be one
+    // value": any non-blank line right after the description line that isn't
+    // itself a new top-level `key:` entry. Depending on its indentation, real
+    // YAML either folds this into the same scalar or fails to parse outright --
+    // neither is what a naive frontmatter-reading agent gets right, so either
+    // way it's worth flagging. This can't distinguish every edge case (e.g. a
+    // value that legitimately continues a nested structure), but skill
+    // frontmatter in practice is flat enough that it doesn't need to.
+    let rawMultiLine = false;
+    const extraLines = [];
+    for (let i = descIndex + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "")
+            break;
+        if (!/^\s/.test(line) && /^[^\s:]+:/.test(line))
+            break; // next top-level key -- description's value ended
+        rawMultiLine = true;
+        extraLines.push(line.trim());
+    }
+    if (extraLines.length > 0)
+        value = [value, ...extraLines].filter(Boolean).join(" ");
+    return { value, rawMultiLine };
+}
+// Non-blocking: this only ever calls console.warn (never sets
+// process.exitCode, never throws) so a weak description warns the author
+// without affecting the exit code or --json mode's structured stdout output.
+function warnAboutSkillDescription(skillMdPath) {
+    let content;
+    try {
+        content = readFileSync(skillMdPath, "utf8");
+    }
+    catch {
+        return; // publish's own existsSync check already guards this path being missing entirely
+    }
+    const extracted = extractSkillDescription(content);
+    const value = extracted?.value ?? "";
+    if (!value.trim()) {
+        console.warn(`WARNING: ${skillMdPath} has no (or an empty) description. In registry-first usage (an agent pulling this skill via the registry/MCP server, without ever loading this file) the description is the only signal deciding whether the skill is ever triggered -- without one, it effectively never will be.`);
+        return;
+    }
+    if (value.length > MAX_DESCRIPTION_LENGTH) {
+        console.warn(`WARNING: ${skillMdPath}'s description is ${value.length} characters, over the ${MAX_DESCRIPTION_LENGTH}-character recommended cap. An oversized description crowds out an agent's other context and is less likely to be read in full when it's deciding whether to trigger this skill.`);
+    }
+    if (extracted?.rawMultiLine) {
+        console.warn(`WARNING: ${skillMdPath}'s description spans multiple raw lines without a YAML block-scalar indicator (">" or "|"). This is easy to write by accident and breaks simple frontmatter parsers that only read a single line -- keep the description on one line, or use an explicit ">" (folded) or "|" (literal) block scalar if it genuinely needs to span multiple lines.`);
+    }
+    if (value.includes("<") || value.includes(">")) {
+        console.warn(`WARNING: ${skillMdPath}'s description contains a literal "<" or ">" character. These can be misread as markup or YAML block-scalar syntax by downstream parsers and renderers -- rewrite the description without them.`);
+    }
+}
 async function tarGzDirectory(dir) {
     const tar = pack();
     const gzip = createGzip();
@@ -111,6 +218,7 @@ function parsePublishArgs(args) {
     const homepage = flagValue(args, "--homepage");
     const repository = flagValue(args, "--repository");
     const kind = flagValue(args, "--kind");
+    const changelog = flagValue(args, "--changelog");
     let legacyPath;
     const first = args[0];
     if (first && !first.startsWith("--")) {
@@ -141,7 +249,20 @@ 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, kind };
+    return {
+        owner,
+        skill,
+        version,
+        path: pathFlag ?? legacyPath ?? ".",
+        name,
+        tagline,
+        tags,
+        license,
+        homepage,
+        repository,
+        kind,
+        changelog,
+    };
 }
 // 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`;
@@ -185,9 +306,16 @@ async function createSkillForPublish(owner, skill, opts, jsonOutput) {
     }
     return created;
 }
-async function initVersion(owner, skill, version, packageSizeBytes, createOpts, jsonOutput) {
+async function initVersion(owner, skill, version, packageSizeBytes, changelog, createOpts, jsonOutput) {
     const path = `/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/init`;
-    const body = JSON.stringify({ version, package_size_bytes: packageSizeBytes });
+    // changelog_md matches the field name versions.ts's SkillVersion type already
+    // reads on the GET side (ahood-cli#87) -- only sent when --changelog was
+    // passed, same "omit rather than null" convention as every other optional
+    // flag in this file (see createSkillForPublish's body above).
+    const initBody = { version, package_size_bytes: packageSizeBytes };
+    if (changelog !== undefined)
+        initBody.changelog_md = changelog;
+    const body = JSON.stringify(initBody);
     try {
         const init = await apiJson(path, { method: "POST", headers: { "Content-Type": "application/json" }, body });
         return { init };
@@ -212,7 +340,7 @@ 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, kind } = parsePublishArgs(args);
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, kind, changelog } = parsePublishArgs(args);
         const skillMdPath = join(path, "SKILL.md");
         const agentMdPath = join(path, "AGENT.md");
         const serverJsonPath = join(path, "server.json");
@@ -249,8 +377,16 @@ export async function publish(args) {
             }
             // else: hasSkillMd only -- resolvedKind stays undefined (unchanged existing behavior, server defaults to 'skill')
         }
+        // ahood-cli#93: fires for an explicit --kind skill, and for the
+        // inferred-skill case above (resolvedKind left undefined because
+        // SKILL.md was the only root file present) -- but not when SKILL.md
+        // merely happens to sit alongside an AGENT.md/server.json being
+        // published as --kind agent/mcp instead.
+        if (resolvedKind === "skill" || (resolvedKind === undefined && hasSkillMd)) {
+            warnAboutSkillDescription(skillMdPath);
+        }
         const archive = await tarGzDirectory(path);
-        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository, kind: resolvedKind }, jsonOutput);
+        const { init, created } = await initVersion(owner, skill, version, archive.length, changelog, { 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/help.js

@@ -30,9 +30,9 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         usage: "ahood mcp",
         summary: "Start an MCP server exposing read-only skill commands as tools over stdio.",
         desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
-            "skill_versions, skill_list, and whoami as MCP tools -- the same data ahood's --json commands already " +
-            "return, reachable as typed tool calls instead of parsed CLI output. Meant to be launched by an " +
-            "MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively.",
+            "skill_versions, skill_list, skill_outdated, and whoami as MCP tools -- the same data ahood's --json " +
+            "commands already return, reachable as typed tool calls instead of parsed CLI output. Meant to be " +
+            "launched by an MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively.",
     },
 ];
 export const SKILL_COMMANDS_HELP = [
@@ -70,6 +70,17 @@ export const SKILL_COMMANDS_HELP = [
         desc: "List a skill's published-version history: version, changelog, size, and publish date. Most-recent first.",
         flags: ["--json    Emit the raw version objects instead of formatted text."],
     },
+    {
+        usage: "ahood skill diff <owner>/<skill> <versionA> <versionB> [--json]",
+        summary: "Show what changed between two published versions -- a SKILL.md diff plus an added/removed/changed file summary.",
+        desc: "Show what changed between two published versions of a skill: a unified diff of SKILL.md's content, plus a " +
+            "summary of which files were added or removed based on the two versions' manifests (a common file's content " +
+            "can only be confirmed changed for SKILL.md itself, since manifests don't carry per-file checksums). Both " +
+            "versions must be explicit semver -- \"latest\" isn't accepted, since it could silently mean two different " +
+            "things if a new version is published between resolving each side.",
+        flags: ["--json    Emit {skillmd_diff, manifest: {added, removed, changed}} instead of formatted text."],
+        examples: ["ahood skill diff alice/pdf-tools 1.0.0 1.1.0", "ahood skill diff alice/pdf-tools 1.0.0 1.1.0 --json"],
+    },
     {
         usage: "ahood skill list [--json]",
         summary: "List your own skills, public and private.",
@@ -96,6 +107,15 @@ export const SKILL_COMMANDS_HELP = [
         ],
         examples: ["ahood skill update --dry-run", "ahood skill update alice/pdf-tools --dry-run --json"],
     },
+    {
+        usage: "ahood skill outdated [<owner>/<skill> ...] [--json]",
+        summary: "Read-only staleness check comparing current and latest versions (with changelog) for installed skills.",
+        desc: "Read-only staleness check across installed skills -- current vs. latest version, plus the changelog for " +
+            "anything behind. With no argument, checks every installed skill; with one or more given, checks just " +
+            "those. Never moves a lockfile pin or installs anything; equivalent to `ahood skill update --dry-run`.",
+        flags: ["--json    Emit structured preview objects instead of a formatted table."],
+        examples: ["ahood skill outdated", "ahood skill outdated alice/pdf-tools --json"],
+    },
     {
         usage: "ahood skill remove <owner>/<skill>",
         summary: "Uninstall and unpin a skill (local only).",
@@ -155,7 +175,7 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill init pdf-tools", "ahood skill init"],
     },
     {
-        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]",
+        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>] [--changelog <text>] [--json]",
         summary: "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.",
         desc: "Publish a new version of a skill, agent, or mcp server manifest from a folder containing SKILL.md, AGENT.md, or server.json. If the artifact " +
             "doesn't exist yet, this creates it first -- pass --name to set its display name, and --kind agent or --kind mcp if " +
@@ -172,6 +192,7 @@ export const SKILL_COMMANDS_HELP = [
             "--license <id>                An SPDX license identifier, e.g. MIT, used only when creating.",
             "--homepage <url>              The artifact's homepage URL, used only when creating.",
             "--repository <url>            The artifact's source repository URL, used only when creating.",
+            "--changelog <text>            What changed in this version, shown by `ahood skill versions`.",
             "--json                        Suppress human progress lines; print one {version,status,...} JSON object on completion (or {error} on failure).",
         ],
         examples: [

package/dist/index.js

@@ -17,6 +17,7 @@ import { share, unshare } from "./commands/share.js";
 import { view } from "./commands/view.js";
 import { read } from "./commands/read.js";
 import { versions } from "./commands/versions.js";
+import { diff } from "./commands/diff.js";
 import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
 import { init } from "./commands/init.js";
@@ -33,9 +34,16 @@ const SKILL_COMMANDS = {
     show: view,
     read,
     versions,
+    diff,
     list: listSkills,
     add,
     update,
+    // A discoverable name for what `update --dry-run` already does (ahood-cli#91)
+    // -- forces --dry-run regardless of what the caller passes, so `outdated`
+    // can never accidentally move a pin forward. Reuses update()'s existing
+    // "no targets = every installed skill, explicit targets = just those"
+    // behavior as-is; no new logic.
+    outdated: (args) => update([...args, "--dry-run"]),
     remove,
     edit,
     unpublish,

package/dist/mcp/tools.js

@@ -6,6 +6,7 @@ import { readSkillMd } from "../commands/read.js";
 import { listSkillVersions } from "../commands/versions.js";
 import { listOwnSkills } from "../commands/list.js";
 import { checkAuth } from "../commands/whoami.js";
+import { fetchVersionMeta } from "../commands/add.js";
 import { validateSegment } from "../spec.js";
 // MCP tool inputs arrive as separate owner/skill zod fields (not a single
 // "<owner>/<skill>" spec string like the CLI's argv), so they bypass
@@ -54,6 +55,55 @@ export function registerTools(server) {
         description: "List the authenticated caller's own skills, public and private.",
         inputSchema: {},
     }, safeTool(async () => listOwnSkills()));
+    server.registerTool("skill_outdated", {
+        description: "Compare an explicit list of {owner, skill, version} pins (e.g. from an agent's own memory of what it " +
+            "installed via MCP calls) against the registry's latest published version for each, returning " +
+            "up-to-date status and changelog -- without reading or requiring any local lockfile. One entry " +
+            "failing to resolve (e.g. a 404 for an unpublished skill) doesn't fail the whole batch; that entry's " +
+            "result carries an `error` field instead.",
+        inputSchema: {
+            skills: z
+                .array(z.object({
+                owner: z.string().min(1),
+                skill: z.string().min(1),
+                version: z.string().min(1),
+            }))
+                .min(1),
+        },
+    }, safeTool(async ({ skills }) => {
+        const results = [];
+        for (const { owner, skill, version } of skills) {
+            const label = `${owner}/${skill}`;
+            try {
+                validateOwnerAndSkill(owner, skill);
+                const meta = await fetchVersionMeta(owner, skill, "latest");
+                const upToDate = version === meta.version;
+                results.push({
+                    skill: label,
+                    current_version: version,
+                    latest_version: meta.version,
+                    up_to_date: upToDate,
+                    changelog_md: upToDate ? null : meta.changelog_md ?? null,
+                });
+            }
+            catch (error) {
+                // One skill being removed/yanked/unreachable/invalid must not abort
+                // resolution of the rest of the batch -- that's the whole point of
+                // accepting an array instead of a single owner/skill pair. Mirrors
+                // update.ts's own per-skill try/catch in its --dry-run loop.
+                const message = error instanceof Error ? error.message : String(error);
+                results.push({
+                    skill: label,
+                    current_version: version,
+                    latest_version: null,
+                    up_to_date: false,
+                    changelog_md: null,
+                    error: message,
+                });
+            }
+        }
+        return results;
+    }));
     server.registerTool("whoami", {
         description: "Report whether the configured token (AHOOD_TOKEN or a stored login) still authenticates.",
         inputSchema: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "diff": "^9.0.0",
     "tar-stream": "^3.2.1",
     "zod": "^4.5.4"
   },