feat(init): version-pinned clerk-cli skill installer

Adds the clerk-cli skill at <repo-root>/skills/clerk-cli/ as a sibling
to the CLI source, distributed alongside the CLI but not bundled into
the binary. The skill is installed at clerk init time via the same
`npx skills add` mechanism as the upstream framework-pattern skills.

The clerk-cli source URL is constructed from CLI_VERSION:
  https://github.com/clerk/cli/tree/v${CLI_VERSION}/skills/clerk-cli

Every published release (stable, canary, snapshot) tags as v${version}
per release.yml/snapshot.ts, so the same template works for all of
them. Dev builds (CLI_VERSION undefined or "0.0.0-dev") fall back to
the main branch.

The two installer calls (clerk-cli + upstream framework skills) share
one runner detection and fail independently, a problem with one
source doesn't block the other.

Author: wyattjoh

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

@@ -165,12 +165,28 @@ If no entry file is found, a post-instruction is printed pointing to the Clerk J
 
 ## Agent skills install
 
-After scaffolding (and after env keys are pulled or keyless instructions are printed), `clerk init` offers to install Clerk's framework-specific agent skills from [`clerk/skills`](https://github.com/clerk/skills) via the [`skills`](https://www.npmjs.com/package/skills) CLI. The runner is detected from the project's package manager (`bunx`, `npx`, `pnpm dlx`, or `yarn dlx`), so a Bun project installs via `bunx skills add clerk/skills`, a pnpm project via `pnpm dlx skills add clerk/skills`, and so on. This step is optional and non-fatal: if no package runner is available on PATH or the install command exits non-zero, init prints a yellow warning with a runner-appropriate manual command and still exits successfully.
+After scaffolding (and after env keys are pulled or keyless instructions are printed), `clerk init` offers to install Clerk's agent skills via the [`skills`](https://www.npmjs.com/package/skills) CLI. The runner is detected from the project's package manager (`bunx`, `npx`, `pnpm dlx`, or `yarn dlx`), so a Bun project installs via `bunx skills add ...`, a pnpm project via `pnpm dlx skills add ...`, and so on. This step is optional and non-fatal: if no package runner is available on PATH or an install command exits non-zero, init prints a yellow warning with a runner-appropriate manual command and still exits successfully.
 
-- **Human mode**: prompts `Install agent skills? (...)` defaulting to yes. Pass `--no-skills` to suppress the prompt entirely, or `-y/--yes` to accept it without confirmation. When more than one runner is available, a second prompt picks which one to use (the project's package manager wins by default).
-- **Agent mode / `--prompt`**: `clerk init` exits early before the skills step runs (see the `if (options.prompt || isAgent()) { ... return }` branch in [`index.ts`](./index.ts)), so nothing is installed. Agent users should run `skills add clerk/skills` via their preferred runner manually, or have their agent do it.
+- **Human mode**: prompts `Install agent skills? (...)` defaulting to yes. Pass `--no-skills` to suppress the prompt entirely, or `-y/--yes` to accept it without confirmation. When more than one runner (`bunx`, `npx`, `pnpm dlx`, `yarn dlx`) is available, a second prompt picks the runner; the project's package manager is the default choice.
+- **Agent mode / `--prompt`**: `clerk init` exits early before the skills step runs (see the `if (options.prompt || isAgent()) { ... return }` branch in [`index.ts`](./index.ts)), so nothing is installed. Agent users should run `skills add clerk/skills` (and the version-pinned `clerk-cli` skill URL) via their preferred runner manually, or have their agent do it.
 
-The base skills `clerk` and `clerk-setup` are always included. The detected framework dependency adds a matching skill:
+Two install commands run, sharing one runner:
+
+### 1. The version-pinned `clerk-cli` skill
+
+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`):
+
+```
+https://github.com/clerk/cli/tree/v<CLI_VERSION>/skills/clerk-cli
+```
+
+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`.
+
+### 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:
 
 | Framework dep           | Added skill                   |
 | ----------------------- | ----------------------------- |
@@ -185,7 +201,13 @@ The base skills `clerk` and `clerk-setup` are always included. The detected fram
 | `express`               | `clerk-backend-api`           |
 | `fastify`               | `clerk-backend-api`           |
 
-Implementation lives in [`skills.ts`](./skills.ts). Note that the E2E fixture setup runs `clerk init --yes --no-skills` because the skill templates reference framework-generated types (e.g. React Router's `./+types/root`) that don't exist outside a real app directory and would break the fixture's `tsc` step.
+These skills version independently of the CLI, so no pin is applied.
+
+### Failure handling
+
+The two install commands fail independently, a problem fetching the version-pinned `clerk-cli` skill (e.g. tag doesn't exist yet, network error) does not block the upstream skills install, and vice versa. Each failure prints its own yellow warning with a manual install command. Init continues and exits successfully either way.
+
+Implementation lives in [`skills.ts`](./skills.ts). Note that the E2E fixture setup runs `clerk init --yes --no-skills` because the framework template skills reference auto-generated types (e.g. React Router's `./+types/root`) that don't exist outside a real app directory and would break the fixture's `tsc` step.
 
 ## API Endpoints
 

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

@@ -3,9 +3,10 @@ import { buildSkillsArgs } from "./skills.ts";
 
 describe("buildSkillsArgs", () => {
   const skills = ["clerk", "clerk-setup", "clerk-nextjs-patterns"];
+  const upstream = "clerk/skills";
 
   test("interactive mode: no -y or -g, lets skills CLI take over", () => {
-    const args = buildSkillsArgs(skills, true);
+    const args = buildSkillsArgs(upstream, skills, true);
     expect(args).toEqual([
       "skills",
       "add",
@@ -23,14 +24,21 @@ describe("buildSkillsArgs", () => {
   });
 
   test("non-interactive mode: includes -y and -g for global auto-detect", () => {
-    const args = buildSkillsArgs(skills, false);
+    const args = buildSkillsArgs(upstream, skills, false);
     expect(args).toContain("-y");
     expect(args).toContain("-g");
     expect(args).not.toContain("--agent");
   });
 
   test("never passes --agent (lets skills CLI auto-detect)", () => {
-    expect(buildSkillsArgs(skills, true)).not.toContain("--agent");
-    expect(buildSkillsArgs(skills, false)).not.toContain("--agent");
+    expect(buildSkillsArgs(upstream, skills, true)).not.toContain("--agent");
+    expect(buildSkillsArgs(upstream, skills, false)).not.toContain("--agent");
+  });
+
+  test("empty skillNames omits --skill flags (used for the clerk-cli source)", () => {
+    const cliUrl = "https://github.com/clerk/cli/tree/main/skills/clerk-cli";
+    const args = buildSkillsArgs(cliUrl, [], true);
+    expect(args).toEqual(["skills", "add", cliUrl]);
+    expect(args).not.toContain("--skill");
   });
 });

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

@@ -1,9 +1,17 @@
 /**
  * Install Clerk agent skills after scaffolding.
  *
- * Maps the detected framework to the appropriate skill set from
- * github.com/clerk/skills, then installs via the user's package runner
- * (bunx, npx, pnpm dlx, or yarn dlx).
+ * Two installer calls share one runner detection:
+ *
+ *  1. The `clerk-cli` skill ships from this repo (`clerk/cli`) at the
+ *     same git tag as the CLI binary, so the skill content always matches
+ *     the binary the user is running. The source URL is constructed from
+ *     `CLI_VERSION` (compile-time global, falls back to "main" for the
+ *     local-dev sentinel "0.0.0-dev").
+ *
+ *  2. The framework-pattern skills (`clerk`, `clerk-setup`,
+ *     `clerk-<framework>-patterns`) ship from the upstream `clerk/skills`
+ *     repo and version independently of the CLI.
  *
  * The skills CLI itself handles agent auto-detection and scope selection:
  * in interactive mode we hand off entirely (no `--agent` / `-y`), so the
@@ -24,10 +32,10 @@ import {
 import { isNonEmpty } from "../../lib/helpers/arrays.js";
 import type { ProjectContext } from "./frameworks/types.js";
 
-/** Skills installed regardless of framework. */
+/** Upstream skills installed regardless of framework. */
 const BASE_SKILLS = ["clerk", "clerk-setup"];
 
-/** Maps framework dep (from package.json) to the skill name in clerk/skills. */
+/** Maps framework dep (from package.json) to the upstream skill name. */
 const FRAMEWORK_SKILL_MAP: Record<string, string> = {
   next: "clerk-nextjs-patterns",
   react: "clerk-react-patterns",
@@ -41,9 +49,13 @@ const FRAMEWORK_SKILL_MAP: Record<string, string> = {
   fastify: "clerk-backend-api",
 };
 
-const SKILLS_SOURCE = "clerk/skills";
+/** Source for upstream framework-pattern skills. */
+const UPSTREAM_SKILLS_SOURCE = "clerk/skills";
 
-function resolveSkills(frameworkDep: string | undefined): string[] {
+/** Repo for the version-pinned clerk-cli skill (this repo). */
+const CLERK_CLI_REPO = "https://github.com/clerk/cli";
+
+function resolveUpstreamSkills(frameworkDep: string | undefined): string[] {
   const skills = [...BASE_SKILLS];
   if (frameworkDep && FRAMEWORK_SKILL_MAP[frameworkDep]) {
     skills.push(FRAMEWORK_SKILL_MAP[frameworkDep]);
@@ -52,8 +64,30 @@ function resolveSkills(frameworkDep: string | undefined): string[] {
 }
 
 /**
- * Build the runner-agnostic argv for `skills add ...`. The caller prepends
- * the runner (bunx / npx / pnpm dlx / yarn dlx) via {@link runnerCommand}.
+ * Resolve the git ref to use when installing the clerk-cli skill from this
+ * repo. Every release (stable, canary, snapshot) tags as `v${CLI_VERSION}` —
+ * see `.github/workflows/release.yml` and `scripts/snapshot.ts`. 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`.
+ */
+function clerkCliSkillRef(): string {
+  const version = typeof CLI_VERSION !== "undefined" ? CLI_VERSION : "0.0.0-dev";
+  if (version === "0.0.0-dev") return "main";
+  return `v${version}`;
+}
+
+function clerkCliSkillUrl(): string {
+  return `${CLERK_CLI_REPO}/tree/${clerkCliSkillRef()}/skills/clerk-cli`;
+}
+
+/**
+ * Build the runner-agnostic argv for `skills add <source> ...`. The caller
+ * prepends the runner (bunx / npx / pnpm dlx / yarn dlx) via
+ * {@link runnerCommand}.
+ *
+ * `skillNames` becomes `--skill <name>` pairs; leave empty to install every
+ * skill from `source` (what we do for the clerk-cli source).
  *
  * Interactive mode: hand off to the skills CLI's native UX (auto-detect
  * installed agents, scope picker) by omitting `--agent` and `-y`.
@@ -62,10 +96,57 @@ function resolveSkills(frameworkDep: string | undefined): string[] {
  *
  * Exported for tests.
  */
-export function buildSkillsArgs(skills: string[], interactive: boolean): string[] {
-  const skillFlags = skills.flatMap((s) => ["--skill", s]);
+export function buildSkillsArgs(
+  source: string,
+  skillNames: readonly string[],
+  interactive: boolean,
+): string[] {
+  const skillFlags = skillNames.flatMap((s) => ["--skill", s]);
   const extraFlags = interactive ? [] : ["-y", "-g"];
-  return ["skills", "add", SKILLS_SOURCE, ...skillFlags, ...extraFlags];
+  return ["skills", "add", source, ...skillFlags, ...extraFlags];
+}
+
+/**
+ * Run a single `skills add ...` invocation. Returns true on success, false
+ * on any failure (spawn error, non-zero exit). Failures print a yellow
+ * warning but never throw — skills are optional and shouldn't tear down
+ * a successful scaffold.
+ */
+async function runSkillsAdd(
+  runner: Runner,
+  cwd: string,
+  source: string,
+  skillNames: readonly string[],
+  interactive: boolean,
+  label: string,
+): Promise<boolean> {
+  const command = runnerCommand(runner, buildSkillsArgs(source, skillNames, interactive));
+  const displayCommand = `${runner.display} skills add ${source}`;
+
+  console.log(`\nInstalling ${cyan(label)} with ${cyan(runner.display)}...`);
+
+  let exitCode: number;
+  try {
+    const proc = Bun.spawn(command, {
+      cwd,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    exitCode = await proc.exited;
+  } catch {
+    console.log(yellow(`\nCould not run \`${displayCommand}\`. You can install manually later.`));
+    return false;
+  }
+
+  if (exitCode !== 0) {
+    console.log(
+      yellow(`\n${label} installation failed. You can install manually: ${displayCommand}`),
+    );
+    return false;
+  }
+
+  return true;
 }
 
 export async function installSkills(
@@ -74,8 +155,9 @@ export async function installSkills(
   packageManager: ProjectContext["packageManager"] | undefined,
   skipPrompt: boolean,
 ): Promise<void> {
-  const skills = resolveSkills(frameworkDep);
-  const skillList = skills.join(", ");
+  const upstreamSkills = resolveUpstreamSkills(frameworkDep);
+  const skillRef = clerkCliSkillRef();
+  const skillList = ["clerk-cli", ...upstreamSkills].join(", ");
 
   if (isHuman() && !skipPrompt) {
     const install = await confirm({
@@ -92,7 +174,7 @@ export async function installSkills(
     console.log(
       yellow(
         "\nNo package runner found on PATH (looked for bunx, npx, pnpm, yarn). " +
-          `Install one and run \`${suggested.display} skills add ${SKILLS_SOURCE}\` manually.`,
+          `Install one and run \`${suggested.display} skills add ${UPSTREAM_SKILLS_SOURCE}\` manually.`,
       ),
     );
     return;
@@ -114,31 +196,31 @@ export async function installSkills(
   }
 
   const interactive = isHuman() && !skipPrompt;
-  const command = runnerCommand(runner, buildSkillsArgs(skills, interactive));
-  const displayCommand = `${runner.display} skills add ${SKILLS_SOURCE}`;
-
-  console.log(`\nInstalling skills with ${cyan(runner.display)}: ${cyan(skillList)}`);
-
-  let exitCode: number;
-  try {
-    const proc = Bun.spawn(command, {
-      cwd,
-      stdin: "inherit",
-      stdout: "inherit",
-      stderr: "inherit",
-    });
-    exitCode = await proc.exited;
-  } catch {
-    console.log(yellow(`\nCould not run \`${displayCommand}\`. You can install manually later.`));
-    return;
-  }
 
-  if (exitCode !== 0) {
+  // Install the version-pinned clerk-cli skill from this repo, then the
+  // upstream framework patterns. Each call soft-fails independently so a
+  // problem with one source doesn't block the other.
+  const cliSkillOk = await runSkillsAdd(
+    runner,
+    cwd,
+    clerkCliSkillUrl(),
+    [],
+    interactive,
+    `clerk-cli skill (${skillRef})`,
+  );
+
+  const upstreamOk = await runSkillsAdd(
+    runner,
+    cwd,
+    UPSTREAM_SKILLS_SOURCE,
+    upstreamSkills,
+    interactive,
+    upstreamSkills.join(", "),
+  );
+
+  if (cliSkillOk && upstreamOk) {
     console.log(
-      yellow(`\nSkills installation failed. You can install manually: ${displayCommand}`),
+      dim("\nAgent skills installed. AI agents now have Clerk context in this project."),
     );
-    return;
   }
-
-  console.log(dim("\nAgent skills installed. AI agents now have Clerk context in this project."));
 }