Keep skills CLI independent of provider startup

Skills management commands need to work when provider configuration is broken, because they are local/script-friendly maintenance commands. Route skills subcommands before provider profile hydration and validation, including supported leading global flags such as --bare.

Constraint: Provider startup validation must still run for normal interactive and provider-backed commands.

Rejected: Import full main.tsx for the skills fast path | that loads optional bundled Chrome modules and re-couples the local skills path to interactive startup.

Confidence: high

Scope-risk: narrow

Tested: bun test src/entrypoints/cli.skills.test.ts src/cli/handlers/skills.test.ts src/skills/loadSkillsDir.test.ts src/commands.test.ts

Tested: bun run build

Tested: CLAUDE_CODE_USE_OPENAI=1 OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY= node dist/cli.mjs skills list

Tested: CLAUDE_CODE_USE_OPENAI=1 OPENAI_BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY= node dist/cli.mjs --bare skills list

Tested: bun run smoke

Tested: git diff --check

Author: anandh8x

src/cli/handlers/skills.ts

@@ -10,7 +10,6 @@ import {
   getCommands,
   type Command,
 } from '../../commands.js'
-import { initBundledSkills } from '../../skills/bundled/index.js'
 import { getCwd } from '../../utils/cwd.js'
 import { getDisplayPath } from '../../utils/file.js'
 import { parseFrontmatter } from '../../utils/frontmatterParser.js'
@@ -47,7 +46,6 @@ function isSkillCommand(cmd: Command): cmd is SkillCommand {
 }
 
 function loadSkills(): Promise<SkillCommand[]> {
-  initBundledSkills()
   return getCommands(getCwd()).then(commands => commands.filter(isSkillCommand))
 }
 

src/cli/handlers/skillsCli.ts

@@ -0,0 +1,125 @@
+type SkillsCliOptions = {
+  force?: boolean
+  global?: boolean
+  help?: boolean
+  json?: boolean
+  registry?: string
+}
+
+const SKILLS_HELP = `Usage: openclaude skills <command> [options]
+
+Commands:
+  list [--json]                    List installed skills
+  show <name>                      Show details for an installed skill
+  validate <path>                  Validate a local skill directory
+  install <idOrUrlOrPath> [options] Install a skill
+  remove <name> [--global]         Remove an installed skill`
+
+function parseSkillsCliArgs(args: string[]): {
+  options: SkillsCliOptions
+  positionals: string[]
+  error?: string
+} {
+  const options: SkillsCliOptions = {}
+  const positionals: string[] = []
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--json') {
+      options.json = true
+    } else if (arg === '--global') {
+      options.global = true
+    } else if (arg === '--force') {
+      options.force = true
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true
+    } else if (arg === '--registry') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        return { options, positionals, error: '--registry requires a value.' }
+      }
+      options.registry = value
+      index += 1
+    } else if (arg?.startsWith('--registry=')) {
+      const value = arg.slice('--registry='.length)
+      if (!value) {
+        return { options, positionals, error: '--registry requires a value.' }
+      }
+      options.registry = value
+    } else if (arg?.startsWith('--')) {
+      return { options, positionals, error: `Unknown skills option: ${arg}` }
+    } else if (arg) {
+      positionals.push(arg)
+    }
+  }
+
+  return { options, positionals }
+}
+
+export async function runSkillsCli(args: string[]): Promise<void> {
+  const subcommand = args[1] ?? 'list'
+  const { options, positionals, error } = parseSkillsCliArgs(args.slice(2))
+  if (error) {
+    console.error(error)
+    process.exit(1)
+  }
+  if (subcommand === '--help' || subcommand === '-h' || options.help) {
+    console.log(SKILLS_HELP)
+    process.exit(0)
+  }
+
+  const {
+    skillsInstallHandler,
+    skillsListHandler,
+    skillsRemoveHandler,
+    skillsShowHandler,
+    skillsValidateHandler,
+  } = await import('./skills.js')
+
+  switch (subcommand) {
+    case 'list':
+      await skillsListHandler({ json: options.json })
+      break
+    case 'show': {
+      const name = positionals[0]
+      if (!name) {
+        console.error('Skill name is required.')
+        process.exit(1)
+      }
+      await skillsShowHandler(name)
+      break
+    }
+    case 'validate': {
+      const path = positionals[0]
+      if (!path) {
+        console.error('Skill path is required.')
+        process.exit(1)
+      }
+      await skillsValidateHandler(path)
+      break
+    }
+    case 'install': {
+      const idOrUrlOrPath = positionals[0]
+      if (!idOrUrlOrPath) {
+        console.error('Skill ID, URL, or path is required.')
+        process.exit(1)
+      }
+      await skillsInstallHandler(idOrUrlOrPath, options)
+      break
+    }
+    case 'remove': {
+      const name = positionals[0]
+      if (!name) {
+        console.error('Skill name is required.')
+        process.exit(1)
+      }
+      await skillsRemoveHandler(name, { global: options.global })
+      break
+    }
+    default:
+      console.error(`Unknown skills command: ${subcommand}`)
+      process.exit(1)
+  }
+
+  process.exit(process.exitCode ?? 0)
+}

src/entrypoints/cli.skills.test.ts

@@ -0,0 +1,70 @@
+import { expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync } from 'fs'
+import { tmpdir } from 'os'
+import { join, resolve } from 'path'
+
+const repoRoot = resolve(import.meta.dir, '..', '..')
+const cliEntrypoint = join(repoRoot, 'src', 'entrypoints', 'cli.tsx')
+
+async function readStream(stream: ReadableStream<Uint8Array>): Promise<string> {
+  return new Response(stream).text()
+}
+
+async function runSkillsList(args: string[]): Promise<{
+  exitCode: number
+  stderr: string
+  stdout: string
+}> {
+  const root = mkdtempSync(join(tmpdir(), 'openclaude-skills-cli-'))
+  const projectDir = join(root, 'project')
+  const homeDir = join(root, 'home')
+  const configDir = join(root, 'config')
+  mkdirSync(projectDir)
+  mkdirSync(homeDir)
+
+  const proc = Bun.spawn({
+    cmd: [process.execPath, cliEntrypoint, ...args],
+    cwd: projectDir,
+    env: {
+      ...process.env,
+      CLAUDE_CODE_USE_OPENAI: '1',
+      OPENAI_BASE_URL: 'https://api.openai.com/v1',
+      OPENAI_API_KEY: '',
+      CLAUDE_CONFIG_DIR: configDir,
+      HOME: homeDir,
+      OPENCLAUDE_DISABLE_EARLY_INPUT: '1',
+    },
+    stderr: 'pipe',
+    stdout: 'pipe',
+  })
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    readStream(proc.stdout),
+    readStream(proc.stderr),
+    proc.exited,
+  ])
+
+  return { exitCode, stderr, stdout }
+}
+
+test('skills list bypasses provider startup validation', async () => {
+  const { exitCode, stderr, stdout } = await runSkillsList(['skills', 'list'])
+
+  expect(exitCode).toBe(0)
+  expect(stdout).toContain('Skills: 0 enabled')
+  expect(stdout).toContain('No installed skills found.')
+  expect(stderr).not.toContain('OPENAI_API_KEY is required')
+})
+
+test('skills list bypasses provider startup validation after --bare', async () => {
+  const { exitCode, stderr, stdout } = await runSkillsList([
+    '--bare',
+    'skills',
+    'list',
+  ])
+
+  expect(exitCode).toBe(0)
+  expect(stdout).toContain('Skills: 0 enabled')
+  expect(stdout).toContain('No installed skills found.')
+  expect(stderr).not.toContain('OPENAI_API_KEY is required')
+})

src/entrypoints/cli.tsx

@@ -47,6 +47,50 @@ process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS ??= 'true'
 // eslint-disable-next-line custom-rules/no-top-level-side-effects
 process.env.COREPACK_ENABLE_AUTO_PIN = '0';
 
+const SKILLS_LEADING_BOOLEAN_FLAGS = new Set([
+  '--bare',
+  '--debug',
+  '--debug-to-stderr',
+  '--mcp-debug',
+  '--verbose',
+])
+
+const SKILLS_LEADING_VALUE_FLAGS = new Set([
+  '--debug-file',
+  '--model',
+  '--provider',
+])
+
+function getSkillsCliArgs(args: string[]): string[] | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === 'skills') {
+      return args.slice(index)
+    }
+    if (SKILLS_LEADING_BOOLEAN_FLAGS.has(arg)) {
+      continue
+    }
+    if (
+      SKILLS_LEADING_VALUE_FLAGS.has(arg) &&
+      args[index + 1] &&
+      !args[index + 1]!.startsWith('-')
+    ) {
+      index += 1
+      continue
+    }
+    if (
+      Array.from(SKILLS_LEADING_VALUE_FLAGS).some(flag =>
+        arg?.startsWith(`${flag}=`),
+      )
+    ) {
+      continue
+    }
+    return undefined
+  }
+
+  return undefined
+}
+
 // Set max heap size for child processes in CCR environments (containers have 16GB)
 // eslint-disable-next-line custom-rules/no-top-level-side-effects, custom-rules/no-process-env-top-level, custom-rules/safe-env-boolean-check
 if (process.env.CLAUDE_CODE_REMOTE === 'true') {
@@ -108,6 +152,16 @@ async function main(): Promise<void> {
     applySafeConfigEnvironmentVariables()
   }
 
+  // Local skills management must stay available even when provider startup
+  // configuration is broken, so users can inspect/fix skills from scripts.
+  const skillsCliArgs = getSkillsCliArgs(args)
+  if (skillsCliArgs) {
+    const { runSkillsCli } = await import('../cli/handlers/skillsCli.js')
+    process.argv = [process.argv[0]!, process.argv[1]!, ...skillsCliArgs]
+    await runSkillsCli(skillsCliArgs);
+    return
+  }
+
   const hasConfiguredProviderProfile = await (async () => {
     const { getActiveProviderProfile } = await import('../utils/providerProfiles.js')
     return getActiveProviderProfile() !== undefined