fix(cli): accept Orca agent ids in skills install --agent

[bbingz]

ELI5

orca skills install --agent claude now installs into Claude Code instead of failing. Orca calls Claude Code claude everywhere else, but the outside skills tool it runs only knows the name claude-code. Orca already had a translation table for this. It just wasn't used for names you type yourself.

What Changed

Before, the reporter of #20831 saw this:

$ orca skills install --skill orca-cli --skill orchestration --agent claude
Running: npx --yes skills add https://github.com/stablyai/orca --skill orca-cli --skill orchestration --global --agent claude -y
...
■  Invalid agents: claude

After, the same command runs ... --global --agent claude-code -y and the install goes through. --dry-run shows the translated name too.

Mechanism. src/shared/skills-cli-agent-keys.ts already maps Orca's agent ids to the skills CLI's names (claude → claude-code, gemini → gemini-cli, copilot → github-copilot, rovo → rovodev, and so on). Until now that map was applied only to agents Orca detects on the host. A value passed with --agent only got a shape check and went through unchanged. A new toRequestedSkillsCliAgentKey sends a typed value through the same map when it is an Orca agent id. resolveInstallAgentKeys calls it on each comma-separated value before de-duplicating, so claude,claude-code becomes a single claude-code.

Unchanged:

• Values Orca doesn't know, such as universal, * or inference-sh, pass through. The skills CLI still judges them, as the existing comment intends.
• Orca ids that map to no skills key, such as aider or omp, also pass through. The CLI still rejects them loudly, as it does today.
• The shape check that blocks values like -y still runs, now after translation.

Deliberate exception: trae. Orca maps its detected trae agent to trae-cn, because Orca detects it through a binary only TRAE CN ships. But trae is also the skills CLI's own key for TRAE international, according to the valid-key list pinned in skills-cli-agent-keys.test.ts. If Orca rewrote a typed --agent trae to trae-cn, it would silently install into the wrong product. So a typed trae keeps its skills CLI meaning. It is the only Orca id that is also a different valid skills key. A new test checks every entry of the map against the pinned list, so a future collision fails CI instead of slipping through.

Why

The issue already names the cause and the fix: the map exists and is applied a few lines away on the detection path. Reusing it keeps one source of truth instead of adding a second alias table. I considered two alternatives. Rejecting Orca ids with a "did you mean claude-code?" error would still fail the most common command. Translating every known id blindly would hijack an explicit --agent trae.

Linked Issue

Fixes #20831

Visual Proof

N/A. This is a CLI argument fix with no UI or interaction change. The before and after argv are quoted above and pinned by the tests.

Testing

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

The existing handler test for an explicit --agent list now passes codex, claude-code ,codex,claude,trae. It asserts that the spawned argv contains codex, claude-code and trae in that order. A new shared test checks the translation of every Orca agent id against the pinned skills-CLI key list and checks that unknown values pass through. Both tests fail without the fix and pass with it. I tested on macOS only. The change is pure string mapping with no path, shell or platform branches.

• vitest run src/cli/skills.test.ts src/shared/skills-cli-agent-keys.test.ts src/shared/agent-feature-install-commands.test.ts: 3 files, 69 tests passed.
• tsc --noEmit -p config/tsconfig.tc.cli.json (typecheck:cli): clean.
• tsc --noEmit -p config/tsconfig.node.json (typecheck:node): clean.
• oxlint and oxfmt --check on the 4 changed files: clean.

AI Disclosure

Implemented with Claude (Anthropic) as a coding agent. Reviewed by OpenAI Codex (codex exec, read-only).

Review

Codex reviewed the commit read-only and reported no actionable findings. It specifically checked these points:

• Translation table: trae is the only conflict between the map and the pinned valid-key set. Unknown and null-mapped values pass through.
• Validation and dedupe: translation runs before de-duplication and keeps first-seen order. It does not bypass the shape check or change *.
• Imports: the new import of isTuiAgent from tui-agent-config adds no import cycle and no browser-incompatible dependency.
• Tests: they pin the full-table translation and the real spawned argv.

Compatibility notes:

• Cross-platform: this is string mapping only, with no paths, shells or process spawning changed.
• SSH/remote: orca skills install still refuses to run through a forwarded shell, and that path is untouched.
• Agents: only typed --agent values that are Orca ids change meaning, and each maps to the key Orca already uses for that agent on detection.
• Performance and security: this is one object lookup per value, and the shape check against flag-like values still runs.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

The change reuses Orca's existing agent-key map and its already-pinned list of valid skills-CLI keys. It adds no upstream material.

Notes

Ensure no issues in: Security, Cross-platoform support (Linux, Windows, Mac), Remote SSH, Mobile, general backwards compatibility, performance

Backwards compatibility: a typed --agent that already worked, meaning a skills-CLI key, behaves exactly as before. The only values whose output changes are Orca ids that the skills CLI rejected outright. Mobile is not affected.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6e37eb38-23b9-4ddb-88ca-3e12c9a90438

📥 Commits

Reviewing files that changed from the base of the PR and between 5cafefe and 43431de.

📒 Files selected for processing (4)

• src/cli/handlers/skills.ts
• src/cli/skills.test.ts
• src/shared/skills-cli-agent-keys.test.ts
• src/shared/skills-cli-agent-keys.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The skills install handler now converts explicit --agent values to requested skills CLI keys before deduplication. The conversion maps recognized agent IDs when a mapping exists and preserves passthrough values, including trae. Tests cover the conversion, deduplicated install targets, and the behavior when explicit agents are provided.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 43431

Explicit agent IDs map to install targets without redirecting accepted CLI keys. No concrete issue blocks merging after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely states the main change: accepting Orca agent IDs in the skills install command.
Description check	✅ Passed	The description is thorough and follows the template. It explains the user impact, implementation, rationale, linked issue, testing, and compatibility considerations. The full pnpm lint, typecheck, te…
Linked Issues check	✅ Passed	Issue [#20831] asks orca skills install --agent to translate known Orca agent IDs and leave values Orca cannot map to the skills CLI. toRequestedSkillsCliAgentKey applies the existing map, preserv…
Out of Scope Changes check	✅ Passed	The changed handler and shared mapper implement issue [#20831]. The accompanying tests verify the translation and install behavior. No unrelated changes appear in the reviewed diff.

• Fix all pre-merge checks with AI

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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