feat(init): support CLERK_CLI_SKILL_SOURCE env override

Adds an escape hatch for skill authors iterating on the clerk-cli skill
without rebuilding the CLI: set CLERK_CLI_SKILL_SOURCE to any value the
`skills` CLI accepts (github URL, org/repo shorthand, absolute or
relative local path), and `clerk init` passes it straight to
`<runner> skills add <value>` in place of the bundled source.

The override path skips the staged temp dir and the --copy flag, so a
local working-tree path installs via the default symlink mode and edits
to the source are picked up immediately by already-installed projects.
The override has no effect on the upstream framework-pattern skills.

Author: wyattjoh

.changeset/clerk-cli-skill-local-debug.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `CLERK_CLI_SKILL_SOURCE` env override to install the `clerk-cli` skill from a local path, fork, or PR branch instead of the bundled content. Intended for skill authors iterating without rebuilding the CLI.

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

@@ -197,6 +197,24 @@ At install time, [`skills.ts`](./skills.ts) stages the bundled content into a fr
 
 The `skills` CLI writes the installed files into each agent's skill directory (`.claude/skills/clerk-cli/`, `.cursor/skills/clerk-cli/`, etc.) and records the entry in the project's `skills-lock.json` with `sourceType: "local"`, which correctly excludes it from `skills update` (the skill can only change when the CLI itself is upgraded).
 
+#### Local debugging
+
+For skill authors iterating on the `clerk-cli` skill without rebuilding the CLI, set `CLERK_CLI_SKILL_SOURCE` to any value the `skills` CLI accepts, and the bundled content is bypassed entirely:
+
+```sh
+# Absolute path to a working-tree skill dir (default symlink install —
+# edits to the source are reflected in the installed skill immediately).
+CLERK_CLI_SKILL_SOURCE="$PWD/skills/clerk-cli" clerk init
+
+# A fork or PR branch on GitHub.
+CLERK_CLI_SKILL_SOURCE="https://github.com/me/cli/tree/wip/skills/clerk-cli" clerk init
+
+# Shorthand for the default repo (installs from main branch).
+CLERK_CLI_SKILL_SOURCE="clerk/cli" clerk init
+```
+
+When the override is active, `clerk init` logs the value being used and hands it straight to `<runner> skills add <value>` without `--copy`, so the install mode matches whatever the `skills` CLI would do for a regular remote or local source. The override has no effect on the upstream framework-pattern skills.
+
 ### 2. The upstream framework-pattern skills
 
 The base skills `clerk` and `clerk-setup` are always included from [`clerk/skills`](https://github.com/clerk/skills). The detected framework dependency adds a matching skill:

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

@@ -74,9 +74,9 @@ export async function installSkills(
   const runner = await resolveSkillsRunner(packageManager, interactive);
   if (!runner) return;
 
-  // Install the bundled clerk-cli skill from a staged temp dir, then the
-  // upstream framework patterns. Each call soft-fails independently so a
-  // problem with one source doesn't block the other.
+  // Install the bundled clerk-cli skill (respecting CLERK_CLI_SKILL_SOURCE if
+  // set), then the upstream framework patterns. Each call soft-fails
+  // independently so a problem with one source doesn't block the other.
   const cliSkillOk = await installClerkCliSkillCore(runner, cwd, interactive);
 
   const upstreamOk = await runSkillsAdd(

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

@@ -27,6 +27,20 @@ clerk skill install --pm bun
 | `-y, --yes`      | Skip prompts; auto-select the preferred package runner and pass `-y -g` to the `skills` CLI                                 |
 | `--pm <manager>` | Package manager hint for runner detection (`bun`, `pnpm`, `yarn`, `npm`). Defaults to lockfile detection in the current dir |
 
+## Local debugging (`CLERK_CLI_SKILL_SOURCE`)
+
+Skill authors iterating on `clerk-cli` can set `CLERK_CLI_SKILL_SOURCE` to bypass the bundled content and point `skills add` at any source the `skills` CLI accepts (absolute path, GitHub URL, or `org/repo` shorthand):
+
+```sh
+# Absolute path to a working-tree skill dir (symlink install — edits are live).
+CLERK_CLI_SKILL_SOURCE="$PWD/skills/clerk-cli" clerk skill install
+
+# A fork or PR branch on GitHub.
+CLERK_CLI_SKILL_SOURCE="https://github.com/me/cli/tree/wip/skills/clerk-cli" clerk skill install
+```
+
+When the override is active, the CLI logs the value being used and passes it straight to `<runner> skills add <value>` without `--copy`. The override applies to both `clerk skill install` and the skills step in `clerk init`.
+
 ## Clerk API endpoints
 
-None. This command does not make any Clerk API calls; it only spawns the external `skills` CLI against a staged copy of the bundled skill.
+None. This command does not make any Clerk API calls; it only spawns the external `skills` CLI against a staged copy of the bundled skill (or the `CLERK_CLI_SKILL_SOURCE` override when set).

packages/cli-core/src/commands/skill/install.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import {
   buildSkillsArgs,
   renderSkillVersionPlaceholder,
+  resolveClerkCliSkillOverride,
   withStagedClerkCliSkill,
 } from "./install.ts";
 
@@ -164,3 +165,26 @@ describe("renderSkillVersionPlaceholder", () => {
     expect(renderSkillVersionPlaceholder(input, "1.2.3")).toBe(input);
   });
 });
+
+describe("resolveClerkCliSkillOverride", () => {
+  test("returns undefined when env var is unset", () => {
+    expect(resolveClerkCliSkillOverride({})).toBeUndefined();
+  });
+
+  test("returns undefined when env var is empty or whitespace", () => {
+    expect(resolveClerkCliSkillOverride({ CLERK_CLI_SKILL_SOURCE: "" })).toBeUndefined();
+    expect(resolveClerkCliSkillOverride({ CLERK_CLI_SKILL_SOURCE: "   " })).toBeUndefined();
+  });
+
+  test("returns trimmed value when env var is set", () => {
+    expect(resolveClerkCliSkillOverride({ CLERK_CLI_SKILL_SOURCE: "clerk/cli" })).toBe("clerk/cli");
+    expect(resolveClerkCliSkillOverride({ CLERK_CLI_SKILL_SOURCE: "  /tmp/my-skill  " })).toBe(
+      "/tmp/my-skill",
+    );
+    expect(
+      resolveClerkCliSkillOverride({
+        CLERK_CLI_SKILL_SOURCE: "https://github.com/me/fork/tree/wip/skills/clerk-cli",
+      }),
+    ).toBe("https://github.com/me/fork/tree/wip/skills/clerk-cli");
+  });
+});

packages/cli-core/src/commands/skill/install.ts

@@ -42,6 +42,29 @@ import clerkCliAuthMd from "../../../../../skills/clerk-cli/references/auth.md"
 import clerkCliRecipesMd from "../../../../../skills/clerk-cli/references/recipes.md" with { type: "text" };
 import clerkCliAgentModeMd from "../../../../../skills/clerk-cli/references/agent-mode.md" with { type: "text" };
 
+/**
+ * Env var that overrides the bundled `clerk-cli` skill source. Accepts any
+ * value the `skills` CLI recognises (github/gitlab URL, `org/repo` shorthand,
+ * absolute or relative local path). Intended for skill authors testing an
+ * in-progress version without recompiling the CLI.
+ */
+const SKILL_SOURCE_OVERRIDE_ENV = "CLERK_CLI_SKILL_SOURCE";
+
+/**
+ * Read the clerk-cli skill source override from the given env. Returns the
+ * trimmed value when set and non-empty, otherwise `undefined`. Exposed for
+ * tests so the precedence rule can be asserted without mutating
+ * `process.env`.
+ */
+export function resolveClerkCliSkillOverride(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const raw = env[SKILL_SOURCE_OVERRIDE_ENV];
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
  * The bundled clerk-cli skill, as `(relativePath, content)` pairs. Text
  * imports resolve live from `<repo-root>/skills/clerk-cli/` during
@@ -212,8 +235,17 @@ export async function resolveSkillsRunner(
 }
 
 /**
- * Install the bundled clerk-cli skill using a pre-resolved runner. Does not
- * prompt; callers handle any UX around confirmation and runner selection.
+ * Install the clerk-cli skill using a pre-resolved runner. Does not prompt;
+ * callers handle any UX around confirmation and runner selection.
+ *
+ * Default path: stage the bundled content into a temp dir and invoke
+ * `skills add <tmpdir> --copy` (the --copy is mandatory; the default symlink
+ * mode would point at a dir we're about to delete).
+ *
+ * Override path: when `CLERK_CLI_SKILL_SOURCE` is set, hand the value straight
+ * to `skills add` unchanged. No staging, no --copy — the caller owns the
+ * source and the install mode. Used by skill authors iterating on clerk-cli
+ * without rebuilding the CLI.
  *
  * Shared with the init flow so runner detection happens once when installing
  * clerk-cli alongside the upstream framework-pattern skills.
@@ -223,6 +255,22 @@ export async function installClerkCliSkillCore(
   cwd: string,
   interactive: boolean,
 ): Promise<boolean> {
+  const override = resolveClerkCliSkillOverride();
+  if (override) {
+    log.blank();
+    log.info(
+      `Using \`${SKILL_SOURCE_OVERRIDE_ENV}=${override}\` in place of the bundled clerk-cli skill.`,
+    );
+    return runSkillsAdd(
+      runner,
+      cwd,
+      override,
+      [],
+      interactive,
+      false,
+      `clerk-cli skill (${override})`,
+    );
+  }
   return withStagedClerkCliSkill(resolveCliVersion(), (stageDir) =>
     runSkillsAdd(runner, cwd, stageDir, [], interactive, true, "clerk-cli skill"),
   );