get-skill 1.0.21

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
+
+## 1.0.21
+
+- **No more `tar@6` deprecation warning on install.** Upgraded `giget` 1.x → 3.x, whose GitHub downloads no longer depend on the deprecated (and CVE-flagged) `tar@6.2.1`. The `skillmds` dependency tree is now tar-free; download behavior (`skillmd add <github url>`, pack fallbacks) is unchanged.
+
+## 1.0.20
+
+- **`skillmd add` now installs to every agent on your machine.** Detection is machine-level (an agent's config dir under your home, e.g. `~/.cursor`), so agents no longer need a pre-existing `skills/` folder to be targeted. The agent registry grows from 5 to **60+**: Gemini CLI, Antigravity, Kiro, Warp, GitHub Copilot, Cline, Roo Code, Goose, Trae, Qwen Code, Amp, OpenClaw, Kilo Code, Hermes (Nous Research), Continue, Devin, OpenHands, Replit, Mistral Vibe, Zed, Kimi Code, Droid (Factory), Crush, Augment, Junie, and more — with per-agent dirs matching each agent's own convention (`~/.codeium/windsurf/skills` for Windsurf, `~/.gemini/antigravity/skills` for Antigravity, etc.). Agents sharing the cross-agent `.agents/skills` convention are written once and labelled with every agent they serve. `-a/--agent` still overrides.
+- Running from your home directory now behaves like `--global` (project scope rooted at `$HOME` *is* the global scope), so agents whose global skills live outside `~/<agent>/skills` get the right directory.
+
+## 1.0.19
+
+- **Clear diagnostics when the registry is blocked.** In sandboxed or proxied environments that deny network egress to `api.skillmd.com`, `skillmd add owner/name` used to fall back to GitHub and surface a misleading "repo not found" error. The CLI now tells 404 ("not in the registry" — GitHub fallback proceeds as before) apart from unreachable (DNS failure, proxy 403, 5xx): if the GitHub fallback also fails, the error names the blocked registry and says what fixes it (allowlist `api.skillmd.com`, or install via the SkillMD MCP server); if the fallback succeeds, a warning notes the copy came from GitHub, not the registry.
+
+## 1.0.18
+
+- **Cleaner tool output for agents.** `skillmd_search`, `skillmd_trending`, and `skillmd_recommend` no longer echo site-oriented fields (`avg_rating`, `rating_count`, `install_count`, `save_count`, `verified`, `type`, `owner_avatar`, `category_slug`, and the internal `confident` ranker flag). Results now carry just what an agent needs to pick a skill: slug, title, description, category, agents, repo stars, and the install snippet.
+- **Quality score no longer punishes ordinary skills.** The security flags (`reads_secrets`, `network_calls`, `executes_scripts`) are pattern matches against prose and code samples, not proof of anything unsafe — they now cost 2/1/5 points respectively (was 25/8/15), so a skill that merely documents an env var or a URL keeps its high score. Verified skills are floored at 85 (unless the content fails to parse). `skillmd_lint` passes a skill's verified status through to the score.
+
+## 1.0.16
+
+- **Installs are no longer gated on verification.** Any skill installs directly — verified or not — with no flag, no prompt, and no second step, from both the CLI (`skillmd add`) and the MCP `skillmd_install` tool. Security flags (network_calls, executes_scripts, reads_secrets, docs_only) are still shown on the result as information, but never block. `--deny <flag>` remains available as an opt-in for anyone who wants to exclude a flag; `--allow-unverified` is now a no-op kept for backward compatibility.
+
+## 1.0.15
+
+- Search is now **browsable in the interactive menu**: arrow through results, press Enter on one to see a card, and install it to your project or user directory — all without leaving the CLI (`← Back` at each level; Esc goes up one step, never quits).
+- Search results are clean two-line entries showing the source repo's **star count** (e.g. `★ 223.7k`) instead of the placeholder rating, with the description truncated to fit your terminal.
+- Fixes for narrow terminals: result rows are width-budgeted so they don't wrap and garble the menu; the result card prints once instead of repainting on every action.
+
+## 1.0.14
+
+- Interactive menu (`skillmds` in a terminal) no longer exits after one action — it returns to the menu until you pick **Quit**; cancelling a sub-prompt goes back to the menu instead of quitting.
+- "List installed skills" now shows project **and** global skills together, tagged `[agent/scope]`, replacing the misleading "Include global skills?" prompt (which actually toggled global-only vs project-only). Invalid skills show the parse reason.
+- The in-menu command reference now includes `info`.
+
+## 1.0.13
+
+Safe & easy installs release.
+
+- **Packs install their full file tree.** `skillmd add owner/pack` now downloads the pack's source directory (pinned to the registry's commit; falls back to the default branch with a warning if the pin is gone upstream), so `assets/` and `references/` files referenced by SKILL.md actually exist. Hardened: symlinks are skipped, 200-file/20MB caps, temp dirs cleaned up.
+- **Unverified skills prompt instead of hard-blocking.** Interactive installs show the lint score and security flags and ask before installing; non-interactive installs (and `-y`) still require the explicit `--allow-unverified`. Blocked output links the skill's page for review.
+- **New `skillmd info <slug>`** shows verification status, security flags, rating, provenance (source repo @ commit), and the install snippet. Unknown subcommands now print a proper error instead of silently starting the MCP server.
+- **MCP `skillmd_install` gained the CLI's safety gates**: refuses unverified skills unless `allow_unverified: true` (only after explicit human approval), validates before writing, reports security flags, and guards against malformed skill names.
+- **Installs are exact.** The registry now stores the published SKILL.md verbatim (`raw_md`) and installs deliver it byte-for-byte; reconstructed frontmatter (legacy rows) is YAML-quoted so descriptions with `:`/`#`/quotes can't corrupt the file.
+- Description limit aligned with Claude Code's real spec (1024 chars, was 500) — valid skills are no longer flagged "(invalid SKILL.md)" by `skillmd list`, and `list` now says *why* a file is invalid.
+
+## 1.0.12
+
+- Registry-native `skillmd` CLI shipped inside `skillmds`: `search`, `add`, `list`, `remove`, `update`, `publish`, `login`/`logout`, plus lint/scan/rules/init. (Release notes added retroactively.)
+
+## 1.0.11
+
+- Security flags render with full readable labels, each with its own marker: `⚑ Executes Scripts  ⚑ Calls Network  ⚑ Reads Secrets`.
+
+## 1.0.10
+
+- Quality score is now a composite of spec correctness, completeness, and **security risk** — skills that read secrets, execute scripts, or make network calls score lower (a risky/stub skill is no longer a green 100).
+- Lint output ends with a **Failed** section listing each failure's rule, message, and full path, so problems don't scroll off in a large run.
+- New `--errors-only` flag to show only failing skills.
+- Fixed emoji spacing/overlap; rule ids are grouped by severity per skill.
+- The closer states how many skills failed instead of a vague "Problems found".
+
+## 1.0.9
+
+- Compact lint output: one line per skill (status dot, score, name, rule-id chips) with a single summary line, instead of a tall multi-row block per skill. Linting a single skill still shows full diagnostic messages.
+
+## 1.0.8
+
+- `skillmds` with no command in a terminal now opens the interactive CLI menu; it only starts the MCP server when launched over piped stdio (how MCP clients run it). Previously a bare `npx skillmds` in a terminal appeared to hang on the silent MCP server.
+
+## 1.0.7
+
+- Nicer CLI output: colored PASS/FAIL, quality-score bars, `ERROR`/`WARN`/`INFO` badges, and a summary with average score.
+- Running `skillmd` (or `skillmds`) with no command on a terminal now opens a guided interactive menu (lint, scan, search, init, list). Piped/CI still prints help.
+- Progress spinner while scanning.
+
+## 1.0.6
+
+- Bundle the banner image in the package and serve it via jsDelivr so it renders on the npm page (the previous absolute URL was unreachable).
+
+## 1.0.5
+
+- The `skillmds` binary now dispatches: `skillmds <command>` (lint, scan, add, …) runs the CLI, while `skillmds` with no command starts the MCP server. This makes `npx skillmds lint .` work without the `-p` flag.
+
+## 1.0.4
+
+- `skillmd lint`/`scan` print a progress line to stderr and warn when scanning a home directory, so a directory scan never looks like a frozen blank screen.
+- Directory scans skip large build/OS directories (`AppData`, `node_modules`, `target`, …) and cap recursion depth, so `lint .` in a big tree terminates quickly.
+- Clearer message when no `SKILL.md` is found.
+- Bare `skillmd` (no command) prints help.
+
+## 1.0.3
+
+- CLI (`skillmd`) and MCP server (`skillmds`) now report their version from `package.json` instead of a hardcoded string.
+- READMEs rewritten; added this changelog.
+
+## 1.0.2
+
+- `skillmd lint`: skip directories that cannot be read (e.g. `EPERM` on protected system folders) instead of aborting the scan.
+
+## 1.0.1
+
+- Fix `skillmd_lint` in the MCP server: keep `yaml` external in the bundled engine so it loads at runtime (bundling a CommonJS module into ESM raised `Dynamic require of "process"`).
+
+## 1.0.0
+
+- Add the `skillmd` CLI, shipped alongside the MCP server in this package. Commands: `lint`/`check`, `scan`, `rules`, `init`, `search`, `add`, `list`, `remove`, `update`, `publish`/`submit`, `login`, `logout`.
+- Validation engine shared with the SkillMD registry: `SKILL.md` parser, lint rules `SK001`–`SK040`, security scan, quality score, and `text`/`json`/`sarif`/`github` output.
+- Add the `skillmd_lint` MCP tool.
+- MCP server and CLI authenticate with `Authorization: Bearer` tokens.
+
+## 0.1.1
+
+- Initial MCP server: `skillmd_search`, `skillmd_get`, `skillmd_install`, `skillmd_trending`, `skillmd_recommend`, `skillmd_list_saved`.

package/README.md

@@ -0,0 +1,128 @@
+<p align="center">
+  <img src="https://skillmd.com/brand/banner.png" alt="SkillMD" width="560">
+</p>
+
+# get-skill
+
+[![npm version](https://img.shields.io/npm/v/get-skill.svg)](https://www.npmjs.com/package/get-skill)
+[![license](https://img.shields.io/npm/l/get-skill.svg)](#license)
+
+Get any [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) (`SKILL.md`) into your agent, from the [SkillMD](https://skillmd.com) registry — 860,000+ skills, each linted, security-scanned and content-pinned.
+
+```bash
+npx get-skill add anthropic/pdf
+```
+
+> `get-skill` is the same package as [`skillmds`](https://www.npmjs.com/package/skillmds), published under a second, easier-to-remember name. Same build, same version. Either one works.
+
+## Install
+
+```bash
+npm i -g get-skill
+```
+
+That gives you three commands off one build:
+
+- **`get-skill`** — everything, in one word. `get-skill <command>` runs the CLI; bare `get-skill` starts the MCP server when an MCP client launches it, or the interactive menu in a terminal.
+- **`skillmd`** — the CLI on its own.
+- **`skillmds`** — the MCP server on its own.
+
+No install needed to try it:
+
+```bash
+npx get-skill search pdf
+npx get-skill lint .
+```
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `get-skill add <source>` | Install a skill (registry slug, GitHub repo, or local path). Lints before writing. |
+| `get-skill search <query>` | Search the registry. |
+| `get-skill lint [path]` (`check`) | Validate `SKILL.md` files; print diagnostics and a quality score. |
+| `get-skill scan [path]` | Report scripts, network calls, and secret access. |
+| `get-skill list` (`ls`) | List installed skills. |
+| `get-skill remove <names...>` (`rm`) | Remove installed skills. |
+| `get-skill update [names...]` | Update installed skills from the registry. |
+| `get-skill init [name]` | Create a `SKILL.md` from a template. |
+| `get-skill rules [id]` | List lint rules, or show one. |
+| `get-skill publish [path]` (`submit`) | Publish to the registry. Exits non-zero on lint errors. |
+| `get-skill login` / `logout` | Store or remove a token. |
+
+All commands accept `--json`.
+
+### add
+
+```bash
+get-skill add anthropic/pdf                 # registry slug (verified-only by default)
+get-skill add owner/repo                    # GitHub repo
+get-skill add ./path                        # local
+get-skill add anthropic/pdf -a claude-code -g
+get-skill add some/skill --deny executes_scripts
+get-skill add some/skill --skip-lint
+```
+
+### lint
+
+```bash
+get-skill lint ./my-skill
+get-skill lint . --format sarif > skillmd.sarif
+get-skill lint . --strict
+get-skill 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.
+
+### publish
+
+```bash
+get-skill login                # store a token from your skillmd.com account
+get-skill publish ./my-skill   # blocked on lint errors
+get-skill publish ./my-skill --dry-run
+get-skill publish ./my-skill --force   # publish despite warnings; never bypasses errors
+```
+
+## MCP server
+
+Claude Code:
+
+```bash
+claude mcp add skillmd -- npx -y get-skill
+```
+
+Other MCP clients:
+
+```jsonc
+{
+  "mcpServers": {
+    "skillmd": { "command": "npx", "args": ["-y", "get-skill"] }
+  }
+}
+```
+
+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.
+
+The CLI and the registry validate `SKILL.md` with the same engine, so they apply identical rules.
+
+## Find skills on skillmd.com
+
+- [Search all skills](https://skillmd.com/search) · [browse by category](https://skillmd.com/categories) · [by publisher](https://skillmd.com/publishers)
+- Install guides per agent: [Claude Code](https://skillmd.com/agents/claude-code) · [Cursor](https://skillmd.com/agents/cursor) · [Codex](https://skillmd.com/agents/codex) · [all 60+ agents](https://skillmd.com/agents)
+- [The SKILL.md format](https://skillmd.com/docs/format) · [CLI docs](https://skillmd.com/docs/cli) · [MCP docs](https://skillmd.com/docs/mcp) · [registry stats](https://skillmd.com/stats)
+
+## Configuration
+
+Resolution order, highest first:
+
+| Setting | Sources |
+|---|---|
+| Token | `--token` → `SKILLMD_TOKEN` → `~/.skillmd/config.json` |
+| API base | `--api` → `SKILLMD_API` → default registry |
+
+`SKILLMD_TOKEN` enables `skillmd_list_saved`, personalized recommendations, and publishing.
+
+## License
+
+MIT

package/bin/skillmd-mcp.mjs

@@ -0,0 +1,331 @@
+#!/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";
+import { stringify as stringifyYaml } from "yaml";
+
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+// Shared validation engine, bundled into ./vendor at publish time (npm run build).
+// Falls back gracefully if the vendor build is absent (e.g. running from source).
+let lint = null;
+try {
+  ({ lint } = await import("../vendor/index.js"));
+} catch {
+  /* skillmd_lint will report that validation is unavailable */
+}
+
+const API = process.env.SKILLMD_API || "https://api.skillmd.com";
+const TOKEN = process.env.SKILLMD_TOKEN || "";
+
+// Companion files not in R2 carry a registry-supplied source_url. Ingest only
+// pins these to GitHub raw hosts, so anything else is a hostile/compromised
+// registry response — refuse to fetch it (client-side SSRF guard).
+const ALLOWED_SOURCE_HOSTS = new Set(["raw.githubusercontent.com", "gist.githubusercontent.com"]);
+function isAllowedSourceUrl(u) {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === "https:" && ALLOWED_SOURCE_HOSTS.has(parsed.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+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" },
+      },
+    },
+  },
+];
+
+// KEEP IN SYNC with apps/cli/src/api.ts (reconstructSkillMd / skillMdFor) —
+// duplicated because the MCP bin ships as a standalone script; no automated
+// check enforces this.
+function reconstructSkillMd(skill) {
+  // Verbatim when the author shipped frontmatter; a frontmatter-less upstream
+  // SKILL.md gets the registry's name/description prepended so it parses.
+  if (skill.raw_md && /^\uFEFF?\s*---\r?\n/.test(skill.raw_md)) return skill.raw_md;
+  const fm = { name: skill.slug.split("/")[1] || skill.title, description: String(skill.description).replace(/\n/g, " ") };
+  if (skill.license) fm.license = skill.license;
+  return `---\n${stringifyYaml(fm)}---\n${skill.raw_md || skill.body_md || ""}`;
+}
+
+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 — run `npm run build` in the skillmds package.");
+      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 = reconstructSkillMd(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": {
+      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 = reconstructSkillMd(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");
+              // R2 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();
+}

package/bin/skillmd.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The `skillmd` CLI, shipped inside the `skillmds` package.
+import("../dist/cli.js");