feat: Clerk CLI Skill by wyattjoh · Pull Request #126 · clerk/cli

wyattjoh · 2026-04-07T18:41:39Z

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 · 2026-04-07T18:42:09Z

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.

Pulls the clerk-cli skill markdown files at <repo-root>/skills/clerk-cli/ into skills.ts as text imports (`import md from "./SKILL.md" with { type: "text" }`), which resolve live during `bun run dev` and get embedded by `bun build --compile`. The skill content therefore always matches the binary running it, with no network lookup, no tag publishing race, and no CLI_VERSION URL fallback. At install time, `installSkills` stages the bundled content into a fresh `mkdtemp` directory and invokes `<runner> skills add <tmpdir> --copy`. The --copy flag is required: the `skills` CLI's default symlink mode would point each agent's skill dir at the temp dir, which we delete immediately after the install completes. Copy mode produces real files in `.claude/skills/clerk-cli/` etc. and records the install 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 upstream `clerk/skills` install continues to use the default symlink mode against the remote source. The two installer calls share one runner detection and fail independently.

Installs the bundled clerk-cli skill standalone so projects set up before the skill was bundled, or CLIs upgraded since, can pull it in without re-running init. `init` now delegates the clerk-cli portion to shared core in commands/skill/install.ts, keeping a single runner detection across clerk-cli and upstream framework skills. Also extracts PACKAGE_MANAGERS as the canonical tuple plus derived type in lib/package-manager.ts, reused by both `init --pm` and `skill install --pm` choices. PM_PRIORITY in bootstrap keeps its semantic name via `satisfies readonly PackageManager[]` plus a compile-time exhaustiveness guard. Fix the nano-staged oxlint hook to pass `-c .oxlintrc.json` explicitly so override files (e.g. `unicorn/no-process-exit` off in cli-program.ts) apply when linting specific paths; bare `oxlint <file>` does not auto-discover the config.

Hoists the dev-version sentinel to a shared lib/version module so cli-program.ts and install.ts stay in lockstep. Adds resolveCliVersion() which maps both undefined and the 0.0.0-dev sentinel to undefined, letting downstream callers treat unversioned binaries uniformly. Threads the resolved version through withStagedClerkCliSkill so every bundled asset has {{CLI_VERSION}} substituted at install time. The install caller uses resolveCliVersion() instead of an inline typeof guard.

Import DEV_CLI_VERSION from packages/cli-core/src/lib/version.ts in scripts/build.ts so the build script's default version arg stays in lockstep with the sentinel used by the skill installer. Also extend scripts/tsconfig.json to include globals.d.ts so CLI_VERSION is in scope when tsc follows the cross-package import.

Remove the PackageManager type re-export from bootstrap-registry and update consumers (bootstrap.ts, context.ts, index.ts) to import the type directly from lib/package-manager.ts.

Adds init, apps create, open, completion, and skill install to the Core commands table; adds --destructive to config patch/put; clarifies config put semantics. Strengthens the Prerequisites section to make 'clerk doctor --json' the mandatory session-start check, with a note to rerun 'clerk skill install' after upgrading the CLI so the bundled skill matches the new binary. Adds agent-mode behavior rows for 'apps create' (requires explicit --json) and 'clerk open' (emits a JSON descriptor instead of launching a browser), plus matching entries in the structured-outputs table. Calls out 'clerk <command> --help' as the source of truth for flags so the skill stays a hint rather than a spec, reducing drift surface. Hidden commands (deploy, switch-env) remain undocumented.

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.

The bundled clerk skill drifted from the CLI source in a few places. This commit resyncs the command reference and agent-mode docs: - `clerk init`: document `--app` (skips interactive picker) - `clerk config patch`/`put`: document `--app` and `--instance` - Add `clerk update` row to the core commands table - `references/agent-mode.md`: document the structured JSON error output (`{"error":{...}}` on stderr) that agent mode emits, split error-format guidance into human vs agent columns - SKILL.md: expand the `clerk doctor --json` shape to include `detail` and `fix` alongside `remedy`

Correct documentation drift identified by skill audit: - OpenAPI catalog cache TTL is 1 hour, not 24 hours (matches CACHE_TTL_MS in packages/cli-core/src/lib/constants.ts). - `apps create` auto-emits JSON in agent mode via the shared printJson() helper, same as `apps list`; update agent-mode matrix and SKILL.md bullet so agents don't unnecessarily add --json.

Pull the accurate, CLI-verified additions from the external clerk-cli skill draft into the bundled clerk skill: - Document auth aliases: signup/signin/sign-in, signout/sign-out, and the top-level clerk login / clerk logout shortcuts. - Explain --destructive on config patch (same semantics as on config put). - Note that config commands authenticate via the Platform API and do not accept --secret-key. - Add a mapping from each failing clerk doctor check to the manual remediation command (auth login / link / env pull), since doctor --fix is disabled in agent mode. PR #29 items skipped because they drift from the current CLI source: the {checks, overall} doctor JSON wrapper (actual output is a flat array) and doctor --fix working in agent mode (source gates it on isHuman()). Co-authored-by: Rafael Thayto <rafa.thayto@gmail.com>

Replace hardcoded ~/.clerk/config.json and ~/.clerk/cache/ paths with platform-agnostic guidance since constants.ts uses envPaths (XDG). Add CLERK_CONFIG_DIR to the environment variables table.

- Remove "clerk" from BASE_SKILLS so the upstream clerk/skills install no longer overwrites the bundled pinned skill - Import DEV_CLI_VERSION in update-check.ts to eliminate duplicate sentinel - Move detectPackageManager to lib/package-manager; re-export from context - Expand version substitution tests to cover all 4 bundled skill files

…mpt fallback

wyattjoh · 2026-04-07T18:41:39Z