@ahood/cli 0.5.2 → 0.7.0

package/README.md

@@ -201,6 +201,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood whoami [--json]` | Reports whether your stored token still authenticates. |
 | `ahood token create <name>\|list [--json]\|revoke <id> [--yes]` | Manage personal API tokens. |
 | `ahood completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
+| `ahood mcp` | Start an MCP server exposing read-only skill commands as tools over stdio. |
 
 ### Skill
 
@@ -210,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). |
@@ -221,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
 
@@ -273,6 +276,7 @@ ahood completion fish > ~/.config/fish/completions/ahood.fish
 - **Structured output everywhere.** `--json` is available on every read command and on `publish`/`update`, so an agent never has to scrape human-formatted text.
 - **Predictable failure.** A stable, documented [exit code](#exit-codes) per failure class, and error messages that never leak raw upstream infrastructure details — safe to surface directly to an agent's reasoning loop.
 - **A real "start here."** `ahood skill init <name>` scaffolds a valid `SKILL.md` an agent can extend, rather than requiring it to know the frontmatter format up front.
+- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp` starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, and `whoami` as typed tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp` (or `npx @ahood/cli@latest mcp`) as a stdio server.
 
 ## Development
 

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/list.js

@@ -1,7 +1,11 @@
 import { apiJson } from "../http.js";
+export async function listOwnSkills() {
+    const { skills } = await apiJson("/api/v1/skills?mine=true");
+    return skills ?? [];
+}
 export async function listSkills(args = []) {
     const jsonOutput = args.includes("--json");
-    const { skills } = await apiJson("/api/v1/skills?mine=true");
+    const skills = await listOwnSkills();
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;

package/dist/commands/mcp.js

@@ -0,0 +1,7 @@
+import { startMcpServer } from "../mcp/server.js";
+// `ahood mcp` takes no subcommands/flags in v1. Unlike every other
+// account-scoped command it never returns until the client disconnects --
+// see startMcpServer's comment.
+export async function mcp(_args) {
+    await startMcpServer();
+}

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/commands/read.js

@@ -2,19 +2,16 @@ 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 UsageError(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}` : "."}`);
     }
@@ -22,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/search.js

@@ -2,9 +2,16 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 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)
@@ -12,13 +19,11 @@ export async function search(args) {
     const query = queryParts.join(" ");
     if (!query)
         throw new UsageError(USAGE);
-    if (limit !== undefined && (!/^\d+$/.test(limit) || Number(limit) < 1)) {
-        throw new UsageError(`--limit must be a positive integer (got "${limit}").\n${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;
@@ -30,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/versions.js

@@ -14,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 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

@@ -23,6 +23,9 @@ 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");
@@ -35,7 +38,7 @@ export async function view(args) {
         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;

package/dist/commands/whoami.js

@@ -14,29 +14,20 @@ async function fetchProfile() {
         return undefined;
     }
 }
-export async function whoami(args = []) {
-    const wantsJson = args.includes("--json");
+// Pure auth-status check: no console output, no process.exitCode -- callers
+// (the CLI's whoami() below, and the MCP whoami tool) decide how to present
+// each outcome. Never throws; every failure mode is a normal return value.
+export async function checkAuth() {
     const token = resolveToken();
     if (!token) {
-        // Previously exited 0 here, defeating whoami's purpose as a scriptable
-        // auth check -- "no token configured at all" must fail just like "token
-        // rejected by the server" does below. Exit 4 ("authentication required
-        // or rejected"), not the generic 1 -- this is exactly the case the
-        // README's own exit-code table names as the canonical example of 4
-        // (ahood-cli#80).
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: false }));
-        else
-            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
-        process.exitCode = 4;
-        return;
+        return { authenticated: false, reason: "not_logged_in" };
     }
     // There is no endpoint that returns an identity for a bearer caller yet, so
-    // whoami can only answer "does this token still authenticate?". It probes
+    // this can only answer "does this token still authenticate?". It probes
     // /api/v1/auth/tokens, which is deliberately session-only (Task 3), and
     // reads the STATUS to tell the two failure modes apart -- swallowing every
-    // error and printing "Authenticated." unconditionally (as this did) meant a
-    // revoked token and a garbage token both reported success with exit code 0.
+    // error and reporting success unconditionally (as this used to) meant a
+    // revoked token and a garbage token both reported success.
     //   403 -> resolveCaller accepted the token, the route then rejected it for
     //          being a token rather than a session. The token is valid.
     //   401 -> resolveCaller could not resolve the token at all: unknown,
@@ -48,38 +39,66 @@ export async function whoami(args = []) {
         // A session-backed caller (only reachable if this ever runs against a
         // cookie-bearing client) -- the token list came back.
         const profile = await fetchProfile();
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: true, mode: "session", ...profile }));
-        else
-            console.log(profile ? `Authenticated as ${profile.username}.` : "Authenticated.");
+        return { authenticated: true, mode: "session", profile };
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
             const profile = await fetchProfile();
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: true, mode: "token", ...profile }));
-            else
-                console.log(profile
-                    ? `Authenticated as ${profile.username} (personal API token).`
-                    : "Authenticated with a personal API token.");
-            return;
+            return { authenticated: true, mode: "token", profile };
         }
         if (error instanceof ApiError && error.status === 401) {
-            // Same exit-4 reasoning as the "no token at all" branch above: the
-            // token was rejected by the server, which is the other half of the
-            // README's exit-code-4 definition ("or the token was refused").
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
-            else
-                console.error("Not authenticated -- your token is invalid or has been revoked.");
-            process.exitCode = 4;
-            return;
+            return { authenticated: false, reason: "invalid_token" };
         }
         const message = error instanceof Error ? error.message : String(error);
+        return { authenticated: null, error: message };
+    }
+}
+export async function whoami(args = []) {
+    const wantsJson = args.includes("--json");
+    const result = await checkAuth();
+    if (result.authenticated === false && result.reason === "not_logged_in") {
+        // Previously exited 0 here, defeating whoami's purpose as a scriptable
+        // auth check -- "no token configured at all" must fail just like "token
+        // rejected by the server" does below. Exit 4 ("authentication required
+        // or rejected"), not the generic 1 -- this is exactly the case the
+        // README's own exit-code table names as the canonical example of 4
+        // (ahood-cli#80).
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: false }));
+        else
+            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === false && result.reason === "invalid_token") {
+        // Same exit-4 reasoning as the "no token at all" branch above: the
+        // token was rejected by the server, which is the other half of the
+        // README's exit-code-4 definition ("or the token was refused").
         if (wantsJson)
-            console.log(JSON.stringify({ authenticated: null, error: message }));
+            console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
         else
-            console.error(`Could not verify your token: ${message}`);
+            console.error("Not authenticated -- your token is invalid or has been revoked.");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === null) {
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: null, error: result.error }));
+        else
+            console.error(`Could not verify your token: ${result.error}`);
         process.exitCode = 1;
+        return;
+    }
+    if (wantsJson) {
+        console.log(JSON.stringify({ authenticated: true, mode: result.mode, ...result.profile }));
+        return;
+    }
+    if (result.mode === "session") {
+        console.log(result.profile ? `Authenticated as ${result.profile.username}.` : "Authenticated.");
+    }
+    else {
+        console.log(result.profile
+            ? `Authenticated as ${result.profile.username} (personal API token).`
+            : "Authenticated with a personal API token.");
     }
 }

package/dist/help.js

@@ -26,6 +26,14 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         desc: "Print a shell completion script for the command names.",
         examples: ["ahood completion bash >> ~/.bashrc"],
     },
+    {
+        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, 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 = [
     {
@@ -62,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.",
@@ -88,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).",
@@ -147,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 " +
@@ -164,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,7 +17,9 @@ 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";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
 import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
@@ -32,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,
@@ -69,6 +78,7 @@ const COMMANDS = {
     whoami,
     token,
     completion,
+    mcp,
     skill: dispatchSkill,
     group: dispatchGroup,
 };

package/dist/mcp/safe-tool.js

@@ -0,0 +1,46 @@
+import { ApiError, NetworkError } from "../http.js";
+import { UsageError } from "../usage-error.js";
+// Mirrors exit-code.ts's exitCodeFor categorization (ahood-cli#83) -- one
+// error taxonomy for both the CLI's exit codes and MCP's error_code field,
+// rather than maintaining two.
+export function errorCodeFor(error) {
+    if (error instanceof UsageError)
+        return "usage_error";
+    if (error instanceof ApiError) {
+        if (error.status === 401 || error.status === 403)
+            return "auth_error";
+        if (error.status === 404)
+            return "not_found";
+        if (error.status >= 500)
+            return "network_error";
+        return "usage_error";
+    }
+    if (error instanceof NetworkError)
+        return "network_error";
+    return "general_error";
+}
+// Wraps an MCP tool's data-fetching logic so a thrown error never crosses
+// the stdio boundary as a raw exception -- caught here and turned into a
+// structured isError result instead. `fn` is the tool's own core function
+// (e.g. searchSkills), already adapted to take the single zod-validated
+// input object each MCP tool callback receives.
+export function safeTool(fn) {
+    return async (input) => {
+        try {
+            const result = await fn(input);
+            // Defensive backstop: JSON.stringify(undefined) evaluates to the JS
+            // value `undefined`, not a string -- if any tool's core function ever
+            // returns undefined (e.g. a malformed API response missing an
+            // expected key), the MCP SDK rejects that as an invalid tool result
+            // and throws a raw protocol-level error instead of the structured
+            // isError result this wrapper exists to guarantee. Coalescing to null
+            // keeps `text` a string no matter what `fn` returns.
+            return { content: [{ type: "text", text: JSON.stringify(result ?? null) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const body = { error: message, error_code: errorCodeFor(error) };
+            return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+        }
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { CLI_VERSION } from "../version.js";
+// Split from startMcpServer so tests can build a server and connect it to an
+// InMemoryTransport instead of real stdio.
+export function buildServer() {
+    const server = new McpServer({ name: "ahood", version: CLI_VERSION });
+    registerTools(server);
+    return server;
+}
+// Connects over stdio and blocks: StdioServerTransport reads process.stdin
+// for the life of the process. This is expected -- an MCP host spawns
+// `ahood mcp` as a long-lived subprocess and talks to it over stdio for as
+// long as the session lasts.
+export async function startMcpServer() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { safeTool } from "./safe-tool.js";
+import { searchSkills } from "../commands/search.js";
+import { viewSkill } from "../commands/view.js";
+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
+// parseOwnerSkill entirely and go straight to the core function -- which
+// URL-encodes them and hits the API. Running the same validateSegment checks
+// the CLI gets via parseOwnerSkill here closes that gap: an invalid segment
+// (e.g. "..") or an absurdly long one now fails locally as a UsageError
+// (safeTool maps it to error_code "usage_error") instead of reaching the
+// wire with the caller's bearer token.
+function validateOwnerAndSkill(owner, skill) {
+    const spec = `${owner}/${skill}`;
+    validateSegment(owner, "owner", spec);
+    validateSegment(skill, "skill", spec);
+}
+// Registers every v1 MCP tool. Read-only by design (ahood-cli#83's spec) --
+// each tool wraps the same core function the equivalent `ahood skill <verb>
+// --json` CLI path already calls, so there is exactly one source of truth
+// for what each of these returns.
+export function registerTools(server) {
+    server.registerTool("skill_search", {
+        description: "Search published skills in the ahood registry.",
+        inputSchema: { query: z.string().min(1), limit: z.number().int().positive().optional() },
+    }, safeTool(async ({ query, limit }) => searchSkills(query, limit)));
+    server.registerTool("skill_view", {
+        description: "Show a skill's details (tags, license, homepage, repository, dates, etc.) without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return viewSkill(owner, skill);
+    }));
+    server.registerTool("skill_read", {
+        description: "Read a skill's full SKILL.md content without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return readSkillMd(owner, skill);
+    }));
+    server.registerTool("skill_versions", {
+        description: "List a skill's published-version history (version, changelog, size, publish date).",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return listSkillVersions(owner, skill);
+    }));
+    server.registerTool("skill_list", {
+        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: {},
+    }, safeTool(async () => checkAuth()));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -32,7 +32,10 @@
     "sync-readme": "node scripts/sync-readme.mjs"
   },
   "dependencies": {
-    "tar-stream": "^3.2.1"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "diff": "^9.0.0",
+    "tar-stream": "^3.2.1",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/node": "^20",