skillrepo 4.18.0 → 4.18.1

package/README.md

@@ -662,9 +662,11 @@ Skills land at one of two project paths, depending on the agent:
 | Cursor / Windsurf / Gemini CLI / Codex CLI / Cline / GitHub Copilot | `.agents/skills/<name>/` | `~/.agents/skills/<name>/` |
 | Windsurf (personal-scope override) | — | `~/.codeium/windsurf/skills/<name>/` |
 
-The CLI keeps `.claude/skills/` and `.agents/skills/` listed in the
-SkillRepo section of your project `.gitignore`, re-checked on every
-sync — skills are a per-developer cache, not committed content. The `--agent` flag overrides detection (e.g.
+The CLI keeps `.claude/skills/` and `.agents/skills/` gitignored,
+re-checked on every sync: an entry is added to the SkillRepo section of
+your project `.gitignore` only when no existing rule already ignores
+that path (a repo that ignores `.claude/` gets no `.claude/skills/`
+line) — skills are a per-developer cache, not committed content. The `--agent` flag overrides detection (e.g.
 `--agent claude,agents` writes both paths). See
 [`docs/vendor-paths.md`](docs/vendor-paths.md) for primary-source
 citations on each agent's read paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.18.0",
+  "version": "4.18.1",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library, synced across your dev environment",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -443,7 +443,8 @@ export async function runInit(argv, io = {}, deps = {}) {
         `.gitignore updated (added: ${gitignoreResult.added.join(", ")})`,
       );
     }
-    // "skipped" → all entries already present, no output needed
+    // "skipped" → every entry already present (or, for the skill roots,
+    // already ignored by an existing rule — #2903), no output needed
   } catch (err) {
     p.warning(
       `Could not update .gitignore: ${err?.message ?? String(err)}. ` +
@@ -1077,7 +1078,7 @@ async function runDetectionPicker({ yes, json, stdout, detections }) {
         "    .agents/skills/   (for Cursor, Windsurf, Gemini CLI, Codex CLI, " +
         "Cline, Copilot, and others)\n" +
         "\n" +
-        "  Both paths are added to .gitignore — skills are a per-developer " +
+        "  Both paths are gitignored — skills are a per-developer " +
         "cache, not committed.\n\n",
     );
   }

package/src/lib/file-write.mjs

@@ -466,11 +466,13 @@ export function writeSkillDir(skill, options = {}) {
   const targets = placementTargetsFor(options);
 
   // Pre-flight: if any target writes to a project-scope managed root
-  // (.claude/skills/, .agents/skills/), ensure the root's blanket
-  // ignore is present in the CLI's marked .gitignore section before
-  // starting any writes (#2361 — heal on every sync, both roots; the
+  // (.claude/skills/, .agents/skills/), ensure the root is gitignored
+  // before starting any writes — the blanket entry lands in the CLI's
+  // marked .gitignore section only when no existing rule already covers
+  // the root (#2903: a repo ignoring `.claude/` gets no redundant
+  // `.claude/skills/` line). #2361 — heal on every sync, both roots; the
   // pre-4.10.0 code covered only .agents/skills/ under a separate
-  // header). A failure here is recoverable (user fixes their
+  // header. A failure here is recoverable (user fixes their
   // .gitignore and re-runs) because nothing has hit disk yet. A
   // failure here AFTER a successful write to an earlier target would
   // leave the user with a half-applied state and an error message

package/src/lib/gitignore-section.mjs

@@ -14,13 +14,21 @@
  * surfaced by the sync-time foreign-content scan (`foreign-content.mjs`)
  * — never something the ignore machinery accommodates.
  *
- * Idempotent: entries already present anywhere in the file are skipped;
- * missing entries are inserted INTO the existing marked section when one
- * exists (never a duplicate header), else appended as a new section.
- * Every call also heals the retired pre-4.10.0 sync-time section shape
- * (see `healLegacySection`).
+ * Idempotent: entries already present anywhere in the file are skipped.
+ * The managed-root entries are also skipped when an existing ignore rule
+ * already covers them — asked of git itself via `git check-ignore`
+ * (#2903), so a repo that ignores `.claude/` never gets a redundant
+ * `.claude/skills/` line; the init-only entries stay on the literal
+ * scan (see `isCoverageProbed` for why). Genuinely missing entries are
+ * inserted INTO the existing marked section when one exists (never a
+ * duplicate header), else appended as a new section. Nothing is written
+ * when nothing is missing. Every call also heals the retired pre-4.10.0
+ * sync-time section shape (see `healLegacySection`).
  */
 
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
+
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import { gitignorePath } from "./paths.mjs";
 import { diskError } from "./errors.mjs";
@@ -79,12 +87,18 @@ export function ensureManagedRootIgnores(targets, options = {}) {
 }
 
 /**
- * Core ensure: required entries end up line-exact in the file, inside
- * the CLI's marked section, with the legacy sync-time section healed
- * away. Single writer for every gitignore mutation the CLI performs.
+ * Core ensure: every required entry ends up ignored — either it is
+ * already present line-exact somewhere in the file, an existing ignore
+ * rule already covers it (managed roots only — `git check-ignore`, see
+ * `isCoverageProbed` / `isCoveredByGit`), or it is written into the
+ * CLI's marked section — with the legacy sync-time section healed away.
+ * Single writer for every gitignore mutation the CLI performs; at most
+ * ONE write per call.
  *
- * Returns `"skipped"` if every required entry is already present and no
- * legacy section needed healing, `"created"` if the file didn't exist,
+ * Returns `"skipped"` if nothing needed writing (every required entry
+ * present or covered, no legacy section to heal) — the file is not
+ * touched at all in that case, not even for a comment — `"created"` if
+ * the file didn't exist and at least one entry needed writing,
  * `"updated"` otherwise.
  *
  * @param {string[]} requiredEntries
@@ -107,28 +121,52 @@ export function ensureGitignoreEntries(requiredEntries, options = {}) {
     });
   }
 
+  const dir = dirname(filePath);
+
   if (existing === null) {
-    // Fresh .gitignore — write all required entries as one section.
-    const content =
-      GITIGNORE_SECTION_HEADER + "\n" + requiredEntries.join("\n") + "\n";
+    // Fresh .gitignore — one section holding every entry that still
+    // needs a line: the init-only entries always, a managed root only
+    // when no other ignore source (a nested .gitignore, info/exclude,
+    // a global excludes file) already covers it. Nothing to add →
+    // nothing to create.
+    const toAdd = dropCoveredEntries(requiredEntries, dir);
+    if (toAdd.length === 0) {
+      return { path: ".gitignore", action: "skipped", added: [] };
+    }
+    const content = GITIGNORE_SECTION_HEADER + "\n" + toAdd.join("\n") + "\n";
     writeSectionFile(filePath, content);
-    return {
-      path: ".gitignore",
-      action: "created",
-      added: [...requiredEntries],
-    };
+    return { path: ".gitignore", action: "created", added: toAdd };
   }
 
   // Preserve the original line-ending style throughout.
   const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
 
-  const { lines, healed } = healLegacySection(existing.split(/\r?\n/));
+  const { lines, healed, removed } = healLegacySection(
+    existing.split(/\r?\n/),
+  );
 
   // Line-exact match check. `.env.local` as a line is distinct from
   // `.env.local.backup` or a comment `# .env.local` — compare trimmed
-  // lines so we match the entry literally.
+  // lines so we match the entry literally. A managed-root entry not
+  // present line-exact may still be covered by a broader rule
+  // (`.claude/` covers `.claude/skills/`); git is the authority on that
+  // — except for the line the heal just removed, which git still sees
+  // on disk (`removed`, see `dropCoveredEntries`).
+  //
+  // Whatever the heal removed is re-homed even when this call did not
+  // ask for that root (a Claude-only sync in a repo still carrying the
+  // legacy `.agents/skills/` line): the heal migrates protection, never
+  // drops it. Before #2903 that line was silently lost in this case.
+  const wanted =
+    removed.length > 0
+      ? [...new Set([...requiredEntries, ...removed])]
+      : requiredEntries;
   const trimmed = lines.map((l) => l.trim());
-  const missing = requiredEntries.filter((entry) => !trimmed.includes(entry));
+  const missing = dropCoveredEntries(
+    wanted.filter((entry) => !trimmed.includes(entry)),
+    dir,
+    removed,
+  );
 
   if (missing.length === 0 && !healed) {
     return {
@@ -195,6 +233,125 @@ function writeSectionFile(filePath, content) {
       hint: GITIGNORE_HINT,
     });
   }
+  forgetCoverage(dirname(filePath));
+}
+
+/**
+ * Per-process memo of `isCoveredByGit` answers, keyed by
+ * `<dir>\0<entry>`. The sync pre-flight runs once per written skill, so
+ * without it a sync writing N skills would spawn git N times for every
+ * entry that is covered-but-not-literal (~10 ms each). Every write this
+ * module makes to a directory's .gitignore forgets that directory's
+ * answers (`forgetCoverage`), so a memoized answer never outlives the
+ * file state it was computed from. Anything else editing the file
+ * mid-process is outside this module's contract — this is the only
+ * writer of that section.
+ */
+const coverageMemo = new Map();
+
+/**
+ * Forget every memoized answer for `dir`. Called after each write.
+ *
+ * @param {string} dir
+ */
+function forgetCoverage(dir) {
+  const prefix = `${dir}\0`;
+  for (const key of coverageMemo.keys()) {
+    if (key.startsWith(prefix)) coverageMemo.delete(key);
+  }
+}
+
+/**
+ * Only the managed skill roots consult git for coverage. They are
+ * per-checkout cache directories the CLI alone populates, so any ignore
+ * source git honours in THIS checkout (the repo's .gitignore files,
+ * `.git/info/exclude`, the global excludes file) makes an entry
+ * redundant here, and every other developer's own sync heals their own
+ * checkout. The init-only entries are a different contract: `.env.local`
+ * holds a live access key and `.claude/settings.local.json` per-developer
+ * settings, and their line in the TRACKED .gitignore is what protects
+ * every clone — it must not be withheld because the one developer running
+ * `init` happens to have a personal global excludes rule that covers it.
+ * They stay on the literal scan, exactly as before #2903.
+ *
+ * Considered and rejected for them: probing every entry but counting
+ * only in-tree `.gitignore` sources (parse `git check-ignore -v -z` for
+ * the matching rule's source). It would also quiet the one-time,
+ * init-only redundancy when a TRACKED `.env*` rule already covers
+ * `.env.local`, at the cost of output parsing and a second probe shape
+ * for a cosmetic gain. Revisit if that redundancy ever matters.
+ *
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isCoverageProbed(entry) {
+  return Object.values(MANAGED_ROOT_ENTRIES).includes(entry);
+}
+
+/**
+ * Ask git whether `entry` is already ignored in the work tree that owns
+ * the `.gitignore` at `dir` — the authoritative answer to "would adding
+ * this line be redundant?", honouring every ignore source git does
+ * (that `.gitignore`, nested ones, `.git/info/exclude`, the global
+ * excludes file). Per-checkout sources count deliberately for the
+ * entries this is asked about — see `isCoverageProbed`.
+ *
+ * `--no-index`: pattern coverage regardless of whether a tracked cache
+ * happens to sit under the root (#2361's tracked-cache case) — a rule
+ * that is already there is still redundant to add. The trailing slash
+ * on directory entries is load-bearing: `git check-ignore .agents/skills`
+ * (no slash) does NOT match an `.agents/skills/` rule while the
+ * directory does not exist yet, and on a first sync it does not. The
+ * probe runs WITH `dir` as its cwd because git resolves the path against
+ * its cwd — asked from a subdirectory, an unanchored `.claude/` rule
+ * would match `sub/.claude/skills/` and an anchored `/.claude/` would
+ * not, both wrong answers about the root.
+ *
+ * @param {string} dir - Directory holding the managed `.gitignore`.
+ * @param {string} entry - A `GITIGNORE_REQUIRED_ENTRIES` line.
+ * @returns {boolean | null} `true` covered, `false` not covered, `null`
+ *          no signal — git absent (`spawnSync` reports ENOENT via
+ *          `error`, it does not throw), not a work tree (exit 128), or
+ *          the probe timed out. Callers fall back to the literal scan.
+ */
+function isCoveredByGit(dir, entry) {
+  const key = `${dir}\0${entry}`;
+  if (coverageMemo.has(key)) return coverageMemo.get(key);
+  const probe = spawnSync(
+    "git",
+    ["check-ignore", "-q", "--no-index", "--", entry],
+    { cwd: dir, stdio: "ignore", windowsHide: true, timeout: 5000 },
+  );
+  let covered = null;
+  if (!probe.error && probe.status === 0) covered = true;
+  else if (!probe.error && probe.status === 1) covered = false;
+  coverageMemo.set(key, covered);
+  return covered;
+}
+
+/**
+ * Drop the managed-root entries git reports as already ignored. Entries
+ * that are not probed (`isCoverageProbed`) and entries in `exempt` stay.
+ * `exempt` names the line a pending legacy heal removed from the
+ * in-memory lines but not yet from disk: git would report that entry
+ * covered by the very line about to disappear, so it is re-homed
+ * unconditionally — the heal's whole purpose. With no signal from git
+ * (`null`) the literal scan the caller already ran is the only evidence,
+ * so the entry stays — outside a git work tree nothing can be committed
+ * anyway, and the pre-#2903 behaviour is preserved exactly.
+ *
+ * @param {string[]} entries - Entries not present line-exact in the file.
+ * @param {string} dir
+ * @param {string[]} [exempt]
+ * @returns {string[]}
+ */
+function dropCoveredEntries(entries, dir, exempt = []) {
+  return entries.filter(
+    (entry) =>
+      !isCoverageProbed(entry) ||
+      exempt.includes(entry) ||
+      isCoveredByGit(dir, entry) !== true,
+  );
 }
 
 /**
@@ -210,20 +367,29 @@ function writeSectionFile(filePath, content) {
  * legacy header — survives verbatim.
  *
  * @param {string[]} lines
- * @returns {{ lines: string[]; healed: boolean }}
+ * @returns {{ lines: string[]; healed: boolean; removed: string[] }}
+ *          `removed` names the entry line dropped (at most the
+ *          `.agents/skills/` root) so the caller re-homes it without
+ *          asking git, which still sees it on disk.
  */
 function healLegacySection(lines) {
   const headerIdx = lines.findIndex(
     (l) => l.trim() === LEGACY_GITIGNORE_SECTION_HEADER,
   );
-  if (headerIdx === -1) return { lines, healed: false };
+  if (headerIdx === -1) return { lines, healed: false, removed: [] };
 
   let end = headerIdx + 1;
-  if (end < lines.length && lines[end].trim() === ".agents/skills/") {
+  const removed = [];
+  if (
+    end < lines.length &&
+    lines[end].trim() === MANAGED_ROOT_ENTRIES.agentsProject
+  ) {
+    removed.push(MANAGED_ROOT_ENTRIES.agentsProject);
     end += 1;
   }
   return {
     lines: [...lines.slice(0, headerIdx), ...lines.slice(end)],
     healed: true,
+    removed,
   };
 }

package/src/lib/mergers/gitignore.mjs

@@ -14,8 +14,13 @@
  * entries through the same core, so every CLI-authored gitignore line
  * lives in the one marked section the uninstall remover strips (#2361).
  *
- * Idempotent: entries already present are skipped; a legacy sync-time
- * section is healed into the marked section as a side effect.
+ * Idempotent: entries already present are skipped, and so are the two
+ * skill-root entries when an ignore rule git honours already covers them
+ * (`git check-ignore`, #2903). The always-added entries never take that
+ * shortcut — `.env.local` holds a live key, and its line in the TRACKED
+ * .gitignore is what protects every clone (see `isCoverageProbed` in
+ * `../gitignore-section.mjs`). A legacy sync-time section is healed into
+ * the marked section as a side effect.
  */
 
 import { placementTargetsFor } from "../file-write.mjs";
@@ -64,11 +69,13 @@ function entriesFor(options) {
 }
 
 /**
- * Ensure the init-required paths are in .gitignore. Creates the file
- * if it doesn't exist. Idempotent — returns `"skipped"` if every
- * required entry is already present and no legacy section needed
- * healing, `"created"` if the file didn't exist, `"updated"` if it did
- * and at least one entry was missing (or a legacy section was healed).
+ * Ensure the init-required paths are gitignored. Creates the file if it
+ * doesn't exist and something needs writing. Idempotent — returns
+ * `"skipped"` if every required entry is already present (or, for the
+ * skill roots only, covered by an existing ignore rule) and no legacy
+ * section needed healing, `"created"` if the file didn't exist,
+ * `"updated"` if it did and at least one entry was missing (or a legacy
+ * section was healed).
  *
  * @param {{ vendors?: string[], global?: boolean }} [options]
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}

package/src/test/lib/file-write.test.mjs

@@ -30,9 +30,12 @@ import {
   readFileSync,
   readdirSync,
   chmodSync,
+  statSync,
+  utimesSync,
 } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
 
 import {
   validateFilePath,
@@ -1444,3 +1447,44 @@ describe("cleanupOrphans", () => {
     assert.match(result.cleaned[0], /ghost\.old$/);
   });
 });
+
+// ── .gitignore pre-flight honours existing ignore rules (#2903) ─────────
+//
+// The sync path (SessionStart hook → update → writeSkillDir) is where the
+// redundant `.claude/skills/` line was observed: a repo already ignoring
+// `.claude/` had the entry appended on every fresh checkout. Real git
+// repository so `git check-ignore` is exercised, not mocked.
+
+describe("writeSkillDir — .gitignore pre-flight honours existing ignore rules (#2903)", () => {
+  beforeEach(() => {
+    setupSandbox();
+    execFileSync("git", ["init", "-q"], { cwd: process.cwd(), stdio: "ignore" });
+  });
+  afterEach(teardownSandbox);
+
+  it("a repo that already ignores both roots keeps its .gitignore byte-identical across a sync write", () => {
+    const gi = join(process.cwd(), ".gitignore");
+    const original = "# team rules\n.claude/\n.agents/\n";
+    writeFileSync(gi, original);
+    const frozen = new Date("2001-02-03T04:05:06Z");
+    utimesSync(gi, frozen, frozen);
+
+    const { written } = writeSkillDir(minimalSkill(), { vendors: ["claudeCode", "cursor"] });
+
+    assert.equal(written.length, 2, "both project roots written");
+    assert.equal(readFileSync(gi, "utf-8"), original);
+    assert.equal(statSync(gi).mtimeMs, frozen.getTime(), ".gitignore must not be rewritten");
+  });
+
+  it("a repo that ignores only .claude/ gets .agents/skills/ and nothing else", () => {
+    const gi = join(process.cwd(), ".gitignore");
+    writeFileSync(gi, ".claude/\n");
+
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode", "cursor"] });
+
+    assert.equal(
+      readFileSync(gi, "utf-8"),
+      ".claude/\n\n# SkillRepo CLI (added by `skillrepo init`)\n.agents/skills/\n",
+    );
+  });
+});

package/src/test/lib/gitignore-section.test.mjs

@@ -10,9 +10,19 @@
 
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+  existsSync,
+  statSync,
+  utimesSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
+import { execFileSync, spawnSync } from "node:child_process";
 
 import {
   ensureGitignoreEntries,
@@ -23,6 +33,7 @@ import {
   GITIGNORE_SECTION_HEADER,
   LEGACY_GITIGNORE_SECTION_HEADER,
 } from "../../lib/artifact-registry.mjs";
+import { isolatePathEnv } from "../helpers/path-isolation.mjs";
 
 let originalCwd;
 let tempDir;
@@ -150,6 +161,22 @@ describe("ensureGitignoreEntries — legacy sync-time section heal", () => {
     assert.equal(matches.length, 1);
   });
 
+  it("re-homes the legacy .agents/skills/ line even when the caller did not ask for that root (Claude-only sync)", () => {
+    // Before #2903 a claudeProject-only call healed the legacy section
+    // and silently dropped the `.agents/skills/` protection it removed.
+    writeFileSync(
+      join(tempDir, ".gitignore"),
+      `node_modules/\n\n${LEGACY_GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`,
+    );
+    const result = ensureGitignoreEntries([".claude/skills/"]);
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".claude/skills/", ".agents/skills/"]);
+    assert.equal(
+      gitignore(),
+      `node_modules/\n\n${GITIGNORE_SECTION_HEADER}\n.claude/skills/\n.agents/skills/\n`,
+    );
+  });
+
   it("never removes user content sitting under the legacy header", () => {
     writeFileSync(
       join(tempDir, ".gitignore"),
@@ -211,3 +238,243 @@ describe("ensureManagedRootIgnores — target mapping", () => {
     ]);
   });
 });
+
+// ── Existing ignore rules (#2903) ───────────────────────────────────────
+//
+// The literal scan above cannot see that `.claude/` already ignores
+// `.claude/skills/`; git can. These run against REAL repositories so the
+// probe's semantics (trailing slash, --no-index, cwd anchoring, every
+// ignore source git honours) are exercised end-to-end, not mocked.
+
+function git(args, cwd) {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+/** A fixed, obviously-old mtime: proves "no write happened" without racing the clock. */
+const FROZEN_MTIME = new Date("2001-02-03T04:05:06Z");
+
+function freezeMtime(file) {
+  utimesSync(file, FROZEN_MTIME, FROZEN_MTIME);
+}
+
+/** What git itself says about a path in `cwd` — the property the writer must guarantee. */
+function gitIgnores(entry, cwd) {
+  return (
+    spawnSync("git", ["check-ignore", "-q", "--no-index", "--", entry], {
+      cwd,
+      stdio: "ignore",
+    }).status === 0
+  );
+}
+
+describe("ensureGitignoreEntries — existing ignore rules are honoured (#2903)", () => {
+  beforeEach(() => {
+    git(["init", "-q"], tempDir);
+  });
+
+  it("appends only the entry no existing rule covers (.claude/ already covers .claude/skills/)", () => {
+    writeFileSync(join(tempDir, ".gitignore"), "node_modules/\n.claude/\n");
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".agents/skills/"]);
+    assert.equal(
+      gitignore(),
+      `node_modules/\n.claude/\n\n${GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`,
+    );
+    // Both roots end up ignored — one by the user's rule, one by ours.
+    assert.ok(gitIgnores(".claude/skills/", tempDir));
+    assert.ok(gitIgnores(".agents/skills/", tempDir));
+  });
+
+  it("does not touch the file at all when every entry is already covered — no comment-only write", () => {
+    const file = join(tempDir, ".gitignore");
+    const original = "# team rules\n.claude/\n.agents/\n";
+    writeFileSync(file, original);
+    freezeMtime(file);
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.deepEqual(result, { path: ".gitignore", action: "skipped", added: [] });
+    assert.equal(readFileSync(file, "utf-8"), original, "byte-identical");
+    assert.equal(
+      statSync(file).mtimeMs,
+      FROZEN_MTIME.getTime(),
+      "the file must not be rewritten, not even with identical bytes",
+    );
+  });
+
+  it("memoizes probe answers per process — a second call needs no git at all", () => {
+    writeFileSync(join(tempDir, ".gitignore"), ".claude/\n.agents/\n");
+    const first = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(first.action, "skipped");
+    // With git unreachable a fresh probe would return "no signal" and
+    // the literal scan would append both roots; the memo answers instead.
+    // (Nothing was written by the first call, so nothing cleared it.)
+    const restorePath = isolatePathEnv();
+    try {
+      const second = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+      assert.deepEqual(second, { path: ".gitignore", action: "skipped", added: [] });
+      assert.equal(gitignore(), ".claude/\n.agents/\n");
+    } finally {
+      restorePath();
+    }
+  });
+
+  it("creates the file with every entry when no rule covers them", () => {
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(result.action, "created");
+    assert.deepEqual(result.added, [".claude/skills/", ".agents/skills/"]);
+    assert.equal(
+      gitignore(),
+      `${GITIGNORE_SECTION_HEADER}\n.claude/skills/\n.agents/skills/\n`,
+    );
+  });
+
+  it("is idempotent — the run after a partial append changes nothing", () => {
+    const file = join(tempDir, ".gitignore");
+    writeFileSync(file, ".claude/\n");
+    const first = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(first.action, "updated");
+    const afterFirst = readFileSync(file, "utf-8");
+    freezeMtime(file);
+    const second = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.deepEqual(second, { path: ".gitignore", action: "skipped", added: [] });
+    assert.equal(readFileSync(file, "utf-8"), afterFirst);
+    assert.equal(statSync(file).mtimeMs, FROZEN_MTIME.getTime());
+  });
+
+  it("a fresh .gitignore honours coverage from a nested .gitignore", () => {
+    mkdirSync(join(tempDir, ".claude"));
+    writeFileSync(join(tempDir, ".claude", ".gitignore"), "skills/\n");
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(result.action, "created");
+    assert.deepEqual(result.added, [".agents/skills/"]);
+    assert.equal(gitignore(), `${GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`);
+  });
+
+  it("creates nothing when every entry is covered by .git/info/exclude", () => {
+    writeFileSync(join(tempDir, ".git", "info", "exclude"), ".claude/\n.agents/\n");
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.deepEqual(result, { path: ".gitignore", action: "skipped", added: [] });
+    assert.ok(!existsSync(join(tempDir, ".gitignore")), "no file may be created");
+  });
+
+  it("the init-only entries stay on the literal scan even when a tracked rule covers them", () => {
+    // `.env.local` holds a live access key: its line in the TRACKED
+    // .gitignore protects every clone, so a covering rule never
+    // withholds it. Only the managed skill roots consult git.
+    writeFileSync(join(tempDir, ".gitignore"), ".env*\n.claude/\n");
+    const result = ensureGitignoreEntries([
+      ".env.local",
+      ".claude/settings.local.json",
+      ".claude/skills/",
+    ]);
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".env.local", ".claude/settings.local.json"]);
+    assert.equal(
+      gitignore(),
+      `.env*\n.claude/\n\n${GITIGNORE_SECTION_HEADER}\n.env.local\n.claude/settings.local.json\n`,
+    );
+  });
+
+  it("a personal ignore source never withholds the credential entry (.env.local covered by .git/info/exclude)", () => {
+    writeFileSync(join(tempDir, ".git", "info", "exclude"), ".env.local\n.claude/\n");
+    writeFileSync(join(tempDir, ".gitignore"), "node_modules/\n");
+    const result = ensureGitignoreEntries([".env.local", ".claude/skills/"]);
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".env.local"], "the skill root is per-checkout, the key is not");
+  });
+
+  it("heals the legacy section AND re-homes .agents/skills/ — the removed legacy line is not mistaken for coverage", () => {
+    writeFileSync(
+      join(tempDir, ".gitignore"),
+      `.claude/\n\n${LEGACY_GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`,
+    );
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".agents/skills/"]);
+    const content = gitignore();
+    assert.ok(!content.includes(LEGACY_GITIGNORE_SECTION_HEADER));
+    assert.equal(content, `.claude/\n\n${GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`);
+    assert.ok(
+      gitIgnores(".agents/skills/", tempDir),
+      "the heal must never drop the root's only protection",
+    );
+  });
+
+  it("heal re-homes .agents/skills/ in ONE write even when another rule covers it (git still sees the legacy line on disk)", () => {
+    const file = join(tempDir, ".gitignore");
+    writeFileSync(
+      file,
+      `.claude/\n.agents/\n\n${LEGACY_GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`,
+    );
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.deepEqual(result, {
+      path: ".gitignore",
+      action: "updated",
+      added: [".agents/skills/"],
+    });
+    // The heal and the re-home land together — never a healed-but-
+    // unprotected intermediate file; `.claude/skills/` stays covered
+    // by `.claude/` and is not added.
+    assert.equal(
+      readFileSync(file, "utf-8"),
+      `.claude/\n.agents/\n\n${GITIGNORE_SECTION_HEADER}\n.agents/skills/\n`,
+    );
+  });
+
+  it("heal with nothing to re-home writes the healed file once and reports updated", () => {
+    // Legacy header WITHOUT its `.agents/skills/` line: nothing was
+    // removed, so both roots go through the probe and are covered.
+    writeFileSync(
+      join(tempDir, ".gitignore"),
+      `.claude/\n.agents/\n\n${LEGACY_GITIGNORE_SECTION_HEADER}\nmy-own-line/\n`,
+    );
+    const result = ensureGitignoreEntries([".claude/skills/", ".agents/skills/"]);
+    assert.deepEqual(result, { path: ".gitignore", action: "updated", added: [] });
+    assert.equal(gitignore(), ".claude/\n.agents/\n\nmy-own-line/\n");
+  });
+
+  it("probes relative to the .gitignore's own directory, not the process cwd (baseDir anchoring)", () => {
+    // An ANCHORED rule at the repo root matches `.claude/skills/` only
+    // when the question is asked from the root. A probe run from `sub/`
+    // would ask about `sub/.claude/skills/`, hear "not ignored", and
+    // append a redundant line.
+    writeFileSync(join(tempDir, ".gitignore"), "/.claude/\n");
+    const sub = join(tempDir, "sub");
+    mkdirSync(sub);
+    process.cwd = () => sub;
+    const result = ensureGitignoreEntries([".claude/skills/"], { baseDir: tempDir });
+    assert.deepEqual(result, { path: ".gitignore", action: "skipped", added: [] });
+    assert.equal(gitignore(), "/.claude/\n");
+  });
+});
+
+describe("ensureGitignoreEntries — literal-scan fallback when git has no answer (#2903)", () => {
+  it("outside a git work tree a broader rule is not recognised (pre-#2903 behaviour, unchanged)", () => {
+    // Fence repository discovery at the temp dir's parent so this test
+    // cannot accidentally find a repository above the temp tree.
+    const prior = process.env.GIT_CEILING_DIRECTORIES;
+    process.env.GIT_CEILING_DIRECTORIES = dirname(tempDir);
+    try {
+      writeFileSync(join(tempDir, ".gitignore"), ".claude/\n");
+      const result = ensureGitignoreEntries([".claude/skills/"]);
+      assert.equal(result.action, "updated");
+      assert.deepEqual(result.added, [".claude/skills/"]);
+    } finally {
+      if (prior === undefined) delete process.env.GIT_CEILING_DIRECTORIES;
+      else process.env.GIT_CEILING_DIRECTORIES = prior;
+    }
+  });
+
+  it("with no git binary on PATH the literal scan decides", () => {
+    git(["init", "-q"], tempDir);
+    writeFileSync(join(tempDir, ".gitignore"), ".claude/\n");
+    const restorePath = isolatePathEnv();
+    try {
+      const result = ensureGitignoreEntries([".claude/skills/"]);
+      assert.equal(result.action, "updated");
+      assert.deepEqual(result.added, [".claude/skills/"]);
+    } finally {
+      restorePath();
+    }
+  });
+});

package/src/test/mergers/gitignore.test.mjs

@@ -21,6 +21,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
 
 import { mergeGitignore } from "../../lib/mergers/gitignore.mjs";
 
@@ -186,3 +187,50 @@ describe("mergeGitignore — line-exact matching", () => {
     assert.equal(result.action, "skipped");
   });
 });
+
+// ── Existing ignore rules (#2903) ───────────────────────────────────────
+
+describe("mergeGitignore — existing ignore rules are honoured for the skill roots (#2903)", () => {
+  it("in a repo that already ignores .claude/, init adds .agents/skills/ but never .claude/skills/", () => {
+    execFileSync("git", ["init", "-q"], { cwd: tempDir, stdio: "ignore" });
+    writeFileSync(join(tempDir, ".gitignore"), "node_modules/\n.claude/\n");
+
+    const result = mergeGitignore({ vendors: ["claudeCode", "cursor"] });
+
+    assert.equal(result.action, "updated");
+    // The init-only entries are literal-scan (a tracked-file contract,
+    // see isCoverageProbed); the skill roots consult git.
+    assert.deepEqual(result.added, [
+      ".env.local",
+      ".claude/settings.local.json",
+      ".agents/skills/",
+    ]);
+    assert.equal(
+      readFileSync(join(tempDir, ".gitignore"), "utf-8"),
+      "node_modules/\n.claude/\n\n# SkillRepo CLI (added by `skillrepo init`)\n" +
+        ".env.local\n.claude/settings.local.json\n.agents/skills/\n",
+    );
+  });
+
+  it("in a repo that already ignores both skill roots and lists the init-only entries, the file is left byte-identical", () => {
+    execFileSync("git", ["init", "-q"], { cwd: tempDir, stdio: "ignore" });
+    const original = ".env.local\n.claude/settings.local.json\n.claude/\n.agents/\n";
+    writeFileSync(join(tempDir, ".gitignore"), original);
+
+    const result = mergeGitignore({ vendors: ["claudeCode", "cursor"] });
+
+    assert.deepEqual(result, { path: ".gitignore", action: "skipped", added: [] });
+    assert.equal(readFileSync(join(tempDir, ".gitignore"), "utf-8"), original);
+  });
+
+  it("a personal global excludes rule never withholds the credential entry", () => {
+    execFileSync("git", ["init", "-q"], { cwd: tempDir, stdio: "ignore" });
+    writeFileSync(join(tempDir, ".git", "info", "exclude"), ".env*\n.claude/\n.agents/\n");
+    writeFileSync(join(tempDir, ".gitignore"), "node_modules/\n");
+
+    const result = mergeGitignore({ vendors: ["claudeCode", "cursor"] });
+
+    assert.equal(result.action, "updated");
+    assert.deepEqual(result.added, [".env.local", ".claude/settings.local.json"]);
+  });
+});