{"record":{"id":"76b754bbb7249c88","repo":"stablyai/orca","slug":"invalid-environment-76b754","errorCode":"invalid_environment","errorMessage":"No coding agent detected on this host, so there is no install target. Pass --agent <name>[,<name>...] to choose targets explicitly — --agent universal writes only the shared .agents/skills directory that Orca reads.","messagePattern":"No coding agent detected on this host, so there is no install target\\. Pass --agent <name>\\[,<name>\\.\\.\\.\\] to choose targets explicitly — --agent universal writes only the shared \\.agents/skills directory that Orca reads\\.","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/skills.ts","lineNumber":222,"sourceCode":"    if (unusable !== undefined) {\n      // Why: the skills CLI drops a value starting with `-`, which leaves it with\n      // no target and installs into every agent it knows.\n      throw new RuntimeClientError(\n        'invalid_argument',\n        `Invalid --agent value \"${unusable}\". Pass agent names such as claude-code, ` +\n          'codex, or universal.'\n      )\n    }\n    return keys\n  }\n  const detected = detectSkillsCliAgentKeys()\n  if (detected.length > 0) {\n    return detected\n  }\n  // Why: without --agent, `skills add -y` falls into its own zero-detected branch\n  // and installs into every agent it knows (~75), creating config directories for\n  // agents this host does not have. Say so instead.\n  throw new RuntimeClientError(\n    'invalid_environment',\n    'No coding agent detected on this host, so there is no install target. Pass ' +\n      '--agent <name>[,<name>...] to choose targets explicitly — --agent universal ' +\n      'writes only the shared .agents/skills directory that Orca reads.'\n  )\n}\n\nfunction buildNpxSkillsArgs(\n  verb: SkillMutationVerb,\n  skillNames: string[],\n  global: boolean,\n  agents: string[]\n): string[] {\n  const skillArgs =\n    verb === 'install'\n      ? buildAgentFeatureSkillInstallArgs(skillNames, { global, yes: true, agents })\n      : buildAgentFeatureSkillUpdateArgs(skillNames, { global, yes: true })\n  // Why: a cold package cache makes bare `npx` prompt before it will fetch","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/skills.ts#L204-L240","documentation":"Thrown with code `invalid_environment` (not invalid_argument) by resolveInstallAgentKeys when no coding agent was detected on the host AND the user did not pass `--agent`. Orca refuses to fall through to the skills CLI's default all-agents branch because that would create config directories for ~75 agents this machine does not have. The fix is to name a target explicitly, with `--agent universal` being the minimal choice that writes only the shared `.agents/skills` directory Orca itself reads.","triggerScenarios":"Running `orca skills install` (or update/add) on a machine where no known TUI coding agent is installed and `--agent` is omitted. Detection probes KNOWN_TUI_AGENT_DETECTION_COMMANDS in install dirs and finds nothing.","commonSituations":"Fresh machine/CI runner with Orca but no Claude Code/Codex/etc. installed; container where agent binaries aren't on PATH; SSH host whose agents live only on the client; headless server meant only to serve the shared skills dir.","solutions":["Pass `--agent universal` to write only the shared `.agents/skills` directory Orca reads.","Pass `--agent <name>` for a specific agent you intend to install on this host.","Install a supported coding agent on the host so detection succeeds, then re-run without `--agent`.","If this is the wrong machine entirely (e.g. an SSH-forwarded shell), see error 672."],"exampleFix":"// before\norca skills install              // no agent detected, no --agent\n// after\norca skills install --agent universal   // shared .agents/skills only\n// or target a real agent\norca skills install --agent claude-code","handlingStrategy":"fallback","validationCode":"import { detectSkillsCliAgentKeys } from '<skills>'\nconst detected = detectSkillsCliAgentKeys()\nif (detected.length === 0 && !flags.has('agent')) {\n  // provide --agent universal (or a concrete name) before invoking\n}","typeGuard":"function needsExplicitAgent(flags: Map<string, string | boolean>, detected: string[]): boolean {\n  return detected.length === 0 && !flags.has('agent')\n}","tryCatchPattern":"try { await runSkillsInstall(flags) }\ncatch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'invalid_environment' && e.message.startsWith('No coding agent detected')) {\n    // retry with --agent universal (shared dir) or install a supported agent first\n  } else throw e\n}","preventionTips":["On headless/CI hosts, always pass --agent universal unless a specific agent is intended.","Install at least one supported coding agent before relying on auto-detection.","Do not treat 'no detection' as 'install into everything' — Orca refuses on purpose."],"tags":["cli","validation","skills","invalid-environment","agent-detection","headless","ci"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}