skillrepo 4.1.0 → 4.3.0

package/src/test/dispatcher.test.mjs

@@ -71,7 +71,7 @@ describe("dispatcher — top-level help", () => {
     assert.equal(r.status, 0);
     assert.match(r.stdout, /SkillRepo CLI/);
     // All 7 commands listed
-    for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+    for (const cmd of ["init", "update", "get", "add", "push", "remove", "list", "search"]) {
       assert.match(r.stdout, new RegExp(`\\b${cmd}\\b`), `expected to see "${cmd}" in help`);
     }
   });
@@ -123,7 +123,7 @@ describe("dispatcher — unknown command", () => {
 describe("dispatcher — per-command help", () => {
   // PR1 only ships init for real; the other 6 are stubs but still
   // route --help correctly.
-  for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+  for (const cmd of ["init", "update", "get", "add", "push", "remove", "list", "search"]) {
     it(`\`skillrepo ${cmd} --help\` prints command-specific help`, async () => {
       const r = await runCli([cmd, "--help"]);
       assert.equal(r.status, 0);
@@ -194,6 +194,14 @@ describe("dispatcher — implemented commands route to their modules", () => {
     assert.ok([1, 2, 5].includes(r.status));
   });
 
+  it("`skillrepo push` is wired to the real module (not a stub)", async () => {
+    // Missing path exits validation (5); missing credentials would
+    // exit auth (2). Either proves the stub is gone.
+    const r = await runCli(["push"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([2, 5].includes(r.status));
+  });
+
   it("`skillrepo remove` is wired to the real module (not a stub)", async () => {
     const r = await runCli(["remove", "@alice/pdf-helper"], { env: { HOME: "/tmp/no-skillrepo-config" } });
     assert.doesNotMatch(r.stderr, /Not yet implemented/);

package/src/test/e2e/mock-server.mjs

@@ -6,8 +6,11 @@
  *   GET    /api/v1/skill-content                  — legacy skill content
  *   POST   /api/v1/auth/validate                  — credential check (PR2)
  *   GET    /api/v1/library                        — library sync with ETag + since (PR2)
- *   POST   /api/v1/library                        — add to library (PR3a)
+ *   POST   /api/v1/library                        — multipart file-push (#1452)
+ *   POST   /api/v1/library/refs                   — add catalog skill to library (#1451)
  *   DELETE /api/v1/library/[owner]/[name]         — remove from library (PR3a)
+ *   POST   /api/v1/library/[owner]/[name]/publish — make global (#1449)
+ *   POST   /api/v1/library/[owner]/[name]/unpublish — make private (#1449)
  *   GET    /api/v1/skills/[owner]/[name]          — single skill fetch (PR2)
  *   GET    /api/v1/skills/search                  — keyword search (PR2)
  *
@@ -24,10 +27,15 @@
  *   setEtag(etag)                        — what library responses include
  *
  *   (PR3a additions)
- *   setAddResponse(owner, name, resp)    — per-skill response for POST /library
+ *   setAddResponse(owner, name, resp)    — per-skill response for POST /library/refs (#1451)
  *   setRemoveResponse(owner, name, resp) — per-skill response for DELETE /library/<owner>/<name>
+ *   setPushResponse(resp)                — response for POST /library multipart push (#1452)
  *   getLastPostBody()                    — inspect the most recent POST body (JSON-parsed)
  *
+ *   (Epic #1444 R3 #1449 additions)
+ *   setPublishResponse(owner, name, resp)   — per-skill response for POST /library/<owner>/<name>/publish
+ *   setUnpublishResponse(owner, name, resp) — per-skill response for POST /library/<owner>/<name>/unpublish
+ *
  * The slot APIs let unit/integration tests configure each scenario
  * without spinning up multiple servers per test. Default behavior
  * for an unconfigured slot is a sensible empty payload.
@@ -84,6 +92,18 @@ export function createMockServer(initialPayload, options = {}) {
   // matches any owner/name when no exact match is registered.
   let addResponses = new Map();    // key: "owner/name" or "*" → { status, body }
   let removeResponses = new Map(); // key: "owner/name" or "*" → { status, body }
+  // Epic #1444 R3 #1456 — POST /api/v1/library/[owner]/[name]/publish
+  // and POST /api/v1/library/[owner]/[name]/unpublish (#1449).
+  let publishResponses = new Map();   // key: "owner/name" or "*" → { status, body }
+  let unpublishResponses = new Map(); // key: "owner/name" or "*" → { status, body }
+
+  // #1452 — POST /api/v1/library (multipart file-push) response slot.
+  // Tests set this with `setPushResponse({ status, body })`; when null,
+  // a default 201 LibraryPushResponse is served. The test server does
+  // not parse multipart bodies — verifying the wire format is the
+  // client's responsibility.
+  /** @type {{ status: number, body: any } | null} */
+  let pushResponse = null;
 
   // Most recent POST body (JSON-parsed) for test inspection.
   //
@@ -138,19 +158,25 @@ export function createMockServer(initialPayload, options = {}) {
     // command sends a JSON body to POST /api/v1/library, so we
     // now collect chunks and re-dispatch once the stream ends.
     if (req.method === "POST" || req.method === "DELETE" || req.method === "PUT" || req.method === "PATCH") {
-      let bodyChunks = "";
+      // Buffer as Buffer chunks, not string concatenation. JSON routes
+      // re-interpret as UTF-8; binary multipart bodies (#1452 push) keep
+      // their bytes intact. Concatenating `chunk.toString("utf-8")`
+      // would silently corrupt non-UTF-8 file content.
+      const chunks = [];
       req.on("data", (chunk) => {
-        bodyChunks += chunk.toString("utf-8");
+        chunks.push(chunk);
       });
       req.on("end", () => {
-        if (req.method === "POST" && bodyChunks.length > 0) {
+        const rawBody = Buffer.concat(chunks);
+        const rawBodyText = rawBody.toString("utf-8");
+        if (req.method === "POST" && rawBodyText.length > 0) {
           try {
-            lastPostBody = JSON.parse(bodyChunks);
+            lastPostBody = JSON.parse(rawBodyText);
           } catch {
-            lastPostBody = bodyChunks; // preserve as string for tests
+            lastPostBody = rawBodyText; // preserve as string for tests
           }
         }
-        handleRequest(req, res, bodyChunks);
+        handleRequest(req, res, rawBodyText);
       });
       req.on("error", () => {
         // Connection dropped — nothing to do, client is gone
@@ -189,8 +215,11 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
-    // ── PR3a: POST /api/v1/library (add to library) ─────────────────
-    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+    // ── #1451: POST /api/v1/library/refs (add catalog skill) ───────
+    //
+    // Was at /api/v1/library until #1452 rebound that URL to multipart
+    // file-push. Same handler logic; only the URL moved.
+    if (url.pathname === "/api/v1/library/refs" && req.method === "POST") {
       if (!checkAuth(req, res)) return;
       let body;
       try {
@@ -233,6 +262,141 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
+    // ── #1452: POST /api/v1/library (multipart file-push) ──────────
+    //
+    // Accepts multipart/form-data and returns a synthesized
+    // `LibraryPushResponse` shape. The handler does not actually
+    // parse the multipart body — it just inspects the Content-Type
+    // header to confirm the client sent multipart, and serves either
+    // a `pushResponse` slot value (set via `setPushResponse`) or a
+    // default 201 with `action: "created"` shape.
+    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+      if (!checkAuth(req, res)) return;
+      const contentType = req.headers["content-type"] ?? "";
+      if (!contentType.includes("multipart/form-data")) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error:
+              "Invalid multipart body. Set Content-Type: multipart/form-data.",
+            code: "invalid_multipart",
+          }),
+        );
+        return;
+      }
+      if (pushResponse) {
+        res.writeHead(pushResponse.status, {
+          "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify(pushResponse.body));
+        return;
+      }
+      // Default: 201 with a synthesized SyncSkill response.
+      res.writeHead(201, {
+        "Content-Type": "application/json",
+        Location: "/api/v1/library/mock/test-skill",
+      });
+      res.end(
+        JSON.stringify({
+          action: "created",
+          bump: null,
+          skill: {
+            owner: "mock",
+            name: "test-skill",
+            version: "1.0",
+            description: "mock",
+            keywords: [],
+            updatedAt: new Date().toISOString(),
+            etag: '"mock/test-skill@0"',
+            contextSignals: null,
+            files: [],
+            filesIncomplete: false,
+          },
+        }),
+      );
+      return;
+    }
+
+    // ── #1449: POST /api/v1/library/[owner]/[name]/publish ─────────
+    {
+      const m = url.pathname.match(
+        /^\/api\/v1\/library\/([^\/]+)\/([^\/]+)\/publish$/,
+      );
+      if (m && req.method === "POST") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const configured =
+          publishResponses.get(`${owner}/${name}`) ?? publishResponses.get("*");
+        if (configured) {
+          res.writeHead(configured.status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(configured.body));
+          return;
+        }
+        // Default: 200 published with synthesized SyncSkill.
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            action: "published",
+            skill: {
+              owner,
+              name,
+              version: "1.0.0",
+              description: "mock",
+              keywords: [],
+              updatedAt: new Date().toISOString(),
+              etag: `"${owner}/${name}@0"`,
+              contextSignals: null,
+              files: [],
+              filesIncomplete: false,
+            },
+          }),
+        );
+        return;
+      }
+    }
+
+    // ── #1449: POST /api/v1/library/[owner]/[name]/unpublish ───────
+    {
+      const m = url.pathname.match(
+        /^\/api\/v1\/library\/([^\/]+)\/([^\/]+)\/unpublish$/,
+      );
+      if (m && req.method === "POST") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const configured =
+          unpublishResponses.get(`${owner}/${name}`) ??
+          unpublishResponses.get("*");
+        if (configured) {
+          res.writeHead(configured.status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(configured.body));
+          return;
+        }
+        // Default: 200 unpublished, zero subscribers notified.
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            action: "unpublished",
+            notifiedSubscriberCount: 0,
+            skill: {
+              owner,
+              name,
+              version: "1.0.0",
+              description: "mock",
+              keywords: [],
+              updatedAt: new Date().toISOString(),
+              etag: `"${owner}/${name}@0"`,
+              contextSignals: null,
+              files: [],
+              filesIncomplete: false,
+            },
+          }),
+        );
+        return;
+      }
+    }
+
     // ── PR3a: DELETE /api/v1/library/[owner]/[name] (remove) ────────
     {
       const m = url.pathname.match(/^\/api\/v1\/library\/([^\/]+)\/([^\/]+)$/);
@@ -489,6 +653,34 @@ export function createMockServer(initialPayload, options = {}) {
       removeResponses = new Map();
     },
 
+    // Epic #1444 R3 #1456 — publish / unpublish slot setters.
+    setPublishResponse(owner, name, response) {
+      publishResponses.set(`${owner}/${name}`, response);
+    },
+    setPublishResponseForAny(response) {
+      publishResponses.set("*", response);
+    },
+    clearPublishResponses() {
+      publishResponses = new Map();
+    },
+    setUnpublishResponse(owner, name, response) {
+      unpublishResponses.set(`${owner}/${name}`, response);
+    },
+    setUnpublishResponseForAny(response) {
+      unpublishResponses.set("*", response);
+    },
+    clearUnpublishResponses() {
+      unpublishResponses = new Map();
+    },
+
+    /**
+     * #1452 — register the next POST /api/v1/library (multipart file-push)
+     * response. Pass `null` to restore the default 201 LibraryPushResponse.
+     */
+    setPushResponse(response) {
+      pushResponse = response;
+    },
+
     /**
      * Return the most recent POST body the server received, or null
      * if no POST has been made yet. Body is JSON-parsed when

package/src/test/lib/http.test.mjs

@@ -39,6 +39,7 @@ import {
   searchSkills,
   addSkillToLibrary,
   removeSkillFromLibrary,
+  pushSkill,
   isCliSource,
   CLI_SOURCE_VALUES,
 } from "../../lib/http.mjs";
@@ -795,7 +796,7 @@ describe("addSkillToLibrary", () => {
   it("returns { status: 'added' } on 201", async () => {
     const srv = await startServer((req, res) => {
       assert.equal(req.method, "POST");
-      assert.match(req.url, /^\/api\/v1\/library$/);
+      assert.match(req.url, /^\/api\/v1\/library\/refs$/);
       assert.equal(req.headers["content-type"], "application/json");
       jsonRes(res, 201, {
         added: {
@@ -988,6 +989,246 @@ describe("addSkillToLibrary", () => {
   });
 });
 
+// ── pushSkill (#1455 multipart upsert) ─────────────────────────────────
+
+describe("pushSkill", () => {
+  const SKILL_MD = "---\nname: my-skill\ndescription: t\n---\n\nbody\n";
+
+  /**
+   * Helper: read the request's Content-Type and verify it's multipart;
+   * accept the body without parsing. Tests assert on the response shape
+   * the helper returns and on headers / URL.
+   */
+  function makePushServer(handler) {
+    return startServer(handler);
+  }
+
+  it("hits POST /api/v1/library with multipart Content-Type", async () => {
+    const srv = await makePushServer((req, res) => {
+      assert.equal(req.method, "POST");
+      assert.match(req.url, /^\/api\/v1\/library$/);
+      assert.match(req.headers["content-type"] ?? "", /multipart\/form-data/);
+      jsonRes(res, 201, {
+        action: "created",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("sends an Idempotency-Key header on every request (auto-generated)", async () => {
+    let observedKey;
+    const srv = await makePushServer((req, res) => {
+      observedKey = req.headers["idempotency-key"];
+      jsonRes(res, 201, {
+        action: "created",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+      assert.ok(observedKey, "Idempotency-Key header should be present");
+      assert.ok(observedKey.length >= 16, "Auto-generated key should be reasonably long");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("threads an explicit idempotencyKey through to the header", async () => {
+    let observedKey;
+    const srv = await makePushServer((req, res) => {
+      observedKey = req.headers["idempotency-key"];
+      jsonRes(res, 201, {
+        action: "created",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+        idempotencyKey: "custom-key-abc",
+      });
+      assert.equal(observedKey, "custom-key-abc");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { action: 'created', bump: null, skill } on 201", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 201, {
+        action: "created",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      const result = await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+      assert.equal(result.action, "created");
+      assert.equal(result.bump, null);
+      assert.equal(result.skill.version, "1.0");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { action: 'updated', bump: 'minor' | 'major' } on 200 update", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 200, {
+        action: "updated",
+        bump: "minor",
+        skill: { owner: "mock", name: "my-skill", version: "1.1" },
+      });
+    });
+    try {
+      const result = await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+      assert.equal(result.action, "updated");
+      assert.equal(result.bump, "minor");
+      assert.equal(result.skill.version, "1.1");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { action: 'unchanged', bump: null } on 200 no-op", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 200, {
+        action: "unchanged",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      const result = await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+      assert.equal(result.action, "unchanged");
+      assert.equal(result.bump, null);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on 2xx with unknown `action` (server contract violation)", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 200, {
+        action: "weird",
+        skill: { owner: "x", name: "x", version: "1.0" },
+      });
+    });
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill(srv.url, VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) =>
+          err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("maps 403 plan_limit through mapErrorResponse to validationError", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 403, {
+        error: "Plan limit reached",
+        code: "plan_limit",
+      });
+    });
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill(srv.url, VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) =>
+          err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("maps 413 payload_too_large through mapErrorResponse", async () => {
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 413, {
+        error: "Payload exceeds limit",
+        code: "payload_too_large",
+      });
+    });
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill(srv.url, VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) => err instanceof CliError,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("retries on transient 5xx (Idempotency-Key makes retry safe)", async () => {
+    let calls = 0;
+    const srv = await makePushServer((req, res) => {
+      calls++;
+      if (calls === 1) {
+        jsonRes(res, 503, { error: "transient" });
+        return;
+      }
+      jsonRes(res, 201, {
+        action: "created",
+        bump: null,
+        skill: { owner: "mock", name: "my-skill", version: "1.0" },
+      });
+    });
+    try {
+      const result = await pushSkill(srv.url, VALID_KEY, {
+        files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+      });
+      assert.equal(result.action, "created");
+      assert.ok(calls >= 2, "Should have retried at least once");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("guards against empty serverUrl / apiKey via the cross-cutting check", async () => {
+    await assert.rejects(
+      () =>
+        pushSkill("", VALID_KEY, {
+          files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+        }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+    await assert.rejects(
+      () =>
+        pushSkill("http://x", "", {
+          files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+        }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+});
+
 // ── removeSkillFromLibrary (PR3a) ──────────────────────────────────────
 
 describe("removeSkillFromLibrary", () => {

package/src/test/lib/skill-walk.test.mjs

@@ -0,0 +1,127 @@
+/**
+ * Unit tests for `walkSkillFiles` (#1455).
+ *
+ * Verifies the walker's exclusion + path-normalization rules:
+ *   - Hidden files / dirs (anything starting with `.`) are excluded
+ *   - `node_modules` directories are excluded
+ *   - Root `SKILL.md` is INCLUDED (uploaded uniformly with other files
+ *     per the agentskills.io spec)
+ *   - Returned paths are POSIX-style + sorted
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { walkSkillFiles } from "../../lib/skill-walk.mjs";
+
+let sandbox;
+
+beforeEach(() => {
+  sandbox = mkdtempSync(join(tmpdir(), "skillrepo-walk-"));
+});
+
+afterEach(() => {
+  rmSync(sandbox, { recursive: true, force: true });
+});
+
+function file(rel, content = "x") {
+  const abs = join(sandbox, rel);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+describe("walkSkillFiles", () => {
+  it("returns all skill files in deterministic (sorted) order", async () => {
+    file("SKILL.md", "---\nname: x\n---\n");
+    file("references/intro.md");
+    file("scripts/run.sh");
+    file("assets/logo.png");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    // `localeCompare` sorts uppercase after lowercase, so SKILL.md
+    // lands last among entries with no subdir prefix.
+    assert.deepEqual(paths, [
+      "assets/logo.png",
+      "references/intro.md",
+      "scripts/run.sh",
+      "SKILL.md",
+    ]);
+  });
+
+  it("includes root SKILL.md as a regular file (agentskills.io spec)", async () => {
+    file("SKILL.md", "---\nname: x\n---\n");
+    file("references/a.md");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    assert.ok(paths.includes("SKILL.md"));
+    assert.deepEqual(paths, ["references/a.md", "SKILL.md"]);
+  });
+
+  it("excludes hidden files and dirs at every depth", async () => {
+    file("SKILL.md");
+    file(".env");
+    file(".git/HEAD");
+    file(".vscode/settings.json");
+    file("references/.DS_Store");
+    file("references/.hidden/secret");
+    file("references/foo.md");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    assert.deepEqual(paths, ["references/foo.md", "SKILL.md"]);
+  });
+
+  it("excludes node_modules directories", async () => {
+    file("SKILL.md");
+    file("node_modules/foo/index.js");
+    file("scripts/node_modules/bar/index.js");
+    file("references/intro.md");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    assert.deepEqual(paths, ["references/intro.md", "SKILL.md"]);
+  });
+
+  it("uses POSIX forward-slash paths even on Windows-style separators", async () => {
+    file("SKILL.md");
+    file("references/nested/deep.md");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    for (const p of paths) {
+      assert.ok(!p.includes("\\"), `Path ${p} contains backslash`);
+    }
+    assert.ok(paths.includes("SKILL.md"));
+    assert.ok(paths.includes("references/nested/deep.md"));
+  });
+
+  it("returns just SKILL.md when the directory has only SKILL.md + hidden files", async () => {
+    file("SKILL.md");
+    file(".env");
+    file(".git/HEAD");
+
+    const walked = await walkSkillFiles(sandbox);
+    const paths = walked.map((f) => f.relativePath);
+    assert.deepEqual(paths, ["SKILL.md"]);
+  });
+
+  it("returns absolute paths + sizes for each file", async () => {
+    file("SKILL.md", "ab");
+    file("references/a.md", "abc");
+
+    const walked = await walkSkillFiles(sandbox);
+    assert.equal(walked.length, 2);
+    const refEntry = walked.find((f) => f.relativePath === "references/a.md");
+    assert.ok(refEntry);
+    assert.ok(refEntry.absolutePath.startsWith(sandbox));
+    assert.equal(refEntry.size, 3);
+    const skillEntry = walked.find((f) => f.relativePath === "SKILL.md");
+    assert.ok(skillEntry);
+    assert.equal(skillEntry.size, 2);
+  });
+});