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.

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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 61a2b63

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 95c37677-a5ff-44c4-993f-eafe22b41639

📥 Commits

Reviewing files that changed from the base of the PR and between 9c7d911 and 61a2b63.

📒 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

✅ Files skipped from review due to trivial changes (11)

• .changeset/clerk-skill.md
• scripts/tsconfig.json
• packages/cli-core/src/commands/init/index.ts
• packages/cli-core/src/lib/package-manager.ts
• packages/cli-core/src/lib/version.ts
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/init/README.md
• packages/cli-core/src/commands/init/bootstrap.ts
• skills/clerk/references/auth.md
• packages/cli-core/src/commands/skill/README.md
• skills/clerk/references/recipes.md

🚧 Files skipped from review as they are similar to previous changes (4)

• scripts/build.ts
• packages/cli-core/src/commands/init/context.ts
• packages/cli-core/src/commands/init/frameworks/types.ts
• packages/cli-core/src/commands/init/bootstrap-registry.ts

---

📝 Walkthrough

Walkthrough

Adds a new top-level clerk skill install command that stages the bundled Clerk skill assets, resolves a package-runner, and delegates installation to the external skills CLI (interactive and unattended flows supported). Introduces centralized lib/package-manager.ts and lib/version.ts modules for package-manager enums and CLI version resolution. Refactors init to install the bundled Clerk skill separately from upstream framework-pattern skills, adds tests for skill staging/arg-building, and includes extensive Clerk skill documentation and README/CLI help updates.

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 pull request title 'feat: Clerk CLI Skill' clearly and concisely describes the main feature added in the changeset: bundling and integrating a clerk skill into the CLI binary.
Description check	✅ Passed	The pull request description is comprehensive and directly related to the changeset, explaining how the skill is bundled, pinned to CLI version, invokes the CLI, and maintains installer continuity.

_{✏️ 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.