skillmds 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
 
+## 1.2.0
+
+`skillmd add` was rewritten. It no longer copies a skill into every agent folder it can find: it writes **one canonical copy** and links that copy into the agents you chose, in the scope you chose, and records what it did in a lock file.
+
+### Never litters your folders
+
+- In a terminal, `add` asks **Installation scope: Project / Global** before writing anything, then which of the detected agents to link into. The agent selection is remembered and pre-checked next time.
+- With `-y`, `--json`, piped stdin, or inside a host agent (Claude Code, Cursor, Codex, Gemini CLI, CI) the scope is auto-detected: **project** when the current directory carries `.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `AGENTS.md`, `CLAUDE.md`, `skills-lock.json` or an agent dot-dir, **global** otherwise. The run says which it picked.
+- A piped run with neither `-y` nor a scope flag now **exits 1 with a hint** instead of guessing. Running `skillmd add owner/name` from your Desktop no longer scatters `.claude/`, `.cursor/`, `.codex/`, `.agents/` there.
+- New `-p, --project` forces the current directory; `-g, --global` is unchanged. Cancelling a prompt installs nothing.
+- Project installs only touch agents that are **already present in the project** (or named with `-a`) — `add -p` never creates a folder for an agent the project does not use.
+
+### One canonical copy, links everywhere
+
+- The skill's files are written once to `.agents/skills/<name>` (project) or `~/.agents/skills/<name>` (global). Each chosen agent directory gets a **junction** (Windows) or **symlink** (everywhere else) pointing at it; if the filesystem refuses, the CLI falls back to a copy and says so.
+- `--mode link|copy` picks between the two (`link` is the default). The old `--copy` spelling still works as a hidden alias.
+- Writes are staged and moved into place, so an interrupted install never leaves a half-written skill behind.
+- `add` refuses to replace a skill installed from a **different source**, or a directory it does not track, unless you pass `--force`.
+- Local directory sources install **all** of the skill's files. GitHub and gist sources install `SKILL.md` only for now; registry installs deliver the full bundle.
+
+### Lock files
+
+- Project installs write `skills-lock.json` next to your code — sorted, no timestamps, designed to be committed and to produce clean diffs. Global installs write `~/.skillmd/lock.json`.
+- Each entry records the `source`, the `commit_sha` it came from, a `digest` of the installed files, the `agents` it is linked into, and the link `mode` per agent. `list`, `update`, `check` and `remove` all read it.
+
+### Real source grammar
+
+One parser now decides what a `<source>` argument means, and every command uses it:
+
+- `owner/name` — a registry slug (GitHub is the fallback).
+- `owner/repo#ref` — a branch, tag or commit.
+- `owner/repo/sub/path` — a subdirectory of a repo.
+- `owner/repo@skill` — one named skill inside a repo or pack.
+- `github:owner/repo` / `gh:owner/repo` — force the GitHub reading of a bare `owner/name`.
+- GitHub `tree/` and `blob/` URLs, with the ref in the URL preserved (a `blob` URL pointing at a `SKILL.md` resolves to its directory).
+- Gist URLs.
+- `--ref <ref>` overrides the ref on any GitHub source; `-l, --list` prints the skills a source contains without installing anything.
+- GitLab and `git@`/`ssh://` sources get a clear "clone it locally and run `skillmd add ./path/to/skill`" message instead of a confusing 404.
+
+### Production behaviour
+
+- **`list` / `ls`** — both scopes by default (`-g`, `-p` to narrow, `-a` to filter by agent, `--json`). Columns: name · scope · agents · mode · source. Skills that are on disk but not in a lock file — hand-made, or installed by 1.1.x — are tagged `untracked`.
+- **`remove` / `rm`** — takes `[names...]` or opens a picker; confirms unless `-y`. `--all` removes everything in scope (not combinable with names). `-a` unlinks only those agents and leaves the canonical copy alone; `-g`/`-p` narrow the scope, both are searched by default. `--json` supported; exits 1 when nothing was removed.
+- **`update [names]`** — lock-driven: it refreshes the **full bundle** from the source recorded for each skill, re-lints before writing, and short-circuits when the recorded `commit_sha` has not moved. `--check` reports without writing, `-g`/`-p` narrow the scope, `--json` is supported, and any failure exits 1. Untracked skills are reported and skipped with "reinstall with `skillmd add`".
+- **New `check` command** — `update --check` under its own name.
+- **`login` / `logout` / `init`** never prompt off a TTY: they exit 1 naming the flags to pass instead of hanging an agent or a CI job. All three accept `--json`.
+- A stored token is now **bound to the API host it was saved for**, so a token for one registry is never sent to another. `http://` bases are refused unless you pass `--insecure-http`.
+- `--token` on a terminal prints a warning on stderr: it lands in shell history and in every `ps` listing — prefer `skillmd login` or `SKILLMD_TOKEN`.
+
+### Security
+
+- Every file in a registry bundle must carry a sha256 and match it, including companion files delivered by URL. A missing or mismatched hash refuses the install rather than writing unverifiable content. The one exception is the bundle's inline `SKILL.md`: the registry generates that file from the skill's stored record rather than storing it, so there is no hash to compare it against. Every other path, hashed or not, is either verified or refused.
+- Registry bundles are capped at **200 files / 20 MB**. Every registry, GitHub raw and gist request carries a **30 s** timeout; the repository download itself runs through `giget`, which takes no deadline — it is bounded instead by the pre-download size check against the GitHub tree API and by the same 200 files / 20 MB caps once the files are on disk. Temp directories are cleaned up on both the success and the failure path.
+- Terminal escape sequences are stripped from registry text before it is printed, so a description can never repaint your terminal.
+- Windows reserved device names (`con`, `nul`, `lpt1`, …) are refused as skill or file names.
+- The install-count `POST /api/skills/<owner>/<name>/install` (body `{"via":"cli"}`, nothing else) is documented in the README and skipped entirely when `SKILLMD_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` is set.
+
+### MCP server rewritten in TypeScript
+
+- The server is now TypeScript on the same code path as the CLI — one installer, one source parser, one sanitiser, one set of schemas.
+- `skillmd_install` gained `scope`, `agents`, `mode`, `force` and `deny`, and installs through the canonical-copy-plus-links model like the CLI.
+- `dest` is **deprecated**: it is accepted only when it points at a known agent skills directory. Use `scope` + `agents`.
+- `skillmd_lint` diagnostics declare the correct severity enum (`warn`, not `warning`).
+- `skillmd_list_saved` results go through the same sanitiser as every other tool's output.
+
+### Agent table refreshed
+
+- codex, goose, amp and zed use the cross-agent `.agents/skills` convention; gemini-cli uses `.gemini/skills`; antigravity uses `.agent/skills`; droid uses `.factory/skills`.
+- `CLAUDE_CONFIG_DIR` and `CODEX_HOME` relocate those agents' global directories.
+- Project-only agents (eve, promptscript) no longer claim a global directory.
+- Legacy directories stay in the detection list, so an existing install is still found.
+
+### Removed
+
+- `--copy` is now a hidden alias of `--mode copy` (still works, no longer advertised).
+- The `yaml` dependency — nothing imported it since the validation engine moved to `@skillmds/core`.
+- `lint`'s undocumented `check` alias, which collided with the new `check` command. Use `skillmd lint`.
+
+### Upgrade notes
+
+- A token saved by an earlier `skillmd login --api <other-host>` is now treated as bound to `api.skillmd.com`. If you use a different registry, re-run `skillmd login --api <url>`.
+- Skills installed by 1.1.x show as `untracked` in `list` and are skipped by `update`. Re-run `skillmd add` on them once to bring them under the lock file.
+- If a script used `skillmd check .` to lint, change it to `skillmd lint .` — `check` now reports available updates.
+
+## 1.1.2
+
+- **MCP tool metadata.** Every tool now declares a `title`, `annotations` (all read-only except `skillmd_install`, none destructive), an `outputSchema`, and a description on every parameter; list-returning tools respond with `structuredContent: { items }`, `skillmd_lint` and `skillmd_install` return structured results, and refusals are flagged `isError`.
+- **Server metadata.** `initialize` reports a title, description, website URL, icons and usage instructions.
+- No behavior changes to what the tools do.
+
 ## 1.1.1
 
 - Releases are now published through npm Trusted Publishing (OIDC from GitHub Actions) with provenance; no long-lived npm tokens exist for this package.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/skillmds/assets/skillmd-banner.jpg" alt="SkillMD" width="560">
+  <img src="https://skillmd.com/brand/banner.png" alt="SkillMD" width="560">
 </p>
 
 # skillmds
@@ -27,25 +27,27 @@ This installs both the `skillmd` and `skillmds` commands. To run the CLI without
 npx skillmds lint .
 ```
 
-`npx skillmds <command>` runs the CLI; `npx skillmds` with no command starts the MCP server.
+**Which binary runs what.** `skillmds` with any argument runs the CLI. `skillmds` with no arguments starts the **MCP server** when stdin is piped (how an MCP client launches it), and opens the interactive CLI menu when there's a terminal attached. `skillmd` is always the CLI.
 
 ## CLI: `skillmd`
 
 | Command | Description |
 |---|---|
-| `skillmd lint [path]` (`check`) | Validate `SKILL.md` files; print diagnostics and a quality score. |
+| `skillmd lint [path]` | Validate `SKILL.md` files; print diagnostics and a quality score. |
 | `skillmd scan [path]` | Report scripts, network calls, and secret access. |
 | `skillmd rules [id]` | List lint rules, or show one. |
 | `skillmd init [name]` | Create a `SKILL.md` from a template. |
 | `skillmd search <query>` | Search the registry. |
-| `skillmd add <source>` | Install a skill (registry slug, GitHub repo, or local path). Lints before writing. |
-| `skillmd list` (`ls`) | List installed skills. |
-| `skillmd remove <names...>` (`rm`) | Remove installed skills. |
-| `skillmd update [names...]` | Update installed skills from the registry. |
+| `skillmd info <slug>` | Show a skill's registry record: verification, security flags, provenance, rating. |
+| `skillmd add <source>` | Install a skill (registry slug, GitHub source, gist, or local path). Lints before writing. |
+| `skillmd list` (`ls`) | List installed skills with their scope, agents, link mode and source. |
+| `skillmd remove [names...]` (`rm`) | Remove installed skills, or unlink them from specific agents. |
+| `skillmd update [names...]` | Update installed skills from the source recorded in the lock file. |
+| `skillmd check [names...]` | Report which installed skills have updates (`update --check`). |
 | `skillmd publish [path]` (`submit`) | Publish to the registry. Exits non-zero on lint errors. |
 | `skillmd login` / `logout` | Store or remove a token. |
 
-All commands accept `--json`.
+> `check` is a command of its own since 1.2.0. It used to be an alias of `lint` — scripts that ran `skillmd check .` to validate a skill should now run `skillmd lint .`.
 
 ### lint
 
@@ -57,19 +59,90 @@ skillmd lint . --fix
 ```
 
 Formats: `text` (default), `json`, `sarif` (GitHub Code Scanning), `github` (Actions annotations).
-Exit codes: `0` clean, `1` errors (or warnings with `--strict` / `--fail-on-warning`), `2` usage error.
+Exit codes: `0` clean, `1` errors (or warnings with `--strict` / `--fail-on-warning`).
 
 ### add
 
 ```bash
-skillmd add anthropic/pdf                 # registry slug
-skillmd add owner/repo                     # GitHub repo
-skillmd add ./path                         # local
-skillmd add anthropic/pdf -a claude-code -g
+skillmd add anthropic/pdf                      # registry slug
+skillmd add owner/repo                          # GitHub repo
+skillmd add owner/repo/skills/pdf#main          # a subfolder at a ref
+skillmd add owner/repo@pdf                      # one skill inside a repo or pack
+skillmd add https://github.com/owner/repo/tree/v2/skills/pdf
+skillmd add https://gist.github.com/user/0123456789abcdef
+skillmd add ./path                              # local directory
+skillmd add owner/repo --list                   # what's in there? install nothing
+skillmd add anthropic/pdf -a claude-code cursor -g
+skillmd add anthropic/pdf --mode copy           # no links; real files per agent
 skillmd add some/skill --deny executes_scripts
 skillmd add some/skill --skip-lint
 ```
 
+Sources: a registry slug `owner/name`; a GitHub repo, subdirectory, ref (`#ref`) or named skill (`@skill`), including `tree/` and `blob/` URLs; `github:`/`gh:` to force the GitHub reading of a bare `owner/name`; a gist URL; or a local path. `--ref <ref>` overrides the ref on any GitHub source. GitLab and `git@` sources aren't supported — clone them and install from the path.
+
+**Where skills land.** One canonical copy, linked into each agent you chose:
+
+| Scope | Flag | Canonical copy | Agent links | Lock file |
+| --- | --- | --- | --- | --- |
+| **Project** | `-p`, `--project` | `.agents/skills/<name>` | `./<agent-dir>/skills/<name>` | `skills-lock.json` (commit it) |
+| **Global** | `-g`, `--global` | `~/.agents/skills/<name>` | `~/<agent-dir>/skills/<name>` | `~/.skillmd/lock.json` |
+
+Each agent link is a junction on Windows and a symlink elsewhere, so updating the canonical copy updates every agent at once; `--mode copy` writes real files instead. A project install only touches agents the project already uses (or the ones you name with `-a`), so `add -p` never invents a folder for an agent you don't run.
+
+In a terminal, `add` asks for the scope (**Project** / **Global**) and then which detected agents to link into, remembering your agent choice for next time. Off a terminal the scope is auto-detected — see [Non-interactive use](#non-interactive-use).
+
+Re-installing the same skill from the same source is fine. Replacing a skill that came from a *different* source, or a directory the lock file doesn't know about, needs `--force`.
+
+### list / remove / update / check
+
+```bash
+skillmd list                       # everything installed, project and global
+skillmd list -p -a claude-code     # just this project, just one agent
+skillmd remove pdf                 # unlink from every agent, delete the copy
+skillmd remove pdf -a cursor       # unlink from Cursor only; copy stays
+skillmd remove --all -g -y         # clear your user-level skills
+skillmd check                      # which skills have updates?
+skillmd update                     # refresh them from their recorded sources
+skillmd update pdf -g
+```
+
+`list` shows name · scope · agents · mode · source. Skills installed by hand or by an older CLI have no lock entry and are tagged `untracked`: `update` skips them and tells you to re-run `skillmd add` once to start tracking them.
+
+`update` re-fetches the full bundle from the source recorded in the lock file, re-lints it, and skips skills whose recorded commit hasn't moved. `check` is `update --check`: it reports and writes nothing.
+
+`remove` with no names opens a picker, and confirms before deleting unless you pass `-y`.
+
+### Non-interactive use
+
+Every command works without a terminal, and none of them will ever block on a prompt when there isn't one.
+
+```bash
+skillmd add anthropic/pdf -y --json
+skillmd list --json
+skillmd check --json
+```
+
+- **`--json` requires `-y`** on `add`, and prints exactly one document on stdout; human text and warnings go to stderr, so `skillmd add … --json | jq` is always valid JSON. The `add` document is `{ ok, scope, installed: [{ name, canonical, targets, skipped, digest }], blocked, warnings }`.
+- **Scope auto-detection.** With `-y`, `--json`, piped stdin, or inside a host agent (Claude Code, Cursor, Codex, Gemini CLI, or any CI), `add` picks **project** when the working directory carries `.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `AGENTS.md`, `CLAUDE.md`, `skills-lock.json` or an agent dot-dir, and **global** otherwise. It says which it picked. Pass `-p` or `-g` to decide yourself.
+- **Piped with neither `-y` nor a scope flag exits 1** with a hint rather than guessing where to write.
+- **Exit codes.** `0` success; `1` anything that failed — lint errors, a blocked or denied skill, nothing removed, an update that couldn't be applied, or a prompt that was required but impossible. `login`, `logout` and `init` also exit 1 off a TTY, naming the flags to pass instead.
+- **Tokens.** Prefer `skillmd login` or `SKILLMD_TOKEN` over `--token`: a token on the command line is visible in your shell history and in every process listing on the machine, and the CLI warns about it. A stored token is bound to the API base it was saved for and is never sent anywhere else. An `http://` API base is refused unless you add `--insecure-http`.
+
+### What the CLI sends
+
+Installing a skill **from the registry** sends one fire-and-forget request so the skill's install count on skillmd.com stays accurate:
+
+```
+POST https://api.skillmd.com/api/skills/<owner>/<name>/install
+{"via":"cli"}
+```
+
+That is the whole payload — no identifiers, no paths, no machine information — and the install succeeds whether or not it goes through. Installs from GitHub, gists and local paths send nothing. To turn it off:
+
+```bash
+export SKILLMD_NO_TELEMETRY=1   # or the cross-tool DO_NOT_TRACK=1
+```
+
 ### publish
 
 ```bash
@@ -97,7 +170,9 @@ Other MCP clients:
 }
 ```
 
-Tools: `skillmd_search`, `skillmd_get`, `skillmd_install`, `skillmd_trending`, `skillmd_recommend`, `skillmd_list_saved`, `skillmd_lint`. `skillmd_install` writes a skill's `SKILL.md` and never executes scripts.
+Tools: `skillmd_search`, `skillmd_get`, `skillmd_install`, `skillmd_trending`, `skillmd_recommend`, `skillmd_list_saved`, `skillmd_lint`.
+
+`skillmd_install` runs the same installer as the CLI — it validates the skill, writes one canonical copy and links it into the chosen agents — and takes `scope` (`project` | `global`), `agents`, `mode` (`link` | `copy`), `force` and `deny`. It never executes scripts. The old `dest` parameter is deprecated and is accepted only when it points at a known agent skills directory; use `scope` + `agents` instead.
 
 ### Remote server (no install)
 
@@ -126,7 +201,7 @@ Resolution order, highest first:
 | Token | `--token` → `SKILLMD_TOKEN` → `~/.skillmd/config.json` |
 | API base | `--api` → `SKILLMD_API` → default registry |
 
-`SKILLMD_TOKEN` enables `skillmd_list_saved`, personalized recommendations, and publishing.
+`SKILLMD_TOKEN` enables `skillmd_list_saved`, personalized recommendations, and publishing. A stored token records the API base it belongs to and is only ever sent there. `SKILLMD_NO_TELEMETRY=1` (or `DO_NOT_TRACK=1`) disables the install-count ping described above.
 
 ## License
 

package/bin/skillmd-mcp.mjs

@@ -1,309 +1,3 @@
 #!/usr/bin/env node
-// SkillMD MCP server (stdio). Wraps the public SkillMD API so any MCP-capable agent
-// can search, fetch, install, and discover Agent Skills by name or task.
-//
-//   claude mcp add skillmd -- npx -y skillmds
-//
-// Env:
-//   SKILLMD_API   override API base (default https://api.skillmd.com)
-//   SKILLMD_TOKEN  personal access token (enables skillmd_list_saved / personalized recommend)
-
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { mkdir, writeFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { join, resolve, dirname, sep } from "node:path";
-
-const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-  } catch {
-    return "0.0.0";
-  }
-})();
-// Shared validation engine + registry helpers from @skillmds/core (a runtime
-// dependency of this package). Falls back gracefully when running from an
-// unbuilt source checkout.
-let lint = null;
-let skillMdFor = null;
-let isAllowedSourceUrl = () => false;
-try {
-  ({ lint, skillMdFor, isAllowedSourceUrl } = await import("@skillmds/core"));
-} catch {
-  /* skillmd_lint / skillmd_install will report that the engine is unavailable */
-}
-
-const API = process.env.SKILLMD_API || "https://api.skillmd.com";
-const TOKEN = process.env.SKILLMD_TOKEN || "";
-
-async function api(path, init = {}) {
-  const headers = { accept: "application/json", ...(init.headers || {}) };
-  if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;
-  const res = await fetch(API + path, { ...init, headers });
-  if (!res.ok) throw new Error(`SkillMD API ${res.status} on ${path}: ${await res.text().catch(() => "")}`);
-  return res.json();
-}
-const text = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
-
-// The public API returns site-oriented fields (ratings, counters, avatars,
-// ranker internals) that are noise for an agent picking a skill. Strip them
-// from every list-returning tool so results stay compact and rankable only
-// on what matters to the caller.
-const OMIT_FIELDS = new Set([
-  "type",
-  "verified",
-  "avg_rating",
-  "rating_count",
-  "install_count",
-  "save_count",
-  "owner_avatar",
-  "confident",
-  "category_slug",
-]);
-const trimItems = (items) => (items ?? []).map((s) => Object.fromEntries(Object.entries(s).filter(([k]) => !OMIT_FIELDS.has(k))));
-
-const TOOLS = [
-  {
-    name: "skillmd_search",
-    description: "Search SkillMD for Agent Skills by name, description, or task. Returns matching skills with their owner/name slug and install snippets.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Natural-language query or keywords" },
-        category: { type: "string", description: "Filter by category slug (e.g. devops, data, security)" },
-        verified_only: { type: "boolean", description: "Only verified skills" },
-        type: { type: "string", enum: ["single", "pack"], description: "single file or pack" },
-        min_rating: { type: "number", description: "Minimum average rating 0-5" },
-        limit: { type: "number", description: "Max results (default 20)" },
-      },
-      required: ["query"],
-    },
-  },
-  {
-    name: "skillmd_get",
-    description: "Fetch a single skill by slug (owner/name), including its SKILL.md body, provenance, license and security flags.",
-    inputSchema: { type: "object", properties: { slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" } }, required: ["slug"] },
-  },
-  {
-    name: "skillmd_install",
-    description:
-      "Install a skill by slug: writes its SKILL.md into the agent's skills directory. Never executes any scripts. Any skill installs; the response reports its security flags (docs_only / network_calls / executes_scripts / reads_secrets) as information.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" },
-        dest: { type: "string", description: "Target skills dir. Default ~/.claude/skills" },
-      },
-      required: ["slug"],
-    },
-  },
-  {
-    name: "skillmd_trending",
-    description: "Top skills on the SkillMD leaderboard. range: '30d' or 'all'.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        range: { type: "string", enum: ["30d", "all"], description: "Time window (default all)" },
-        category: { type: "string", description: "Optional category slug" },
-        limit: { type: "number", description: "Max results (default 20)" },
-      },
-    },
-  },
-  {
-    name: "skillmd_recommend",
-    description: "Recommend skills. If based_on is given, suggests skills similar to it (same category); otherwise returns trending.",
-    inputSchema: {
-      type: "object",
-      properties: { based_on: { type: "string", description: "A slug to base recommendations on" }, limit: { type: "number" } },
-    },
-  },
-  {
-    name: "skillmd_list_saved",
-    description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
-    inputSchema: { type: "object", properties: {} },
-  },
-  {
-    name: "skillmd_lint",
-    description:
-      "Validate a SKILL.md against the SkillMD spec and return diagnostics, security flags, and a quality score (0-100). Pass raw SKILL.md content, or a registry slug (owner/name) to fetch and lint.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        content: { type: "string", description: "Raw SKILL.md content to validate" },
-        slug: { type: "string", description: "Registry slug owner/name to fetch and validate" },
-      },
-    },
-  },
-];
-
-async function handleCall(name, args) {
-  switch (name) {
-    case "skillmd_search": {
-      const p = new URLSearchParams({ q: args.query, limit: String(args.limit ?? 20) });
-      if (args.category) p.set("category", args.category);
-      if (args.verified_only) p.set("verified", "true");
-      if (args.type) p.set("type", args.type);
-      if (args.min_rating != null) p.set("min_rating", String(args.min_rating));
-      const r = await api(`/api/search?${p}`);
-      return text(trimItems(r.items));
-    }
-    case "skillmd_get": {
-      const [owner, slugName] = String(args.slug).split("/");
-      const r = await api(`/api/skills/${owner}/${slugName}`);
-      return text(r);
-    }
-    case "skillmd_trending": {
-      const p = new URLSearchParams({ range: args.range ?? "all", limit: String(args.limit ?? 20) });
-      if (args.category) p.set("category", args.category);
-      const r = await api(`/api/leaderboard?${p}`);
-      return text(trimItems(r.items));
-    }
-    case "skillmd_recommend": {
-      if (args.based_on) {
-        const [owner, slugName] = String(args.based_on).split("/");
-        const base = await api(`/api/skills/${owner}/${slugName}`).catch(() => null);
-        if (base?.category_slug) {
-          const r = await api(`/api/leaderboard?range=all&limit=${args.limit ?? 10}&category=${base.category_slug}`);
-          return text(trimItems(r.items).filter((s) => s.slug !== args.based_on));
-        }
-      }
-      const r = await api(`/api/leaderboard?range=30d&limit=${args.limit ?? 10}`);
-      return text(trimItems(r.items));
-    }
-    case "skillmd_list_saved": {
-      if (!TOKEN) return text("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
-      const r = await api(`/api/favorites`);
-      return text(r.items ?? []);
-    }
-    case "skillmd_lint": {
-      if (!lint) return text("Validation engine unavailable — reinstall the skillmds package (npm i -g skillmds), or run `npm ci && npm run build` in a source checkout.");
-      let raw = args.content;
-      let slug;
-      let verified = false;
-      if (!raw && args.slug) {
-        const [owner, slugName] = String(args.slug).split("/");
-        const skill = await api(`/api/skills/${owner}/${slugName}`);
-        raw = skillMdFor(skill);
-        slug = slugName;
-        verified = !!skill.verified;
-      }
-      if (!raw) return text("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
-      const result = lint(raw, { ...(slug ? { slug } : {}), verified });
-      return text({ ok: result.ok, score: result.score, diagnostics: result.diagnostics, security: result.security });
-    }
-    case "skillmd_install": {
-      if (!skillMdFor) return text("skillmds is not fully installed — reinstall it (npm i -g skillmds) and try again.");
-      const [owner, slugName] = String(args.slug).split("/");
-      // Defense in depth: slugName becomes a directory name below — refuse
-      // anything outside the registry's slugify alphabet (path separators,
-      // "..", etc.) before touching the network or filesystem.
-      if (!/^[a-z0-9][a-z0-9-]*$/.test(slugName ?? "")) {
-        return text(`Refused: invalid skill name "${slugName}" — expected a lowercase slug.`);
-      }
-      const skill = await api(`/api/skills/${owner}/${slugName}`);
-      const flags = skill.security_flags ?? [];
-      // Verification never gates installs — any skill installs; flags are
-      // reported in the response as information, not a wall.
-      const raw = skillMdFor(skill); // returns raw_md verbatim when the registry has it
-      if (lint) {
-        const result = lint(raw, { slug: slugName });
-        if (!result.ok) {
-          const errors = result.diagnostics.filter((d) => d.severity === "error");
-          return text(`Refused: ${args.slug} failed validation (${errors.map((d) => `${d.id}: ${d.message}`).join("; ")}). Not installed.`);
-        }
-      }
-      const baseDir = args.dest ? resolve(args.dest) : join(homedir(), ".claude", "skills");
-      const dir = join(baseDir, slugName);
-      await mkdir(dir, { recursive: true });
-      const root = resolve(dir);
-
-      // Zip-slip guard: refuse any path that resolves outside the skill's dir.
-      const writeSafe = async (relPath, contents) => {
-        const fp = resolve(dir, relPath);
-        if (fp !== root && !fp.startsWith(root + sep)) throw new Error(`unsafe path: ${relPath}`);
-        await mkdir(dirname(fp), { recursive: true });
-        await writeFile(fp, contents);
-      };
-
-      let written = 1;
-      let note = "";
-      if (skill.type === "pack") {
-        // Pull the full pack (SKILL.md + companion files) in one call. The JSON
-        // bundle avoids adding an unzip dependency to this standalone binary.
-        try {
-          const bundle = await api(`/api/skills/${owner}/${slugName}/bundle?format=json`);
-          // Resolve + integrity-check every file BEFORE writing any, so a
-          // tampered pack refuses cleanly instead of leaving a partial install.
-          const resolved = [];
-          for (const f of bundle.files ?? []) {
-            if (f.path.includes("..") || f.path.startsWith("/")) continue;
-            let buf;
-            if (f.content_base64 != null) {
-              buf = Buffer.from(f.content_base64, "base64");
-              // Registry-stored files are content-addressed; verify the bytes
-              // match the registry's sha256. Files without one (the reconstructed
-              // inline SKILL.md) carry no hash and are skipped.
-              if (f.sha256) {
-                const got = createHash("sha256").update(buf).digest("hex");
-                if (got !== f.sha256) {
-                  const err = new Error(`integrity check failed for "${f.path}"`);
-                  err.integrity = true;
-                  throw err;
-                }
-              }
-            } else if (f.source_url && isAllowedSourceUrl(f.source_url)) {
-              const r = await fetch(f.source_url).catch(() => null);
-              if (!r || !r.ok) continue;
-              buf = Buffer.from(await r.arrayBuffer());
-            } else continue;
-            resolved.push({ path: f.path, contents: f.path === "SKILL.md" ? raw : buf });
-          }
-          for (const f of resolved) await writeSafe(f.path, f.contents);
-          written = resolved.length || 1;
-          if (!resolved.some((f) => f.path === "SKILL.md")) await writeSafe("SKILL.md", raw);
-        } catch (e) {
-          if (e && e.integrity) return text(`Refused: ${args.slug} failed integrity verification — ${e.message}. Not installed.`);
-          await writeSafe("SKILL.md", raw);
-          note = ` NOTE: pack assets could not be fetched — only SKILL.md was written. For the full pack run: npx skillmds add ${args.slug}`;
-        }
-      } else {
-        await writeSafe("SKILL.md", raw);
-      }
-      api(`/api/skills/${owner}/${slugName}/install`, { method: "POST", body: JSON.stringify({ via: "mcp" }) }).catch(() => {});
-      return text(`Installed ${args.slug} → ${dir} (${written} file${written === 1 ? "" : "s"}; security: ${flags.join(", ") || "unscanned"})${note}`);
-    }
-    default:
-      throw new Error(`Unknown tool: ${name}`);
-  }
-}
-
-async function startMcpServer() {
-  const server = new Server({ name: "skillmd", version: VERSION }, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    try {
-      return await handleCall(req.params.name, req.params.arguments ?? {});
-    } catch (e) {
-      return { isError: true, content: [{ type: "text", text: String(e?.message || e) }] };
-    }
-  });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("skillmd MCP server running (stdio)");
-}
-
-// This binary is invoked three ways:
-//   - `skillmds <anything>`       → run the CLI. commander owns argv, so known
-//     commands run and unknown commands get a proper "unknown command" error
-//     instead of silently starting an MCP server.
-//   - `skillmds` in a terminal    → run the CLI (opens the interactive menu)
-//   - `skillmds` over piped stdio → start the MCP server (how MCP clients launch it;
-//     they always connect stdin as a pipe, never a TTY, and pass no args)
-if (process.argv.length > 2 || process.stdin.isTTY) {
-  await import("../dist/cli.js"); // the CLI parses process.argv itself
-} else {
-  await startMcpServer();
-}
+// SkillMD MCP server (stdio) + CLI dispatch. Source: src/mcp/index.ts.
+import("../dist/mcp.js");