refactor(skill): rename clerk-cli skill to clerk

Rename the bundled skill from `clerk-cli` to `clerk` everywhere the name
appears as a skill identifier: directory path, frontmatter `name:`, user-
facing copy, and the JS/TS identifiers that track it (import bindings,
`BUNDLED_CLERK_SKILL`, `withStagedClerkSkill`, `installClerkSkillCore`).

Leaves CLI-level identifiers untouched since changing them would orphan
user state on upgrade: `KEYCHAIN_SERVICE = "clerk-cli"` (macOS keychain),
`envPaths("clerk-cli", ...)` (OS config/cache paths), and the
`clerk-cli-mock-auth` test-fixture package name.

Author: wyattjoh

.changeset/clerk-cli-skill.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk skill install` to install the bundled `clerk` Claude Code skill into your project. The skill ships with the CLI and is pinned to the CLI's version, and `clerk init` now offers to install it alongside the framework-pattern skills.

.changeset/clerk-skill.md

@@ -55,7 +55,7 @@ Commands:
     (no args)                                Interactive request builder (TTY only)
   doctor      [options]                      Check your project's Clerk integration health
   skill                                      Manage the bundled Clerk CLI agent skill
-    install   [options]                      Install the bundled clerk-cli agent skill
+    install   [options]                      Install the bundled clerk agent skill
   switch-env  [environment]                  Switch the active Clerk CLI environment
   completion  [shell]                        Generate shell autocompletion script
   update      [options]                      Update the Clerk CLI to the latest version

README.md

@@ -487,7 +487,7 @@ Tutorial — enable completions for your shell:
     .command("skill")
     .description("Manage the bundled Clerk CLI agent skill")
     .setExamples([
-      { command: "clerk skill install", description: "Install the clerk-cli agent skill" },
+      { command: "clerk skill install", description: "Install the clerk agent skill" },
       {
         command: "clerk skill install -y",
         description: "Install non-interactively (auto-detect agents, global scope)",
@@ -496,7 +496,7 @@ Tutorial — enable completions for your shell:
 
   skill
     .command("install")
-    .description("Install the bundled clerk-cli agent skill")
+    .description("Install the bundled clerk agent skill")
     .option("-y, --yes", "Skip prompts and run the `skills` CLI unattended")
     .addOption(
       createOption("--pm <manager>", "Package manager hint for runner detection").choices(

packages/cli-core/src/cli-program.ts

@@ -185,17 +185,17 @@ After scaffolding (and after env keys are pulled or keyless instructions are pri
 
 - **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**: skills are installed non-interactively with `-y -g` flags (no prompt shown). Pass `--no-skills` to skip entirely.
-- **`--prompt`**: exits before the skills step runs. Agent users should run `skills add clerk/skills` via their preferred runner manually; the bundled `clerk-cli` skill is only installable via `clerk init` itself, since its source lives inside the CLI binary.
+- **`--prompt`**: exits before the skills step runs. Agent users should run `skills add clerk/skills` via their preferred runner manually; the bundled `clerk` skill is only installable via `clerk init` itself, since its source lives inside the CLI binary.
 
 Two install commands run, sharing one runner:
 
-### 1. The bundled `clerk-cli` skill
+### 1. The bundled `clerk` skill
 
-The `clerk-cli` skill ships **inside the CLI binary**. Its markdown files at [`<repo-root>/skills/clerk-cli/`](../../../../../skills/clerk-cli/) are pulled into [`skills.ts`](./skills.ts) as [text imports](https://bun.com/docs/bundler/loaders#text) (`import md from "./SKILL.md" with { type: "text" }`) and embedded by `bun build --compile`, so the skill content always matches the binary running it. No network, no tag, no version fallback.
+The `clerk` skill ships **inside the CLI binary**. Its markdown files at [`<repo-root>/skills/clerk/`](../../../../../skills/clerk/) are pulled into [`skills.ts`](./skills.ts) as [text imports](https://bun.com/docs/bundler/loaders#text) (`import md from "./SKILL.md" with { type: "text" }`) and embedded by `bun build --compile`, so the skill content always matches the binary running it. No network, no tag, no version fallback.
 
 At install time, [`skills.ts`](./skills.ts) stages the bundled content into a fresh temp directory (`mkdtemp`) and invokes `<runner> skills add <tmpdir> --copy`. The `--copy` flag is required: the default symlink mode would point each agent's skill dir at the temp dir, which we delete immediately after the install completes.
 
-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).
+The `skills` CLI writes the installed files into each agent's skill directory (`.claude/skills/clerk/`, `.cursor/skills/clerk/`, 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).
 
 ### 2. The upstream framework-pattern skills
 
@@ -218,7 +218,7 @@ These skills version independently of the CLI, so no pin is applied.
 
 ### Failure handling
 
-The two install commands fail independently: a problem with the bundled `clerk-cli` skill install (e.g. the `skills` CLI can't be fetched by the runner) does not block the upstream skills install, and vice versa. Each failure prints its own yellow warning with a manual install command (where applicable — the bundled `clerk-cli` skill has no standalone manual command, since its source lives in the binary). Init continues and exits successfully either way.
+The two install commands fail independently: a problem with the bundled `clerk` skill install (e.g. the `skills` CLI can't be fetched by the runner) does not block the upstream skills install, and vice versa. Each failure prints its own yellow warning with a manual install command (where applicable — the bundled `clerk` skill has no standalone manual command, since its source lives in the binary). 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.
 

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

@@ -3,7 +3,7 @@
  *
  * Two installer calls share one runner detection:
  *
- *  1. The bundled `clerk-cli` skill (embedded in the binary via text
+ *  1. The bundled `clerk` skill (embedded in the binary via text
  *     imports). Delegated to the `clerk skill install` core helpers in
  *     `commands/skill/install.ts`.
  *
@@ -21,7 +21,7 @@ import { isHuman } from "../../mode.js";
 import { log } from "../../lib/log.js";
 import { confirm } from "../../lib/prompts.js";
 import type { ProjectContext } from "./frameworks/types.js";
-import { installClerkCliSkillCore, resolveSkillsRunner, runSkillsAdd } from "../skill/install.js";
+import { installClerkSkillCore, resolveSkillsRunner, runSkillsAdd } from "../skill/install.js";
 
 /** Upstream skills installed regardless of framework. */
 const BASE_SKILLS = ["clerk", "clerk-setup"];
@@ -58,7 +58,7 @@ export async function installSkills(
   skipPrompt: boolean,
 ): Promise<void> {
   const upstreamSkills = resolveUpstreamSkills(frameworkDep);
-  const skillList = ["clerk-cli", ...upstreamSkills].join(", ");
+  const skillList = ["clerk", ...upstreamSkills].join(", ");
 
   if (isHuman() && !skipPrompt) {
     const install = await confirm({
@@ -74,10 +74,10 @@ 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
+  // Install the bundled clerk 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.
-  const cliSkillOk = await installClerkCliSkillCore(runner, cwd, interactive);
+  const cliSkillOk = await installClerkSkillCore(runner, cwd, interactive);
 
   const upstreamOk = await runSkillsAdd(
     runner,

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

@@ -1,12 +1,12 @@
 # Skill Command
 
-Manages the bundled `clerk-cli` agent skill. The skill is embedded in the CLI binary at compile time via text imports from `skills/clerk-cli/`, so it always matches the version of the CLI in use.
+Manages the bundled `clerk` agent skill. The skill is embedded in the CLI binary at compile time via text imports from `skills/clerk/`, so it always matches the version of the CLI in use.
 
 ## Subcommands
 
 ### `clerk skill install`
 
-Installs the bundled `clerk-cli` skill for any locally detected AI agents (Claude Code, Cursor, etc.). The actual agent detection and scope selection is delegated to the external [`skills`](https://www.npmjs.com/package/skills) CLI, which is invoked via the preferred package runner on PATH (`bunx`, `pnpm dlx`, `yarn dlx`, or `npx`).
+Installs the bundled `clerk` skill for any locally detected AI agents (Claude Code, Cursor, etc.). The actual agent detection and scope selection is delegated to the external [`skills`](https://www.npmjs.com/package/skills) CLI, which is invoked via the preferred package runner on PATH (`bunx`, `pnpm dlx`, `yarn dlx`, or `npx`).
 
 Interactive mode hands off entirely to the `skills` CLI picker. Non-interactive mode (`-y`, agent mode, or no TTY) passes `-y -g` so the skills CLI runs unattended against global scope with auto-detected agents.
 

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

@@ -2,11 +2,7 @@ import { test, expect, describe } from "bun:test";
 import { existsSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-import {
-  buildSkillsArgs,
-  renderSkillVersionPlaceholder,
-  withStagedClerkCliSkill,
-} from "./install.ts";
+import { buildSkillsArgs, renderSkillVersionPlaceholder, withStagedClerkSkill } from "./install.ts";
 
 describe("buildSkillsArgs", () => {
   const skills = ["clerk", "clerk-setup", "clerk-nextjs-patterns"];
@@ -43,45 +39,42 @@ describe("buildSkillsArgs", () => {
     expect(buildSkillsArgs(upstream, skills, false, false)).not.toContain("--agent");
   });
 
-  test("empty skillNames omits --skill flags (used for the clerk-cli source)", () => {
-    const stageDir = "/tmp/clerk-cli-skill-abc";
+  test("empty skillNames omits --skill flags (used for the clerk source)", () => {
+    const stageDir = "/tmp/clerk-skill-abc";
     const args = buildSkillsArgs(stageDir, [], true, true);
     expect(args).toEqual(["skills", "add", stageDir, "--copy"]);
     expect(args).not.toContain("--skill");
   });
 
-  test("copy=true appends --copy flag (required for the staged clerk-cli dir)", () => {
-    const args = buildSkillsArgs("/tmp/clerk-cli-skill-xyz", [], false, true);
+  test("copy=true appends --copy flag (required for the staged clerk dir)", () => {
+    const args = buildSkillsArgs("/tmp/clerk-skill-xyz", [], false, true);
     expect(args).toContain("--copy");
     // --copy should trail -y / -g, not replace them.
     expect(args).toContain("-y");
     expect(args).toContain("-g");
   });
 });
 
-describe("withStagedClerkCliSkill", () => {
+describe("withStagedClerkSkill", () => {
   test("stages all bundled files into a fresh temp dir and cleans up after", async () => {
     let observed: { dir: string; files: Record<string, string> } | null = null;
 
-    await withStagedClerkCliSkill(undefined, async (dir) => {
+    await withStagedClerkSkill(undefined, async (dir) => {
       const files = {
-        "clerk-cli/SKILL.md": await readFile(join(dir, "clerk-cli/SKILL.md"), "utf-8"),
-        "clerk-cli/references/auth.md": await readFile(
-          join(dir, "clerk-cli/references/auth.md"),
+        "clerk/SKILL.md": await readFile(join(dir, "clerk/SKILL.md"), "utf-8"),
+        "clerk/references/auth.md": await readFile(join(dir, "clerk/references/auth.md"), "utf-8"),
+        "clerk/references/recipes.md": await readFile(
+          join(dir, "clerk/references/recipes.md"),
           "utf-8",
         ),
-        "clerk-cli/references/recipes.md": await readFile(
-          join(dir, "clerk-cli/references/recipes.md"),
-          "utf-8",
-        ),
-        "clerk-cli/references/agent-mode.md": await readFile(
-          join(dir, "clerk-cli/references/agent-mode.md"),
+        "clerk/references/agent-mode.md": await readFile(
+          join(dir, "clerk/references/agent-mode.md"),
           "utf-8",
         ),
       };
       observed = { dir, files };
 
-      const entry = await stat(join(dir, "clerk-cli"));
+      const entry = await stat(join(dir, "clerk"));
       expect(entry.isDirectory()).toBe(true);
     });
 
@@ -95,7 +88,7 @@ describe("withStagedClerkCliSkill", () => {
     }
 
     // SKILL.md should at least contain the YAML frontmatter marker.
-    expect(files["clerk-cli/SKILL.md"]).toContain("---");
+    expect(files["clerk/SKILL.md"]).toContain("---");
 
     // Temp dir is removed once the callback returns.
     expect(existsSync(dir)).toBe(false);
@@ -105,7 +98,7 @@ describe("withStagedClerkCliSkill", () => {
     let capturedDir: string | null = null;
 
     await expect(
-      withStagedClerkCliSkill(undefined, async (dir) => {
+      withStagedClerkSkill(undefined, async (dir) => {
         capturedDir = dir;
         throw new Error("boom");
       }),
@@ -116,17 +109,17 @@ describe("withStagedClerkCliSkill", () => {
   });
 });
 
-describe("withStagedClerkCliSkill version rendering", () => {
+describe("withStagedClerkSkill version rendering", () => {
   test("substitutes CLI_VERSION into the staged SKILL.md", async () => {
-    await withStagedClerkCliSkill("4.5.6", async (stageDir) => {
-      const skill = await readFile(join(stageDir, "clerk-cli/SKILL.md"), "utf8");
+    await withStagedClerkSkill("4.5.6", async (stageDir) => {
+      const skill = await readFile(join(stageDir, "clerk/SKILL.md"), "utf8");
       expect(skill).not.toContain("{{CLI_VERSION}}");
     });
   });
 
   test("passes undefined through as `latest`", async () => {
-    await withStagedClerkCliSkill(undefined, async (stageDir) => {
-      const skill = await readFile(join(stageDir, "clerk-cli/SKILL.md"), "utf8");
+    await withStagedClerkSkill(undefined, async (stageDir) => {
+      const skill = await readFile(join(stageDir, "clerk/SKILL.md"), "utf8");
       expect(skill).not.toContain("{{CLI_VERSION}}");
     });
   });