feat: Clerk CLI Skill

[wyattjoh]

Summary

Bundles the clerk skill into the CLI binary, pins it to the version of the binary that installed it, and teaches the skill how to invoke clerk using whatever runner the project prefers.

How it's bundled

• Markdown files at <repo-root>/skills/clerk/ are pulled into skills.ts as text imports (import md from "./SKILL.md" with { type: "text" }). These resolve live during bun run dev and get embedded by bun build --compile, so the skill content always matches the binary running it.
• At install time, the staged bundle is handed to <runner> skills add <tmpdir> --copy. --copy is required: the default symlink mode would point each agent's skill dir at the temp dir we delete right after the install.
• skills-lock.json records the install with sourceType: "local", correctly excluding it from skills update. The skill can only change when the CLI is upgraded.

How it pins

• Every asset is piped through a new renderSkillVersionPlaceholder(content, version) helper that substitutes {{CLI_VERSION}} at staging time. Release builds pin to the shipped version; dev builds (0.0.0-dev) resolve to latest.
• DEV_CLI_VERSION and resolveCliVersion() live in a new lib/version.ts so the three sites that care about the dev sentinel (the --version fallback, the skill templater, and scripts/build.ts) share one source of truth and can't drift.

How the skill invokes clerk

A new "Invoking the CLI" section in SKILL.md teaches Claude to prefer a globally installed clerk binary first, and fall back to a pinned bunx / npx -y / pnpm dlx / yarn dlx in lockfile-preferred order. Mirrors the CLI's own preferredRunner logic.

Skill correctness

• Removes a wrong claim that clerk init --prompt prints a framework-specific integration guide. It prints a short agent handoff telling the agent to run clerk init -y.
• Resyncs the skill against the current CLI surface: adds init, apps create, open, completion, and skill install to the Core commands table; adds --destructive to config patch/put; strengthens the Prerequisites section so clerk doctor --json is the mandatory session-start check; documents agent-mode behavior for apps create and clerk open.
• Adds --name (with --starter) to the init row and --secret-key to the api row in the Core commands table, and corrects the clerk api ls --platform apps example (dropped an erroneous --).
• Repositions clerk <command> --help as the source of truth for flags so the skill stays a hint rather than a spec, reducing drift surface.
• Ports useful additions from feat(clerk-cli): add Clerk CLI skill skills#29 (verified against CLI source): documents the clerk auth login/logout aliases (signup/signin/sign-in, signout/sign-out) and the top-level clerk login/clerk logout shortcuts; notes that config commands authenticate via the Platform API and ignore --secret-key; extends the --destructive explanation to config patch (same semantics as config put); adds a table mapping each failing clerk doctor check to the manual remediation command (auth login / link / env pull) so agents can remediate without --fix (which is disabled in agent mode).

Skill rename

The bundled skill is named clerk (directory: skills/clerk/, frontmatter name: clerk). CLI-level identifiers that ship to user state (macOS KEYCHAIN_SERVICE, envPaths config/cache dir) keep the clerk-cli name to avoid orphaning existing installs on upgrade.

Installer continuity

• Upstream clerk/skills continues to install via default symlink mode; the two installer calls share runner detection and fail independently.
• buildSkillsArgs gains a copy parameter and threads it through runSkillsAdd so only the clerk skill install gets --copy.

Stacked on #125.

Test plan

• bun run test passes (unit tests cover buildSkillsArgs --copy, renderSkillVersionPlaceholder edge cases, and withStagedClerkSkill staging + cleanup + version rendering)
• Manual: run clerk init in a sandbox; confirm clerk and framework-pattern installs both succeed; check skills-lock.json records clerk with sourceType: "local"
• Manual: confirm .claude/skills/clerk/ contains real files (not a broken symlink) after init
• Manual: confirm the installed SKILL.md no longer contains the literal {{CLI_VERSION}} after install

[wyattjoh]

Stack: init-skills

• feat(lib): add NonEmptyArray helper, tighten preferredRunner #125
• feat: Clerk CLI Skill #126 👈 this PR
  • feat(init): support CLERK_SKILL_SOURCE env override #127
  • docs(skill): add audit-clerk-skill for drift detection #156

Part of a stacked PR chain. Do not merge manually.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new top-level clerk skill install command that stages the bundled Clerk skill, selects or prompts for a package-runner, and invokes the external skills CLI in interactive or unattended modes. Introduces lib/package-manager.ts (PACKAGE_MANAGERS/PackageManager) and lib/version.ts (DEV_CLI_VERSION/resolveCliVersion). Refactors init-related modules to use the canonical PackageManager type and exposes package-manager detection. Splits init skill installation into a bundled clerk install and upstream clerk/skills install. Adds the skill-install implementation, unit tests, docs for agent-mode and skill usage, README/CLI help updates, and related build/tsconfig tweaks.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Clerk CLI Skill' accurately describes the main feature added: bundling and integrating the Clerk CLI skill into the CLI binary.
Description check	✅ Passed	The PR description comprehensively explains the bundling, pinning, invocation logic, skill correctness updates, naming strategy, installer changes, and test plan—all directly aligned with the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/cli-core/src/commands/init/skills.ts (1)

60-90: ⚠️ Potential issue | 🔴 Critical

Don’t reinstall clerk from the upstream source after staging the bundled skill.

installClerkSkillCore() already installs a local skill named clerk. upstreamSkills still contains "clerk", so the second runSkillsAdd() call asks the skills CLI to install another clerk from clerk/skills. That can replace the pinned local install or fail on a duplicate-name conflict, which defeats this PR’s core bundling/pinning behavior.

Suggested fix

-  const upstreamSkills = resolveUpstreamSkills(frameworkDep);
+  const upstreamSkills = resolveUpstreamSkills(frameworkDep).filter(
+    (skill) => skill !== "clerk",
+  );
   const skillList = ["clerk", ...upstreamSkills].join(", ");

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/cli-core/src/commands/init/skills.ts` around lines 60 - 90,
upstreamSkills includes "clerk" which causes runSkillsAdd to reinstall the
staged local skill; filter out "clerk" after computing upstreamSkills and before
calling runSkillsAdd (e.g. const upstreamToInstall = upstreamSkills.filter(s =>
s !== "clerk")), then pass upstreamToInstall to runSkillsAdd (both the array
param and the join string) and skip the call entirely if upstreamToInstall is
empty; keep installClerkSkillCore, skillList and prompt behavior unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/clerk/references/auth.md`:
- Around line 16-35: The bundled auth docs in skills/clerk/references/auth.md
are inaccurate vs the implementation in packages/cli-core/src/lib/plapi.ts
(lines referenced): update the doc text to match actual behavior — state that
prefix mismatches cause an error (not just a warning) and that Platform API auth
resolves only from CLERK_PLATFORM_API_KEY or the stored OAuth token (no
interactive prompt fallback), and remove or rephrase any guidance implying an
interactive prompt or silent fallback; reference the plapi.ts behavior when
rewording so readers/agents follow the CLI's real resolution flow.

---

Outside diff comments:
In `@packages/cli-core/src/commands/init/skills.ts`:
- Around line 60-90: upstreamSkills includes "clerk" which causes runSkillsAdd
to reinstall the staged local skill; filter out "clerk" after computing
upstreamSkills and before calling runSkillsAdd (e.g. const upstreamToInstall =
upstreamSkills.filter(s => s !== "clerk")), then pass upstreamToInstall to
runSkillsAdd (both the array param and the join string) and skip the call
entirely if upstreamToInstall is empty; keep installClerkSkillCore, skillList
and prompt behavior unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d23c701e-a138-48bf-816c-9339054cbbb8

📥 Commits

Reviewing files that changed from the base of the PR and between 3b840b8 and 9c7d911.

📒 Files selected for processing (22)

• .changeset/clerk-skill.md
• README.md
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/init/README.md
• packages/cli-core/src/commands/init/bootstrap-registry.ts
• packages/cli-core/src/commands/init/bootstrap.ts
• packages/cli-core/src/commands/init/context.ts
• packages/cli-core/src/commands/init/frameworks/types.ts
• packages/cli-core/src/commands/init/index.ts
• packages/cli-core/src/commands/init/skills.test.ts
• packages/cli-core/src/commands/init/skills.ts
• packages/cli-core/src/commands/skill/README.md
• packages/cli-core/src/commands/skill/install.test.ts
• packages/cli-core/src/commands/skill/install.ts
• packages/cli-core/src/lib/package-manager.ts
• packages/cli-core/src/lib/version.ts
• scripts/build.ts
• scripts/tsconfig.json
• skills/clerk/SKILL.md
• skills/clerk/references/agent-mode.md
• skills/clerk/references/auth.md
• skills/clerk/references/recipes.md

💤 Files with no reviewable changes (1)

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

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Bundled auth guidance does not match the CLI's actual fallback/error behavior.

Line 25 says bad key types only warn, and Lines 31-33 say human mode can fall back to an interactive Platform API key prompt. The implementation in packages/cli-core/src/lib/plapi.ts:17-24,30-45 does neither: prefix mismatches throw, and PLAPI auth resolves from CLERK_PLATFORM_API_KEY or stored OAuth only, then errors. Since this file ships inside the bundled skill, agents following it will take paths the CLI cannot execute. Please align this reference with the real behavior before merge.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/clerk/references/auth.md` around lines 16 - 35, The bundled auth docs
in skills/clerk/references/auth.md are inaccurate vs the implementation in
packages/cli-core/src/lib/plapi.ts (lines referenced): update the doc text to
match actual behavior — state that prefix mismatches cause an error (not just a
warning) and that Platform API auth resolves only from CLERK_PLATFORM_API_KEY or
the stored OAuth token (no interactive prompt fallback), and remove or rephrase
any guidance implying an interactive prompt or silent fallback; reference the
plapi.ts behavior when rewording so readers/agents follow the CLI's real
resolution flow.

[rafa-thayto]

The upstream clerk/skills repo still ships a skill named clerk, and it's installed after the bundled one — so it overwrites .claude/skills/clerk/ and the {{CLI_VERSION}} pinning is silently lost.

Suggested change

	const BASE_SKILLS = ["clerk", "clerk-setup"];
	const BASE_SKILLS = ["clerk-setup"];

If upstream still needs to ship clerk for some reason, flipping the install order so the bundled one runs last would work too.

[rafa-thayto]

upstreamSkills already starts with "clerk" (from BASE_SKILLS), so the prompt renders as Install agent skills? (clerk, clerk, clerk-setup, …).

If "clerk" is dropped from BASE_SKILLS above, this becomes correct naturally:

Suggested change

	const skillList = ["clerk", ...upstreamSkills].join(", ");
	const skillList = ["clerk", ...upstreamSkills].join(", ");

(Same line, but the underlying list no longer duplicates.) Otherwise dedupe explicitly:

const skillList = [...new Set(["clerk", ...upstreamSkills])].join(", ");

[rafa-thayto]

Nice to have one source of truth — but lib/update-check.ts still hardcodes the literal in getCurrentVersion() and isDevVersion(). Worth migrating those too so the sentinel really can't drift:

// in update-check.ts
import { DEV_CLI_VERSION } from "./version.ts";

export function getCurrentVersion(): string {
  return typeof CLI_VERSION !== "undefined" ? CLI_VERSION : DEV_CLI_VERSION;
}

export function isDevVersion(version: string): boolean {
  return version === DEV_CLI_VERSION;
}

[rafa-thayto]

Reaching across into another command's module (commands/init/context.ts) for a helper that's pure lockfile detection feels a bit tangled — lib/package-manager.ts is right there and is the natural home.

Suggested change

	import { detectPackageManager } from "../init/context.js";
	import type { PackageManager } from "../../lib/package-manager.js";
	import { detectPackageManager } from "../../lib/package-manager.js";

…and move detectPackageManager into lib/package-manager.ts, re-exporting from context.ts if anything still imports it from there.

[rafa-thayto]

If {{CLI_VERSION}} gets added to one of the reference files and rendering regresses, this test passes silently because it only checks SKILL.md. Worth asserting across every staged file:

test("substitutes CLI_VERSION into every staged file", async () => {
  await withStagedClerkSkill("4.5.6", async (stageDir) => {
    for (const rel of ["clerk/SKILL.md", "clerk/references/auth.md", "clerk/references/recipes.md", "clerk/references/agent-mode.md"]) {
      const content = await readFile(join(stageDir, rel), "utf8");
      expect(content, rel).not.toContain("{{CLI_VERSION}}");
    }
  });
});