Repository navigation
feat(skills): ship orca-cli as a first-generation hybrid stub - #9238
Merged
Merged
Conversation
Convert the installable orca-cli SKILL.md from a full fat guide into a hybrid discovery stub: a safe CLI resolver, an `orca skills get orca-cli` pointer, and a bounded read-only fallback for pre-guide binaries. The version-matched command reference now lives only in the Orca binary (embedded guide table, served by `orca skills get`), so the distributed file can no longer drift from the binary that runs the commands. - generator projects STUB_TOPICS from skill-stubs/<name>.md, reusing the guide's own frontmatter so the routing/description surface is unchanged; the embedded full guide (bundled-skill-guides.ts) is untouched. - manifest regenerated: orca-cli releaseRevision 32->33 as an append-only snapshot; existing fat installs classify `outdated` and get the targeted `npx skills update` nudge (no in-app writes). - tests: command-guidance assertions repointed to the guide source (their home now), plus stub-projection + safety coverage. Only orca-cli converts; the other skills stay fat. Per notes/skill-freshness-design.md, the E.3 pointer-compliance spike and the E.5 RC window remain before any further thinning. allowed-tools is intentionally not added yet (frontmatter kept byte-identical to the guide).
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
🚧 Files skipped from review as they are similar to previous changes (4)
📝 WalkthroughWalkthroughThe change adds an Orca CLI discovery stub and updates bundled skill generation to preserve canonical frontmatter while substituting stub content. Stub topics are validated, normalized, and covered by projection and CLI guidance tests, including line-ending checks. The Orca CLI guide now directs version-matched guide retrieval and bounded fallback commands. Manifest, release mapping, and snapshot metadata are refreshed for the generated artifact. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
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. Comment |
AmethystLiang
self-requested a review
July 18, 2026 16:47
brennanb2025
added a commit
that referenced
this pull request
Jul 20, 2026
…9607) * feat(skills): convert the remaining bundled skills to hybrid stubs Roll out the hybrid discovery-stub pattern (first shipped for orca-cli in #9238) to the other seven bundled skills: computer-use, linear-tickets, orca-emulator, orca-emulator-android, orca-linear, orca-per-workspace-env, and orchestration. Each installable SKILL.md becomes a thin stub — a safe CLI resolver, an `orca skills get <topic>` pointer, and a bounded read-only fallback for pre-guide binaries — while the version-matched command reference now lives only in the Orca binary (embedded guide table, served by `orca skills get`). The distributed files can no longer drift from the binary that runs the commands. - generator: STUB_TOPICS now lists all eight canonical topics; each stub body lives in skill-stubs/<topic>.md and the projection reuses the guide's own frontmatter, so every routing/description surface is byte-identical. The embedded full guides (bundled-skill-guides.ts) are untouched. - manifest regenerated: each converted skill's releaseRevision bumps +1 as an append-only snapshot (orca-cli stays at 33). Existing fat installs classify `outdated` and get the targeted `npx skills update` nudge with no in-app writes. - tests: command-guidance assertions for computer-use, orca-linear, and orchestration repointed to their guide sources (their home now), plus per-topic stub-projection + safety coverage. Per notes/skill-freshness-design.md this completes the fat->stub migration across all bundled skills. The E.3 pointer-compliance spike and E.5 RC window flagged on #9238 still apply; allowed-tools frontmatter is intentionally not added yet (frontmatter kept byte-identical to guides). * fix(skills): preserve useful hybrid fallbacks
enrick-dev
pushed a commit
to enrick-dev/orca
that referenced
this pull request
Oct 15, 2026
…ai#9238) * feat(skills): ship orca-cli as a first-generation hybrid stub Convert the installable orca-cli SKILL.md from a full fat guide into a hybrid discovery stub: a safe CLI resolver, an `orca skills get orca-cli` pointer, and a bounded read-only fallback for pre-guide binaries. The version-matched command reference now lives only in the Orca binary (embedded guide table, served by `orca skills get`), so the distributed file can no longer drift from the binary that runs the commands. - generator projects STUB_TOPICS from skill-stubs/<name>.md, reusing the guide's own frontmatter so the routing/description surface is unchanged; the embedded full guide (bundled-skill-guides.ts) is untouched. - manifest regenerated: orca-cli releaseRevision 32->33 as an append-only snapshot; existing fat installs classify `outdated` and get the targeted `npx skills update` nudge (no in-app writes). - tests: command-guidance assertions repointed to the guide source (their home now), plus stub-projection + safety coverage. Only orca-cli converts; the other skills stay fat. Per notes/skill-freshness-design.md, the E.3 pointer-compliance spike and the E.5 RC window remain before any further thinning. allowed-tools is intentionally not added yet (frontmatter kept byte-identical to the guide). * fix(skills): distinguish guide lookup failures * chore(skills): refresh released skill mapping
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Converts the
orca-cliskill's installableSKILL.mdfrom a full "fat" guide into a first-generation hybrid discovery stub, pernotes/skill-freshness-design.md§B/§E.4.The version-sensitive command reference now lives only in the Orca binary (the embedded guide table, served by
orca skills get orca-cli). The distributed skill file becomes a thin, safe pointer, so it can no longer drift from the binary that will actually run the commands — the root cause the thin-stub plan targets.Only
orca-cliconverts here; the other 7 skills stay fat.What changed
skill-stubs/orca-cli.md(new) — body-only hybrid stub: discovery-stub notice, the safe CLI resolver (ORCA_CLI_COMMAND → orca-dev → orca-ide → orca, never bareorcaon Linux/GNOME screen reader), theORCA skills get orca-clipointer, a "don't guess subcommands" warning, and a bounded read-only fallback for pre-guide binaries (so old Orca doesn't dead-end or invite guessing).config/scripts/generate-bundled-skill-guides.mjs— the generator now projectsSTUB_TOPICSfromskill-stubs/<name>.md, composingprojection = <guide frontmatter block> + <stub body>. The guide's frontmatter (name + description) is reused verbatim, so the routing/description surface is byte-identical. The embedded full guide (bundled-skill-guides.ts) is untouched.skills/orca-cli/SKILL.md— regenerated: 331 → 78 lines.resources/skills/current-manifest.json+snapshot-registry.json— regenerated:orca-clireleaseRevision32 → 33 as an append-only snapshot; new digest/size.release-mapping.jsonis byte-identical. Existing fat installs now classifyoutdatedand get the targetednpx skills updatenudge — no in-app writes..gitattributes— LF pin for/skill-stubs/*.md.orca-cli-skill-guidance.test.mjs: command-guidance assertions repointed to the guide source (their home now the projection is thin) + new stub safety coverage (resolver survives, no bareorca, old-binary fallback, frontmatter unchanged).generate-bundled-skill-guides.test.mjs: stub-projection coverage; fixtures copy/CRLFskill-stubs.Verification
verify:bundled-skill-guides+verify:skill-bundle-manifestgates pass.orca-cli-skill-guidance,src/cli/skills.test.ts.orca skills get orca-clistill prints the full guide from the embedded table;skills listshowsorca-cliwith its unchanged description; the on-disk file is the 73-line hybrid stub.Not in scope / gates still ahead (do not merge past these)
Per
skill-freshness-design.md:allowed-toolsfrontmatter — intentionally not added (frontmatter kept byte-identical to the guide). The plan sketches it; validating its exact form is better done in the spike than guessed here.Manual validation (pointer-compliance spike, demo-project)
Summary / result
Verdict: pass — hybrid stub is effective for real agents on this spike.
orca skills getSkill(orca-cli)); Codex loaded installedSKILL.mdwhen askedorcaon macOS with no env overrides (no wrong binary / no fallthrough)orca skills get orca-clibeforestatus/worktree/terminalstatus,worktree ps,terminal list; Claude alsoworktree current)worktree psJSON (display truncation in TUI); not a stub failureNot measured in this run: old-binary (
skills getunknown) failure path, token cost vs fat skill, Linux/WSL/SSH resolver paths, or a head-to-head fat-skill control.Ran real Claude Code and Codex against the hybrid stub install + production guide-serving
orcabinary. Worktrees lived only under demo-project (not the orca monorepo) and were removed after the run.Setup:
~/.agents/skills/orca-cli/SKILL.md(78-line discovery stub; fat skill backed up and restored after)orca(orca skills get orca-cli→ full ~331-line version-matched guide)orca worktree create --repo demo-project --agent {claude|codex} --prompt … --setup skip --no-parentClaude Code (Opus 4.6)
Skill(orca-cli)/ Skill tool (“Successfully loaded skill”)orca(macOS;ORCA_CLI_COMMAND/ORCA_DEV_REPO_ROOTunset)orca skills get orca-clifirststatus,worktree ps,worktree current,terminal list --worktree activeall OKCodex (gpt-5.6-sol high)
~/.agents/skills/orca-cli/SKILL.mdorca(Darwin; no env overrides)orca skills get orca-cliwas first Orca invocationstatus,worktree ps,terminal list --worktree activeall OKworktree psdisplay only; no missing commands / wrong binaryNotes
$orca-cli.