skill-land 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magithar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# skill-land
+
+Install an agent skill to the directory the agent **actually reads**, then verify it landed.
+Exits non-zero if it didn't.
+
+```bash
+npx skill-land Magithar/SKILLmama --for codex,antigravity
+npx skill-land Magithar/SKILLmama --for codex --verify   # audit an existing install
+```
+
+## Why this exists
+
+`npx skills add -a <agent> -g` reports success while writing to the wrong directory
+for 13 agents, including Codex, Antigravity, Cursor, GitHub Copilot, Gemini CLI and
+opencode. Reproduced against `skills@1.5.22` (latest) on 2026-08-08:
+
+```
+$ npx skills add Magithar/SKILLmama -a codex -g -y
+  copy → Codex
+  ✓ SKILLmama (copied)
+    → ~/.agents/skills/skillmama
+  Done!
+$ echo $?
+0
+$ ls ~/.codex/skills/
+                        # empty. Codex never sees it.
+```
+
+The correct path is in the CLI's own registry and never read. `isUniversalAgent()`
+(`dist/cli.mjs:1678`) classifies any agent whose *project* directory is
+`.agents/skills` as "universal", and `getAgentBaseDir()` then routes it to the
+canonical store, discarding `globalSkillsDir`:
+
+```js
+function isUniversalAgent(type) {
+	return agents[type].skillsDir === ".agents/skills";
+}
+```
+
+Every failure of this kind exits 0. Nothing in the ecosystem checks the install took.
+
+A second, separate bug: `-a claude-code,antigravity` is rejected as "Invalid agents"
+while both names appear in the valid list it prints.
+
+## Usage
+
+```bash
+npx skill-land <source> --for <agent> [options]
+```
+
+`<source>` is `owner/repo`, a GitHub URL, a raw `.md` URL, or a local path.
+
+| Option | Effect |
+|---|---|
+| `--for <agent>` | target agent; repeatable or comma-separated |
+| `--skill <name>` | which skill, when the source contains several |
+| `--project` | install into `./` instead of the user-global directory |
+| `--dry-run` | resolve and report, write nothing |
+| `--verify` | check an existing install, write nothing |
+| `--skip-security` | skip the SkillSpector scan (acknowledged, not silent) |
+| `--strict` | refuse to install anything SkillSpector flags |
+| `--list` | show known agents and their directories |
+
+```bash
+# install and verify
+skill-land Magithar/SKILLmama --for codex,antigravity
+
+# audit an install someone else did
+skill-land Magithar/SKILLmama --for codex --verify
+```
+
+## What "verified" means
+
+An install is not done until read-back confirms it:
+
+1. file exists at the target path
+2. non-empty
+3. byte-identical to the source
+4. frontmatter `name` matches the source
+
+Any failure prints the specific check that failed and **exits non-zero**. A write that
+throws (permissions, read-only directory) is reported as a failed install, not a crash.
+
+Tested against: truncated file, wrong skill in the right place, missing file,
+unwritable destination, and a real `npx skills add` install (correctly reported FAIL).
+
+## Antigravity
+
+Antigravity loads skills at startup, so an install cannot be confirmed live. Two
+candidate directories exist and both were created by Antigravity itself in the same
+second:
+
+```
+~/.gemini/antigravity/skills     what the skills CLI registry declares
+~/.gemini/config/skills          confirmed working by live testing
+```
+
+The `language_server` binary contains `skillsPaths` and `skills_paths`, so the search
+path is a configurable list rather than a single directory. Until that list is pinned
+down, `--for antigravity` writes to both and says so. Restart Antigravity fully after
+installing.
+
+## Security scan
+
+Skills run with full agent permissions, and this tool writes a file fetched from a URL into a
+directory an agent auto-loads. So it scans before writing, delegating to
+[NVIDIA/SkillSpector](https://github.com/NVIDIA/SkillSpector) rather than reimplementing it:
+
+```bash
+uv tool install git+https://github.com/NVIDIA/skillspector.git
+```
+
+**It reports, it does not block.** That is a measured decision, not a shortcut.
+
+Scanning 18 known-good skills already installed on a dev machine (2026-08-08, SkillSpector
+v2.8.1, `--no-llm`):
+
+| Verdict | Count |
+|---|---|
+| SAFE | 1 |
+| CAUTION | 9 |
+| **DO_NOT_INSTALL** | **8 (44%)** |
+
+SKILLmama's own `SKILL.md` scores **100 / CRITICAL / DO_NOT_INSTALL**, because its Phase 3.7
+DISCARD rules contain the literal phrase *"instructions to bypass safety checks"* and the pattern
+matcher reads that as an anti-refusal attack. A security checklist gets flagged for describing
+the attacks it checks for.
+
+A gate that blocks 44% of legitimate skills does not make anyone safer; it teaches people to pass
+the override flag reflexively. So findings are surfaced with file and line, and the decision stays
+with the user. `--strict` blocks on a flag for anyone who wants that.
+
+| SkillSpector verdict | Default | `--strict` |
+|---|---|---|
+| `SAFE` | installs | installs |
+| `CAUTION` | installs, findings shown | installs |
+| `DO_NOT_INSTALL` | installs, findings shown | **refuses, exit 1** |
+| scanner error | `treated as NOT scanned` | same |
+| not installed | `NOT SCANNED` + install hint | same |
+
+### Baselines are reported, never applied
+
+A skill repo can ship `.skillspector-baseline.yaml` to suppress findings. This installer scans
+**without** it, deliberately: a baseline that travels with untrusted code would let a malicious
+skill silence its own detections. SkillSpector does not auto-discover baselines either (verified:
+a baseline in the scanned directory has no effect unless `--baseline` is passed), so honouring one
+found in a fetched repo would be strictly less safe than the default.
+
+Instead its presence is surfaced as a fact about the skill, which is itself a signal:
+
+```
+security SAFE  SAFE, LOW, score 7, 2 issue(s)
+         NOTE this repo ships a baseline suppressing 2 finding(s).
+              Scanned WITHOUT it: a baseline from an untrusted repo can hide real findings.
+```
+
+`--no-llm` is always passed. Without it SkillSpector requires an LLM provider and exits 2 with no
+credentials, which would silently degrade this gate to a no-op for anyone without an API key. A
+check that did not run must never read as a check that passed.
+
+## Skill discovery
+
+Walks up to 10 levels, skipping only `.git`, `node_modules`, `.venv` and
+`__pycache__`, with a symlink-loop guard. Project-specific folder names are
+deliberately not hardcoded: a repo whose skill lives in `assets/` is legal, and
+skipping it produced a false "no SKILL.md found".
+
+When a source contains more than one skill the tool **refuses to guess**. It lists
+what it found and exits non-zero until you pass `--skill <name>`:
+
+```
+$ skill-land product-on-purpose/pm-skills --for codex
+  error  78 skills found; refusing to guess.
+         Pick one with --skill <name>:
+           define-hypothesis    ./skills/define-hypothesis/SKILL.md
+           ...
+```
+
+## Adding an agent
+
+Edit `agents.json`. `broken: true` marks agents where the upstream CLI misroutes a
+global install, which is what drives the warning note.
+
+## Scope
+
+Install and verify only. No registry, no publishing, no per-platform content
+transforms. One `SKILL.md` works across all of these agents; the failure mode here is
+a wrong-path bug, not a content-format problem.

package/agents.json

@@ -0,0 +1,87 @@
+{
+  "_comment": "Per-agent skill directories. Verified 2026-08-07 against skills@1.5.18. Agents marked broken:true are ones where `npx skills add -a <agent> -g` reports success but writes to ~/.agents/skills instead of the directory below, because isUniversalAgent() (cli.mjs:1678) classifies any agent whose PROJECT dir is .agents/skills as universal and discards its globalSkillsDir.",
+  "agents": {
+    "claude-code": {
+      "display": "Claude Code",
+      "global": "~/.claude/skills",
+      "project": ".claude/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": false
+    },
+    "codex": {
+      "display": "OpenAI Codex",
+      "global": "~/.codex/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "antigravity": {
+      "_paths": "Global dir is ~/.gemini/config/skills for ALL Antigravity surfaces (2.0, IDE, CLI); they consolidated config across the three clients. Sources: vercel-labs/skills#1470, where the agy binary's own docs give global root ~/.gemini/config/ with skills at skills/<name>/, and no ~/.gemini/antigravity-cli/skills string exists in the binary. Project dir <workspace>/.agents/skills confirmed by behavior 2026-08-08. The other two are written as fallbacks only, pending PR #1483 landing upstream.",
+      "display": "Antigravity",
+      "global": "~/.gemini/config/skills",
+      "alsoWrite": ["~/.gemini/antigravity/skills", "~/.gemini/skills"],
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": true,
+      "broken": true
+    },
+    "antigravity-cli": {
+      "display": "Antigravity CLI",
+      "global": "~/.gemini/antigravity-cli/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": true,
+      "broken": true
+    },
+    "gemini-cli": {
+      "display": "Gemini CLI",
+      "global": "~/.gemini/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "cursor": {
+      "display": "Cursor",
+      "global": "~/.cursor/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "github-copilot": {
+      "display": "GitHub Copilot",
+      "global": "~/.copilot/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "opencode": {
+      "display": "opencode",
+      "global": "~/.config/opencode/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "firebender": {
+      "display": "Firebender",
+      "global": "~/.firebender/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    },
+    "amp": {
+      "display": "Amp",
+      "global": "~/.config/agents/skills",
+      "project": ".agents/skills",
+      "file": "SKILL.md",
+      "restart": false,
+      "broken": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "skill-land",
+  "version": "1.0.0",
+  "description": "Install an agent skill to the directory the agent actually reads, then verify it landed. Exits non-zero if it didn't.",
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "antigravity",
+    "cursor",
+    "skills",
+    "install",
+    "verify"
+  ],
+  "homepage": "https://github.com/Magithar/skills/tree/main/tools/skill-land",
+  "bugs": {
+    "url": "https://github.com/Magithar/skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Magithar/skills.git",
+    "directory": "tools/skill-land"
+  },
+  "author": "Magithar",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "skill-land": "skill-land.mjs"
+  },
+  "files": [
+    "skill-land.mjs",
+    "agents.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill-land.mjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+// skill-land — install an agent skill and verify it actually landed.
+//
+// Exists because `npx skills add -a <agent> -g` reports success while writing to
+// ~/.agents/skills for 13 agents (Codex, Antigravity, Cursor, Copilot, ...). The
+// correct path is in its registry and never read: isUniversalAgent() (cli.mjs:1678)
+// classifies any agent whose PROJECT dir is .agents/skills as "universal" and
+// discards its globalSkillsDir. Every such failure exits 0.
+//
+// This tool owns the path table and refuses to exit 0 on an unverified install.
+
+import { execFileSync } from "child_process";
+import { createHash } from "crypto";
+import {
+  cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync,
+  readFileSync, realpathSync, rmSync, statSync,
+} from "fs";
+import { homedir, tmpdir } from "os";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { agents: AGENTS } = JSON.parse(readFileSync(join(HERE, "agents.json"), "utf-8"));
+
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+const expand = (p) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+const die = (msg) => { console.error(`\n  error  ${msg}\n`); process.exit(1); };
+
+// ---------------------------------------------------------------- source
+
+// Accepts: owner/repo | https://github.com/owner/repo | raw .md URL | local path
+function resolveSource(input) {
+  if (existsSync(input) && statSync(input).isDirectory())
+    return { kind: "dir", dir: resolve(input), label: resolve(input) };
+
+  if (/^https?:\/\/.*\.md(\?.*)?$/i.test(input))
+    return { kind: "raw", url: input, label: input };
+
+  const slug = input.replace(/^https?:\/\/github\.com\//i, "").replace(/\.git$/, "").replace(/\/$/, "");
+  if (!/^[\w.-]+\/[\w.-]+$/.test(slug))
+    die(`cannot parse source "${input}"\n         expected owner/repo, a github URL, a raw .md URL, or a local path`);
+  return { kind: "repo", url: `https://github.com/${slug}.git`, label: slug };
+}
+
+function fetchSource(src, tmp) {
+  if (src.kind === "dir") return src.dir;
+  if (src.kind === "raw") {
+    const dest = join(tmp, "SKILL.md");
+    execFileSync("curl", ["-fsSL", src.url, "-o", dest], { stdio: "pipe" });
+    return tmp;
+  }
+  execFileSync("git", ["clone", "--depth", "1", "--quiet", src.url, tmp], { stdio: "pipe" });
+  return tmp;
+}
+
+// ---------------------------------------------------------------- discovery
+
+// Only skip things that are never a skill anywhere. Project-specific folder
+// names must not be hardcoded here: a repo whose skill lives in assets/ is
+// perfectly legal, and skipping it produced a false "no SKILL.md found".
+const NEVER_SKILLS = new Set([".git", "node_modules", ".venv", "__pycache__"]);
+const MAX_DEPTH = 10;
+
+function findSkills(root) {
+  const hits = [];
+  const seen = new Set();
+  (function walk(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    let real;
+    try { real = statSync(dir).ino + ":" + statSync(dir).dev; } catch { return; }
+    if (seen.has(real)) return; // symlink loop guard
+    seen.add(real);
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory() && !NEVER_SKILLS.has(e.name)) { walk(p, depth + 1); continue; }
+      // isFile() is false for symlinks, and the skills CLI symlinks by default,
+      // so a symlinked SKILL.md must still count. Dedupe by real path below.
+      if (e.name !== "SKILL.md") continue;
+      if (e.isFile() || e.isSymbolicLink()) hits.push(p);
+    }
+  })(root, 0);
+
+  // A repo may symlink its own skill (e.g. .claude/skills → skillmama/). Those
+  // are the same skill, not two, so collapse by resolved target.
+  const byReal = new Map();
+  for (const p of hits) {
+    let key; try { key = realpathSync(p); } catch { key = p; }
+    const prev = byReal.get(key);
+    if (!prev || p.split("/").length < prev.split("/").length) byReal.set(key, p);
+  }
+  return [...byReal.values()].sort(
+    (a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+}
+
+// Never silently pick one skill out of many. A repo with 78 skills must not
+// install an arbitrary one and report success.
+function selectSkill(root, wanted) {
+  const hits = findSkills(root);
+  if (!hits.length)
+    die(`no SKILL.md found under ${root}\n         searched ${MAX_DEPTH} levels deep`);
+
+  const named = hits.map((p) => ({
+    path: p,
+    name: parseFrontmatter(readFileSync(p, "utf-8")).name || basename(dirname(p)),
+  }));
+
+  if (wanted) {
+    const w = wanted.toLowerCase();
+    const match = named.filter((n) => n.name.toLowerCase() === w);
+    if (!match.length)
+      die(`no skill named "${wanted}" in ${root}\n         available: ${named.map((n) => n.name).join(", ")}`);
+    if (match.length > 1)
+      die(`"${wanted}" is ambiguous, ${match.length} matches:\n         ${match.map((m) => m.path.replace(root, ".")).join("\n         ")}`);
+    return match[0].path;
+  }
+
+  if (named.length > 1) {
+    const shown = named.slice(0, 15).map((n) => `           ${n.name.padEnd(28)} ${n.path.replace(root, ".")}`);
+    die(
+      `${named.length} skills found in ${root}; refusing to guess.\n` +
+      `         Pick one with --skill <name>:\n` +
+      shown.join("\n") +
+      (named.length > 15 ? `\n           ... and ${named.length - 15} more` : "")
+    );
+  }
+  return named[0].path;
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return fm;
+}
+
+// ---------------------------------------------------------------- security
+
+// Skills run with full agent permissions, and this tool writes a file fetched
+// from a URL into a directory an agent auto-loads. So scan before writing.
+//
+// Delegates to NVIDIA/SkillSpector rather than reimplementing its pattern set.
+// Exit codes per its docs: 0 = SAFE or CAUTION, 1 = DO_NOT_INSTALL, 2 = error.
+//
+// Borrowed from SKILLmama's own Phase 3.5 lesson: never let a check that did
+// not run read as a check that passed. When the scanner is absent we say so
+// loudly and mark the install unscanned, rather than silently continuing.
+// --no-llm is not optional. Without it SkillSpector needs an LLM provider and
+// exits 2 with no credentials, which would silently degrade this gate to a
+// no-op for anyone without an API key.
+function securityScan(skillPath) {
+  let out = "", code = 0;
+  try {
+    out = execFileSync("skillspector",
+      ["scan", skillPath, "--no-llm", "--format", "json"],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 32 * 1024 * 1024 });
+  } catch (e) {
+    if (e.code === "ENOENT") return { status: "unavailable" };
+    code = typeof e.status === "number" ? e.status : 2;
+    out = e.stdout || "";
+  }
+
+  let ra = null, issues = [];
+  try {
+    const j = JSON.parse(out);
+    ra = j.risk_assessment || null;          // { score, severity, recommendation }
+    issues = Array.isArray(j.issues) ? j.issues : [];
+  } catch { /* fall through */ }
+
+  if (!ra) return { status: "error", detail: `skillspector exited ${code}, no parsable report` };
+
+  // A repo can ship .skillspector-baseline.yaml to suppress findings. We scan
+  // WITHOUT it deliberately: honouring a baseline that travels with untrusted
+  // code would let a malicious skill silence its own detections. Instead the
+  // baseline is surfaced as a fact about the skill, which is itself a signal.
+  let baseline = null;
+  for (const dir of [dirname(skillPath), join(dirname(skillPath), "..")]) {
+    const b = join(dir, ".skillspector-baseline.yaml");
+    if (existsSync(b)) {
+      const n = (readFileSync(b, "utf-8").match(/^\s*-\s*hash:/gm) || []).length;
+      baseline = { path: b, count: n };
+      break;
+    }
+  }
+
+  // Findings are reported, never used to block by default. Measured on this
+  // machine 2026-08-08: 8 of 18 known-good installed skills scored
+  // DO_NOT_INSTALL (44%), and SKILLmama's own SKILL.md scored 100/CRITICAL
+  // because its Phase 3.7 DISCARD rules literally contain the phrase
+  // "instructions to bypass safety checks". A gate that blocks half of all
+  // legitimate skills is worse than no gate: people learn to pass --force.
+  const top = [...issues]
+    .sort((a, b) => (b.confidence || 0) - (a.confidence || 0))
+    .slice(0, 3)
+    .map((i) => `${i.id} ${i.severity} ${i.location?.file || "?"}:${i.location?.start_line ?? "?"}`);
+
+  return {
+    status: ra.recommendation === "DO_NOT_INSTALL" ? "flagged"
+          : ra.recommendation === "CAUTION" ? "caution" : "pass",
+    detail: `${ra.recommendation}, ${ra.severity}, score ${ra.score}, ${issues.length} issue(s)`,
+    top, baseline,
+  };
+}
+
+// ---------------------------------------------------------------- verify
+
+// An install is not done until read-back confirms it. This is the whole point.
+function verify(target, expected) {
+  const checks = [];
+  const ok = (name, pass, detail) => { checks.push({ name, pass, detail }); return pass; };
+
+  if (!ok("file exists", existsSync(target), target)) return checks;
+
+  // Compare the raw bytes by hash. An earlier version compared
+  // readFileSync(...,"utf-8").length, which is UTF-16 code units, not bytes:
+  // it read 25266 for a 25546-byte file and would pass two different files
+  // that happened to share a character count.
+  const raw = readFileSync(target);
+  ok("non-empty", raw.length > 0, `${raw.length} bytes`);
+  const gotHash = sha256(raw);
+  ok("content matches source", gotHash === expected.hash,
+     `${raw.length} bytes sha ${gotHash.slice(0, 12)} vs ${expected.bytes} bytes sha ${expected.hash.slice(0, 12)}`);
+
+  const fm = parseFrontmatter(raw.toString("utf-8"));
+  if (expected.name) {
+    ok("frontmatter name matches", fm.name === expected.name,
+       `found ${fm.name ? `"${fm.name}"` : "none"}, expected "${expected.name}"`);
+  } else {
+    ok("parses", true, "no frontmatter in source, skipped name check");
+  }
+  return checks;
+}
+
+// ---------------------------------------------------------------- main
+
+const argv = process.argv.slice(2);
+if (!argv.length || argv.includes("-h") || argv.includes("--help")) {
+  console.log(`
+  skill-land <source> --for <agent> [options]
+
+    <source>     owner/repo | github URL | raw .md URL | local path
+
+  Options
+    --for <agent>   target agent (repeatable, or comma-separated)
+    --skill <name>  which skill, when the source contains several
+    --project       install into ./ instead of the user-global dir
+    --dry-run       resolve and report, write nothing
+    --verify        check an existing install, write nothing
+    --skip-security skip the SkillSpector scan (acknowledged, not silent)
+    --strict        refuse to install anything SkillSpector flags
+    --list          show known agents and their directories
+
+  Verifies the file landed where the agent actually reads. Exits non-zero if not.
+`);
+  process.exit(0);
+}
+
+if (argv.includes("--list")) {
+  console.log("\n  agent             directory                              upstream");
+  console.log("  " + "-".repeat(70));
+  for (const [k, a] of Object.entries(AGENTS)) {
+    console.log(`  ${k.padEnd(17)} ${a.global.padEnd(38)} ${a.broken ? "BROKEN" : "ok"}`);
+  }
+  console.log();
+  process.exit(0);
+}
+
+const flag = (n) => argv.includes(n);
+const values = (n) => argv.reduce((acc, a, i) =>
+  a === n && argv[i + 1] ? acc.concat(argv[i + 1].split(",")) : acc, []);
+
+// Flags that consume the next argument; their values are not the source.
+const VALUE_FLAGS = new Set(["--for", "--skill"]);
+const source = argv.find((a, i) => !a.startsWith("--") && !VALUE_FLAGS.has(argv[i - 1]));
+if (!source) die("no source given");
+
+const targets = values("--for").map((s) => s.trim()).filter(Boolean);
+if (!targets.length) die(`no --for <agent> given\n         known: ${Object.keys(AGENTS).join(", ")}`);
+for (const t of targets) if (!AGENTS[t]) die(`unknown agent "${t}"\n         known: ${Object.keys(AGENTS).join(", ")}`);
+
+const isProject = flag("--project");
+const dryRun = flag("--dry-run");
+const verifyOnly = flag("--verify");
+const skipSecurity = flag("--skip-security");
+const strict = flag("--strict");
+
+const src = resolveSource(source);
+const tmp = mkdtempSync(join(tmpdir(), "skill-install-"));
+let failed = 0;
+
+try {
+  const root = fetchSource(src, tmp);
+  const skillPath = selectSkill(root, values("--skill")[0]);
+  const body = readFileSync(skillPath, "utf-8");
+  const fm = parseFrontmatter(body);
+  const skillName = (fm.name || "skill").toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+  const rawBody = readFileSync(skillPath);
+  const expected = { bytes: rawBody.length, hash: sha256(rawBody), name: fm.name };
+
+  // Scan before any write. A blocked skill must never reach disk.
+  const scan = skipSecurity ? { status: "skipped" } : securityScan(skillPath);
+  const findings = (scan.top || []).length
+    ? "\n" + scan.top.map((t) => `           ${t}`).join("\n") : "";
+  // Reported, never applied. See securityScan().
+  const baselineNote = scan.baseline
+    ? `\n           NOTE this repo ships a baseline suppressing ${scan.baseline.count} finding(s).`
+    + `\n                Scanned WITHOUT it: a baseline from an untrusted repo can hide real findings.`
+    : "";
+  const SCAN_LINE = {
+    pass:        () => `  security SAFE  ${scan.detail}${baselineNote}`,
+    caution:     () => `  security CAUTION  ${scan.detail}${findings}${baselineNote}`,
+    flagged:     () => `  security FLAGGED  ${scan.detail}${findings}\n           SkillSpector flags ~44% of known-good skills; review, don't just trust it.\n           --strict to refuse installing flagged skills.${baselineNote}`,
+    error:       () => `  security ERROR  ${scan.detail}  — treated as NOT scanned`,
+    unavailable: () => `  security NOT SCANNED  skillspector not on PATH\n           uv tool install git+https://github.com/NVIDIA/skillspector.git`,
+    skipped:     () => `  security NOT SCANNED  --skip-security given`,
+  };
+
+  console.log(`\n  source   ${src.label}`);
+  console.log(`  skill    ${fm.name || "(no frontmatter name)"}  [${rawBody.length} bytes, sha ${expected.hash.slice(0,12)}]`);
+  console.log(`  from     ${skillPath.replace(root, ".")}`);
+  if (!verifyOnly) console.log(SCAN_LINE[scan.status]());
+  console.log("");
+
+  // Refuse to write a skill the scanner flagged. --force is an explicit,
+  // logged override, never a silent one.
+  if (!verifyOnly && strict && scan.status === "flagged") {
+    die(`--strict: SkillSpector reports ${scan.detail}\n         Review the findings above. Drop --strict to install anyway.`);
+  }
+
+  for (const agent of targets) {
+    const a = AGENTS[agent];
+    const bases = isProject
+      ? [resolve(a.project)]
+      : [a.global, ...(a.alsoWrite || [])].map(expand);
+
+    console.log(`  ${a.display}`);
+
+    for (const base of bases) {
+      const destDir = join(base, skillName);
+      const target = join(destDir, a.file);
+
+      if (dryRun) { console.log(`    would write  ${target}`); continue; }
+
+      // A write that throws is a failed install, not a crash. Report it the
+      // same way as a failed read-back so one exit path covers both.
+      let writeErr = null;
+      if (!verifyOnly) {
+        try {
+          mkdirSync(destDir, { recursive: true });
+          cpSync(skillPath, target);
+        } catch (e) {
+          writeErr = `${e.code || "error"}: ${e.message.split("\n")[0]}`;
+        }
+      }
+
+      const checks = writeErr
+        ? [{ name: "write", pass: false, detail: writeErr }]
+        : verify(target, expected);
+      const passed = checks.every((c) => c.pass);
+      if (!passed) failed++;
+
+      console.log(`    ${passed ? "OK  " : "FAIL"}  ${target}${verifyOnly ? "  (verify only)" : ""}`);
+      for (const c of checks) {
+        if (!c.pass) console.log(`            x ${c.name}: ${c.detail}`);
+      }
+    }
+
+    if (!dryRun && a.restart) console.log(`    note  restart ${a.display} fully; skills load at startup`);
+    if (a.broken) console.log(`    note  \`npx skills add -a ${agent} -g\` writes to ~/.agents/skills instead`);
+    console.log();
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+if (failed) {
+  console.error(`  ${failed} install(s) failed verification\n`);
+  process.exit(1);
+}
+if (!dryRun) console.log(`  ${verifyOnly ? "verified existing install" : "verified"}\n`);