skill-land 1.1.0 → 1.3.0

package/README.md

@@ -56,6 +56,8 @@ npx skill-land <source> --for <agent> [options]
 |---|---|
 | `--for <agent>` | target agent; repeatable or comma-separated |
 | `--skill <name>` | which skill, when the source contains several |
+| `--all` | every skill in the source, not just one |
+| `--verbose` | per-skill detail when `--all` (default: one line each) |
 | `--project` | install into `./` instead of the user-global directory |
 | `--dry-run` | resolve and report, write nothing |
 | `--verify` | check an existing install, write nothing |
@@ -69,38 +71,138 @@ skill-land Magithar/SKILLmama --for codex,antigravity
 
 # audit an install someone else did
 skill-land Magithar/SKILLmama --for codex --verify
+
+# audit every skill you have, however it was installed
+skill-land ~/.agents/skills --for antigravity --verify --all
+```
+
+## Auditing a whole directory
+
+`--all` takes every skill in the source instead of one. It is never the default:
+[`selectSkill()`](skill-land.mjs) refuses to guess when a source holds several,
+and `--all` is you saying you meant all of them.
+
+The use it was built for is `--verify --all` — checking whether the skills you
+already installed are where the agent actually reads, whatever put them there.
+That question is unanswerable today even if your setup works, because nothing in
+the ecosystem reads an install back:
+
+```
+$ skill-land ~/.agents/skills --for antigravity --verify --all
+
+  source   /Users/you/.agents/skills
+  skills   1 found
+  impeccable                    FAIL  0/3
+        x ~/.gemini/config/skills/impeccable/SKILL.md
+          file exists: ~/.gemini/config/skills/impeccable/SKILL.md
+        x ~/.gemini/skills/impeccable/SKILL.md
+          content matches source: 10401 bytes sha abd76e36cf1d vs 10401 bytes sha a1ea82ce80f4
+  1 skill, 3 failed
 ```
 
+That middle line is why the check compares hashes and not sizes: both files are
+10401 bytes and they are not the same file. A copy that drifted after install
+looks identical to `ls`.
+
+One line per skill, because a report nobody reads verifies nothing; `--verbose`
+restores the full per-target output. Failing paths are always named — a summary
+you have to re-run to act on is not a summary.
+
+With `--strict`, a flagged skill is skipped and the rest still install; the run
+exits non-zero and lists what it skipped. All-or-nothing across a directory would
+let one flagged skill block every clean one.
+
 ## What "verified" means
 
-An install is not done until read-back confirms it:
+A skill is a **directory**, not a file. `skill-land` copies every file under it and reads
+each one back. For each file:
 
 1. file exists at the target path
 2. non-empty
 3. byte-identical to the source
-4. frontmatter `name` matches the source
+4. frontmatter `name` matches the source (`SKILL.md` only)
 
 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.
 
+Self-contained skills are unaffected — the directory holds one file, so one file is copied.
+Multi-file skills are the reason this matters: `impeccable` ships 148 files, and an install
+of only its `SKILL.md` leaves every `node .../scripts/context.mjs` reference dangling.
+
+Where an agent has several directories it reads, `--verify` counts the skill as installed if
+it is **complete in any one of them**. Requiring every fallback to hold a copy reports
+working installs as broken.
+
+### What it cannot tell you
+
+Verification assumes the installer **copied**. Some installers **rewrite** on install — the
+`skills` CLI adapts `impeccable` for Antigravity, changing `.agents/skills/...` paths to
+`.gemini/skills/...` and `$impeccable` to `/impeccable`. Those files are correct and will
+still report `content matches source` failures, because they genuinely differ from the source.
+`skill-land` reports the difference and does not guess which side is right.
+
 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:
+Antigravity loads skills at startup, so an install cannot be confirmed live. The
+`agy` search path was stated by an Antigravity maintainer on 2026-09-05 in
+[antigravity-cli#103](https://github.com/google-antigravity/antigravity-cli/issues/103#issuecomment-5547952239):
 
 ```
-~/.gemini/antigravity/skills     what the skills CLI registry declares
-~/.gemini/config/skills          confirmed working by live testing
+~/.gemini/config/skills            primary; independently confirmed by live testing
+~/.gemini/skills                   fallback
+~/.gemini/antigravity-cli/skills   fallback
 ```
 
-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.
+`--for antigravity` writes to all three and says so. The `language_server` binary
+contains `skillsPaths` and `skills_paths`, so this is a configurable list rather than a
+single directory, and the maintainer statement covers the CLI — whether the IDE surface
+reads the same list is **unverified**.
+
+Checked against the shipped binaries (Antigravity 2026-07-30 build, inspected
+2026-09-05). `language_server` contains **no** `.gemini/*/skills` literal at all:
+`skills_paths` is a repeated protobuf field, so the client passes the list in, and
+skills resolve to `skills/<name>/` under a *customization root*. Both roots we write
+to are named in the shipped strings and config:
+
+- `~/.gemini/config/` holds `config.json` and `skills/` — the global root
+- `~/.gemini/antigravity-cli/` — "The CLI is configured via
+  `~/.gemini/antigravity-cli/settings.json`" (`language_server`)
+
+1.1.0 and earlier also wrote `~/.gemini/antigravity/skills`, on the reasoning that
+Antigravity created that directory itself. That reasoning was wrong: `app.asar` defines
+`~/.gemini/antigravity` as `IDE_OLD_DATA_DIR`, the **legacy IDE data directory** being
+migrated to `~/.gemini/antigravity-ide`. It was never a skills root. No longer written.
+
+### Live verification
+
+Confirmed against **`agy` 1.1.27 on 2026-09-05**, not inferred. A uniquely-named
+canary skill was planted in each candidate directory and `agy -p "/skills"` run from
+a neutral workspace:
+
+| directory | listed? |
+|---|---|
+| `~/.gemini/config/skills` | **yes** |
+| `~/.gemini/skills` | **yes** |
+| `~/.gemini/antigravity-cli/skills` | **yes** |
+| `~/.agents/skills` | no |
+| `~/.gemini/antigravity/skills` | no |
+
+All three directories `skill-land` writes to are read. The two it does not write to
+are not.
+
+`~/.agents/skills` appears **only** when its parent is the active workspace
+(`agy --add-dir $HOME`) — that is project-local behaviour, not a global search path,
+which is exactly what [#103](https://github.com/google-antigravity/antigravity-cli/issues/103)
+is asking to change. Confirmed still open at 1.1.27.
+
+Two side findings: project-local `.agents/skills` is read only when the directory is
+a **registered workspace** — being the current directory was not enough — and
+`.antigravity/skills` and `.agy/skills` are not read at all.
+
+Restart Antigravity fully after installing.
 
 ## Security scan
 

package/agents.json

@@ -18,10 +18,13 @@
       "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.",
+      "_paths": "LIVE VERIFIED against agy 1.1.27 on 2026-09-05: a uniquely-named canary skill was planted in each candidate directory and `agy -p /skills` run from a neutral workspace. Read as global: ~/.gemini/config/skills, ~/.gemini/skills, ~/.gemini/antigravity-cli/skills — matching the maintainer statement in google-antigravity/antigravity-cli#103 comment 5547952239. NOT read: ~/.agents/skills (appears only when its parent is the active workspace, i.e. `--add-dir $HOME`, which is project-local behavior, not global) and ~/.gemini/antigravity/skills (app.asar defines ~/.gemini/antigravity as IDE_OLD_DATA_DIR, the legacy IDE data dir migrating to ~/.gemini/antigravity-ide; never a skills root). Project dir .agents/skills is read only when the directory is a registered workspace — cwd alone was not enough; .antigravity/skills and .agy/skills are not read at all. language_server hardcodes no .gemini/*/skills literal: skills_paths is a repeated protobuf field the client fills in.",
       "display": "Antigravity",
       "global": "~/.gemini/config/skills",
-      "alsoWrite": ["~/.gemini/antigravity/skills", "~/.gemini/skills"],
+      "alsoWrite": [
+        "~/.gemini/skills",
+        "~/.gemini/antigravity-cli/skills"
+      ],
       "project": ".agents/skills",
       "file": "SKILL.md",
       "restart": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-land",
-  "version": "1.1.0",
+  "version": "1.3.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",

package/skill-land.mjs

@@ -16,7 +16,7 @@ import {
   readFileSync, realpathSync, rmSync, statSync,
 } from "fs";
 import { homedir, tmpdir } from "os";
-import { basename, dirname, join, resolve } from "path";
+import { basename, dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -24,6 +24,8 @@ const { agents: AGENTS } = JSON.parse(readFileSync(join(HERE, "agents.json"), "u
 
 const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
 const expand = (p) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+const fmtBytes = (n) => n < 1024 ? `${n} B`
+  : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} kB` : `${(n / 1024 / 1024).toFixed(1)} MB`;
 const die = (msg) => { console.error(`\n  error  ${msg}\n`); process.exit(1); };
 
 // ---------------------------------------------------------------- source
@@ -120,7 +122,7 @@ function selectSkill(root, wanted) {
     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` +
+      `         Pick one with --skill <name>, or --all for every one of them:\n` +
       shown.join("\n") +
       (named.length > 15 ? `\n           ... and ${named.length - 15} more` : "")
     );
@@ -128,6 +130,44 @@ function selectSkill(root, wanted) {
   return named[0].path;
 }
 
+// --all is the third arm of the same decision: refuse, pick one, or take them
+// all. Deliberately never the default — silently installing 78 skills because
+// a source happened to contain them is the failure selectSkill() exists to
+// prevent, and --all is the user saying they meant it.
+function selectAll(root) {
+  const hits = findSkills(root);
+  if (!hits.length)
+    die(`no SKILL.md found under ${root}\n         searched ${MAX_DEPTH} levels deep`);
+  return hits;
+}
+
+// A skill is a directory, not a file. impeccable ships 148 files; copying only
+// SKILL.md yields a skill whose every `node .../scripts/context.mjs` reference
+// dangles — and 1.2.0 called that "verified", which is precisely the failure
+// this tool exists to catch. Walk the whole skill directory instead.
+//
+// Returns paths relative to the skill root, SKILL.md first so it is written and
+// reported before anything that references it.
+function collectSkillFiles(skillDir, skillFile) {
+  const out = [];
+  (function walk(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!NEVER_SKILLS.has(e.name)) walk(abs, depth + 1);
+        continue;
+      }
+      if (!e.isFile() && !e.isSymbolicLink()) continue;
+      out.push(relative(skillDir, abs));
+    }
+  })(skillDir, 0);
+  return out.sort((a, b) =>
+    (a === skillFile ? -1 : b === skillFile ? 1 : 0) || a.localeCompare(b));
+}
+
 function parseFrontmatter(text) {
   const m = text.match(/^---\n([\s\S]*?)\n---\n/);
   if (!m) return {};
@@ -261,6 +301,7 @@ function securityScan(skillPath) {
 // ---------------------------------------------------------------- verify
 
 // An install is not done until read-back confirms it. This is the whole point.
+// Called once per file in the skill; `expected.name` is set only for SKILL.md.
 function verify(target, expected) {
   const checks = [];
   const ok = (name, pass, detail) => { checks.push({ name, pass, detail }); return pass; };
@@ -287,74 +328,35 @@ function verify(target, expected) {
   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);
-}
+// ---------------------------------------------------------------- per skill
 
-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]);
+// One skill, every target path: scan, disclose, write, read back. Factored out
+// of main so --all is a loop over it rather than a second code path — the
+// single-skill output is unchanged, byte for byte.
+//
+// Returns what the caller needs to summarise: how many targets failed
+// verification, and whether --strict refused this one.
+function runSkill(skillPath, root, quiet) {
+  let skillFailed = 0;
+  let skillSkipped = false;
   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 };
+
+  // The skill is the directory SKILL.md sits in. `name` is set only on SKILL.md
+  // so the frontmatter check does not run against scripts and reference docs.
+  const skillDir = dirname(skillPath);
+  const skillFile = basename(skillPath);
+  const files = collectSkillFiles(skillDir, skillFile).map((rel) => {
+    const raw = readFileSync(join(skillDir, rel));
+    return { rel, bytes: raw.length, hash: sha256(raw),
+             name: rel === skillFile ? fm.name : undefined };
+  });
+  const totalBytes = files.reduce((n, f) => n + f.bytes, 0);
 
   // Scan before any write. A blocked skill must never reach disk.
-  const scan = skipSecurity ? { status: "skipped" } : securityScan(skillPath);
+  const scan = (skipSecurity || verifyOnly) ? { status: "skipped" } : securityScan(skillPath);
   const contents = disclose(rawBody.toString("utf-8"));
   const findings = (scan.top || []).length
     ? "\n" + scan.top.map((t) => `           ${t}`).join("\n") : "";
@@ -372,10 +374,14 @@ try {
     skipped:     () => `  security NOT SCANNED  --skip-security given`,
   };
 
+  if (quiet) {
+    process.stdout.write(`  ${(fm.name || basename(dirname(skillPath))).slice(0, 28).padEnd(30)}`);
+  } else {
   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(`  skill    ${fm.name || "(no frontmatter name)"}  [${files.length} file${files.length === 1 ? "" : "s"}, ${fmtBytes(totalBytes)}, SKILL.md sha ${files[0].hash.slice(0,12)}]`);
   console.log(`  from     ${skillPath.replace(root, ".")}`);
-  if (!verifyOnly) {
+  }
+  if (!verifyOnly && !quiet) {
     // Always shown, with or without a scanner. Counts and quotes only.
     if (contents.length) {
       console.log("  contains");
@@ -388,56 +394,215 @@ try {
     }
     console.log(SCAN_LINE[scan.status]());
   }
-  console.log("");
+  if (!quiet) 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.`);
+    if (!quiet)
+      console.error(`\n  error  --strict: SkillSpector reports ${scan.detail}\n         Review the findings above. Drop --strict to install anyway.\n`);
+    else console.log(`SKIP  --strict: ${scan.detail}`);
+    // One flagged skill must not block the clean ones, but the run still fails.
+    return { name: skillName, failed: 0, skipped: true };
   }
 
+  const bad = [];
+  let targetCount = 0;
+
   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}`);
+    if (!quiet) console.log(`  ${a.display}`);
+
+    const baseResults = [];
 
     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]}`;
+
+      targetCount++;
+      if (dryRun) {
+        if (quiet) continue;
+        console.log(`    would write  ${destDir}  (${files.length} file${files.length === 1 ? "" : "s"}, ${fmtBytes(totalBytes)})`);
+        continue;
+      }
+
+      // Every file in the skill, each read back. A skill whose SKILL.md landed
+      // but whose scripts/ did not is broken, and must not report verified.
+      const badFiles = [];
+      for (const f of files) {
+        const target = join(destDir, f.rel);
+
+        // 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(dirname(target), { recursive: true });
+            cpSync(join(skillDir, f.rel), target);
+          } catch (e) {
+            writeErr = `${e.code || "error"}: ${e.message.split("\n")[0]}`;
+          }
         }
+
+        const checks = writeErr
+          ? [{ name: "write", pass: false, detail: writeErr }]
+          : verify(target, f);
+        if (!checks.every((c) => c.pass)) badFiles.push({ target, rel: f.rel, checks });
       }
 
-      const checks = writeErr
-        ? [{ name: "write", pass: false, detail: writeErr }]
-        : verify(target, expected);
-      const passed = checks.every((c) => c.pass);
-      if (!passed) failed++;
+      baseResults.push({ destDir, badFiles, passed: badFiles.length === 0 });
+    }
+
+    if (!dryRun) {
+      // An install lives in ONE directory the agent reads. Requiring every
+      // fallback to hold a copy manufactures failures: skill-land writes three
+      // paths for Antigravity, but a skill complete in any one of them IS
+      // installed. Installing still demands all three, since it just wrote them.
+      const agentPassed = verifyOnly
+        ? baseResults.some((r) => r.passed)
+        : baseResults.every((r) => r.passed);
+      if (!agentPassed) {
+        skillFailed++;
+        for (const r of baseResults) for (const b of r.badFiles) bad.push(b);
+      }
 
-      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 (!quiet) {
+        for (const r of baseResults) {
+          const n = files.length - r.badFiles.length;
+          // Nothing present at all is one fact, not N failures. Listing every
+          // absent file buries the directories that are partially installed,
+          // which are the ones worth looking at.
+          const absent = r.badFiles.length === files.length
+            && r.badFiles.every((b) => b.checks.some((c) => c.name === "file exists" && !c.pass));
+          if (absent) {
+            console.log(`    FAIL  ${r.destDir}  not installed${verifyOnly ? "  (verify only)" : ""}`);
+            continue;
+          }
+          console.log(`    ${r.passed ? "OK  " : "FAIL"}  ${r.destDir}  ${n}/${files.length} file${files.length === 1 ? "" : "s"}${verifyOnly ? "  (verify only)" : ""}`);
+          for (const b of r.badFiles.slice(0, 10)) {
+            console.log(`            x ${b.rel}`);
+            for (const c of b.checks) if (!c.pass) console.log(`              ${c.name}: ${c.detail}`);
+          }
+          if (r.badFiles.length > 10) console.log(`            ... and ${r.badFiles.length - 10} more file(s)`);
+        }
+        if (verifyOnly && agentPassed && baseResults.some((r) => !r.passed))
+          console.log(`    note  complete in at least one directory ${a.display} reads; that is an install`);
       }
     }
 
+    if (quiet) continue;
     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();
   }
+
+  // One line per skill: the counts, then every failing path underneath it. A
+  // summary that hid which path failed would need a second run to be actionable.
+  if (quiet) {
+    const nf = `${files.length} file${files.length === 1 ? "" : "s"}`;
+    if (dryRun) console.log(`--    ${targetCount} target${targetCount === 1 ? "" : "s"}, ${nf} (dry run)`);
+    else console.log(`${skillFailed ? "FAIL" : "OK  "}  ${nf}`);
+    for (const b of bad.slice(0, 10)) {
+      console.log(`        x ${b.target}`);
+      for (const c of b.checks) if (!c.pass) console.log(`          ${c.name}: ${c.detail}`);
+    }
+    if (bad.length > 10) console.log(`        ... and ${bad.length - 10} more file(s)`);
+  }
+  return { name: skillName, failed: skillFailed, skipped: skillSkipped };
+}
+
+// ---------------------------------------------------------------- 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
+    --all           every skill in the source, not just one
+    --verbose       per-skill detail when --all (default: one line each)
+    --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
+
+  Copies every file in the skill, then reads each back. Exits non-zero if any
+  file did not land where the agent actually reads.
+`);
+  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 allSkills = flag("--all");
+const verbose = flag("--verbose");
+
+// --skill names one, --all takes every one. Asking for both is a contradiction
+// about intent, not something to resolve by precedence.
+if (allSkills && values("--skill").length)
+  die("--all and --skill are mutually exclusive: --skill names one, --all takes every one");
+
+const src = resolveSource(source);
+const tmp = mkdtempSync(join(tmpdir(), "skill-install-"));
+let failed = 0;
+const skipped = [];
+
+try {
+  const root = fetchSource(src, tmp);
+  const skillPaths = allSkills ? selectAll(root) : [selectSkill(root, values("--skill")[0])];
+
+  // With --all the per-skill detail becomes a wall nobody reads, and an unread
+  // report verifies nothing. Collapse to one line each unless asked otherwise.
+  const quiet = allSkills && !verbose;
+  if (quiet) console.log(`\n  source   ${src.label}\n  skills   ${skillPaths.length} found`);
+
+  for (const skillPath of skillPaths) {
+    const r = runSkill(skillPath, root, quiet);
+    failed += r.failed;
+    if (r.skipped) skipped.push(r.name);
+  }
+
+  if (allSkills) {
+    const n = skillPaths.length;
+    console.log(`  ${n} skill${n === 1 ? "" : "s"}, ${failed} failed${skipped.length ? `, ${skipped.length} skipped by --strict` : ""}`);
+    if (skipped.length) console.log(`  skipped  ${skipped.join(", ")}`);
+    console.log();
+  }
 } finally {
   rmSync(tmp, { recursive: true, force: true });
 }