feat(init): support local debugging of clerk-cli skill source

Extends the clerk-cli skill source resolver from a CLI_VERSION-only
lookup to a four-tier flow:

  1. CLERK_CLI_SKILL_SOURCE env var (explicit override, any mode)
  2. CLI_VERSION → matching v${version} tag URL (released binary)
  3. Local working-tree path resolved via import.meta.url (bun run dev
     from a checked-out repo)
  4. tree/main/skills/clerk-cli (compiled local binary fallback)

The local working-tree path resolution is the killer feature for
developer iteration: edit skills/clerk-cli/SKILL.md in your checkout,
re-run `bun run dev -- init`, and the installer reads your working
tree directly. No push, no rebuild, uncommitted edits visible.

resolveSkillSource is exported as a pure function (takes its three
inputs as plain arguments) so it's testable without mocking process.env,
CLI_VERSION, or the filesystem. Adds 9 unit tests covering every branch.

Author: wyattjoh

packages/cli-core/src/commands/init/README.md

@@ -172,17 +172,36 @@ After scaffolding (and after env keys are pulled or keyless instructions are pri
 
 Two install commands run, sharing one runner:
 
-### 1. The version-pinned `clerk-cli` skill
+### 1. The `clerk-cli` skill (from this repo)
 
 The `clerk-cli` skill ships **from this repo** at [`<repo-root>/skills/clerk-cli/`](../../../../../skills/clerk-cli/). It is **not** bundled into the binary, it's fetched at install time by the `skills` CLI, the same way any other skill would be.
 
-The source URL is constructed from `CLI_VERSION` (the compile-time global injected by `scripts/build.ts`):
+The source is resolved by [`resolveSkillSource()`](./skills.ts) in this priority order:
 
-```
-https://github.com/clerk/cli/tree/v<CLI_VERSION>/skills/clerk-cli
-```
+1. **`CLERK_CLI_SKILL_SOURCE` env var**, explicit override. Accepts any source the `skills` CLI accepts (github URL, gitlab URL, local path, git URL). Wins over everything else, in any build mode. Use this for testing forks, feature branches, or custom builds. Label: `custom`.
+2. **`CLI_VERSION` injected at compile time**, released binary path. Builds the URL `https://github.com/clerk/cli/tree/v${CLI_VERSION}/skills/clerk-cli`. Every published release (stable, canary, snapshot) tags as `v${CLI_VERSION}` (see `.github/workflows/release.yml` and `scripts/snapshot.ts`), so the same template works for all of them. Label: `v0.0.2` (or whatever the version is).
+3. **Local working-tree path**, dev mode auto-detection. When running via `bun run dev` from a checked-out copy of this repo, [`resolveLocalSkillPath()`](./skills.ts) walks back from `import.meta.url` to `<repo-root>/skills/clerk-cli/` and passes the **filesystem path** as the source. Working-tree edits (committed or not) are picked up immediately, no push, no rebuild. In compiled binaries, `import.meta.url` resolves to a virtual bundle path that doesn't exist on disk, so `existsSync` returns false and this branch is skipped. Label: `local`.
+4. **`tree/main/skills/clerk-cli` fallback**, last resort for compiled local binaries (`bun run build:compile` without `--version`) where neither the env var nor a local working tree is available. Label: `main`.
+
+The label appears in the install heading (e.g. `Installing clerk-cli skill (local) with bunx...`) so the developer can tell at a glance which source the installer is hitting.
+
+#### Local debugging
 
-Every published release (stable, canary, and snapshot) tags as `v${CLI_VERSION}` (see `.github/workflows/release.yml`), so the same `tree/v<version>/skills/clerk-cli` URL works for all of them. The only case without a matching tag is the local-dev sentinel `0.0.0-dev` (set by `scripts/build.ts` when no `--version` is passed), which falls back to `main`.
+Two ways to test changes to the skill content:
+
+```sh
+# 1. Edit-then-run loop (the most common case): just edit the file and re-run.
+#    bun run dev auto-detects the local working-tree path, so uncommitted
+#    edits are visible to the installer immediately.
+$EDITOR skills/clerk-cli/SKILL.md
+bun run dev -- init  # Installing clerk-cli skill (local) with ...
+
+# 2. Test against a remote source: set CLERK_CLI_SKILL_SOURCE to override.
+#    Useful for QA-ing a feature branch, a fork, or a release candidate
+#    before it's tagged.
+CLERK_CLI_SKILL_SOURCE='https://github.com/clerk/cli/tree/feature-x/skills/clerk-cli' \
+  bun run dev -- init
+```
 
 ### 2. The upstream framework-pattern skills
 

packages/cli-core/src/commands/init/skills.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { buildSkillsArgs } from "./skills.ts";
+import { buildSkillsArgs, resolveSkillSource } from "./skills.ts";
 
 describe("buildSkillsArgs", () => {
   const skills = ["clerk", "clerk-setup", "clerk-nextjs-patterns"];
@@ -42,3 +42,102 @@ describe("buildSkillsArgs", () => {
     expect(args).not.toContain("--skill");
   });
 });
+
+const REPO = "https://github.com/clerk/cli";
+
+describe("resolveSkillSource", () => {
+  test("env override wins over everything else", () => {
+    const result = resolveSkillSource({
+      override: "https://github.com/fork/cli/tree/main/skills/clerk-cli",
+      cliVersion: "0.0.2",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("https://github.com/fork/cli/tree/main/skills/clerk-cli");
+    expect(result.label).toBe("custom");
+  });
+
+  test("env override accepts a local path", () => {
+    const result = resolveSkillSource({
+      override: "./my-skills/clerk-cli",
+      cliVersion: undefined,
+      localPath: null,
+    });
+    expect(result.source).toBe("./my-skills/clerk-cli");
+    expect(result.label).toBe("custom");
+  });
+
+  test("empty override string falls through to next branch", () => {
+    const result = resolveSkillSource({
+      override: "",
+      cliVersion: "0.0.2",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2");
+  });
+
+  test("released stable build → matching tag URL", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.2",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    // CLI_VERSION beats local path — released binaries should always use
+    // their pinned tag, even if a checked-out copy of the repo is reachable.
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2");
+  });
+
+  test("released canary build → matching canary tag URL", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.2-canary.v20260407010352",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/v0.0.2-canary.v20260407010352/skills/clerk-cli`);
+    expect(result.label).toBe("v0.0.2-canary.v20260407010352");
+  });
+
+  test('"0.0.0-dev" sentinel is treated as "no version"', () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.0-dev",
+      localPath: "/home/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("/home/dev/clerk/cli/skills/clerk-cli");
+    expect(result.label).toBe("local");
+  });
+
+  test("undefined cliVersion + local path available → local path", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: undefined,
+      localPath: "/Users/dev/clerk/cli/skills/clerk-cli",
+    });
+    expect(result.source).toBe("/Users/dev/clerk/cli/skills/clerk-cli");
+    expect(result.label).toBe("local");
+  });
+
+  test("no override, no version, no local path → main fallback", () => {
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: undefined,
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/main/skills/clerk-cli`);
+    expect(result.label).toBe("main");
+  });
+
+  test('"0.0.0-dev" sentinel without local path → main fallback', () => {
+    // This is the compiled-local-binary case: bun run build:compile produced
+    // a binary with no --version arg, no env var override, and no source
+    // files reachable on disk.
+    const result = resolveSkillSource({
+      override: undefined,
+      cliVersion: "0.0.0-dev",
+      localPath: null,
+    });
+    expect(result.source).toBe(`${REPO}/tree/main/skills/clerk-cli`);
+    expect(result.label).toBe("main");
+  });
+});