skill-land 1.1.0 → 1.2.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,8 +71,47 @@ 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:
@@ -88,19 +129,63 @@ unwritable destination, and a real `npx skills add` install (correctly reported
 
 ## 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.2.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

@@ -120,7 +120,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 +128,17 @@ 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;
+}
+
 function parseFrontmatter(text) {
   const m = text.match(/^---\n([\s\S]*?)\n---\n/);
   if (!m) return {};
@@ -287,66 +298,17 @@ 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);
-}
-
-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(", ")}`);
+// ---------------------------------------------------------------- per skill
 
-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, "-");
@@ -354,7 +316,7 @@ try {
   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 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 +334,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(`  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,27 +354,39 @@ 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}`);
 
     for (const base of bases) {
       const destDir = join(base, skillName);
       const target = join(destDir, a.file);
 
-      if (dryRun) { console.log(`    would write  ${target}`); continue; }
+      targetCount++;
+      if (dryRun) {
+        if (quiet) continue;
+        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.
@@ -426,18 +404,123 @@ try {
         ? [{ name: "write", pass: false, detail: writeErr }]
         : verify(target, expected);
       const passed = checks.every((c) => c.pass);
-      if (!passed) failed++;
+      if (!passed) { skillFailed++; bad.push({ target, checks }); }
 
+      if (quiet) continue;
       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) 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 okCount = targetCount - skillFailed;
+    if (dryRun) console.log(`--    ${targetCount} target${targetCount === 1 ? "" : "s"} (dry run)`);
+    else console.log(`${skillFailed ? "FAIL" : "OK  "}  ${okCount}/${targetCount}`);
+    for (const b of bad) {
+      console.log(`        x ${b.target}`);
+      for (const c of b.checks) if (!c.pass) console.log(`          ${c.name}: ${c.detail}`);
+    }
+  }
+  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
+
+  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 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 });
 }