orca/notes/skill-guide-indirection-design.md

# Skill Guide Indirection (Thin Stubs + `orca skills get`)

Status: FOLDED INTO `skill-freshness-design.md` (2026-07-13) — read that instead. The stub/CLI
contract and prior-art survey carried over; the migration-via-in-app-updater section here is
superseded (migration now rides `npx skills update`, no in-app writes).

## Principle

Version-sensitive content must not live in distributed files; only discovery metadata should.
Every hard problem in the current system — staleness, adoption consent, installer attribution,
transactional replacement, remote-host reconciliation — descends from shipping full skill
bodies as mutable files that must track the installed Orca binary. Move the bodies into the
binary and the problems shrink to a residue the existing machinery already handles.

## Design

### 1. The binary serves the instructions

New CLI surface (topic names match skill names):

```sh
orca skills list                 # enumerate available guides, one line each
orca skills get <topic>          # full version-matched guide for one skill, markdown to stdout
orca skills get <topic> --full   # include bundled reference docs, if any
```

- Content is authored in `skill-guides/<topic>.md`. A generator embeds those authoritative
  sources in the CLI and emits `skills/<name>/SKILL.md` as an installable projection;
  `skills/` is generated output, not an authoring source.
- Output contract: plain markdown on stdout, exit 0; unknown topic exits nonzero with the
  topic list. No network, no filesystem reads outside the binary's own resources.
- Verb choice: `skills get` (not `guide`) to match the convention agents are already being
  taught by other tools (see Prior art).

### 2. Historical stub sketch (superseded; do not copy)

This sketch records the indirection idea only. The resolver and first-generation hybrid stub
contract in `skill-freshness-design.md` are authoritative and must cover packaged `orca`,
Linux/WSL `orca-ide`, SSH `orca`, and development `orca-dev` without blindly invoking bare
`orca` on Linux.

```markdown
---
name: orca-cli
description: <unchanged per-skill trigger copy — this is the discovery surface>
allowed-tools: <all supported Orca CLI command names>
---

# Orca CLI

This file is a discovery stub, not the usage guide. The full, version-matched reference
lives in the `orca` binary itself.

Before using Orca commands, resolve the CLI for this session and load the guide once:

    <resolved-orca-cli> skills get orca-cli

Don't guess subcommands or flags from memory or from cached copies of this skill — they
change between Orca releases; the command above always matches the installed binary.
```

Stub rules:
- Body is deliberately version-independent: it says when to engage Orca and where to fetch
  the how — never the how itself. A stub should survive many releases unchanged.
- `allowed-tools` must cover every executable that the authoritative resolver can select.
- Stub must not ship before the binary that serves its topic: gate stub rollout on the
  release that includes `skills get` (a stub pointing at a command that does not exist
  is worse than a fat skill). Enforce with a build check: every stub topic must resolve
  against the compiled guide table.
- Stub should degrade honestly when no supported Orca command is on PATH and must retain a
  bounded legacy bootstrap for binaries that predate `skills get`.

### 3. What this retires, what it keeps

Retired / collapsed:
- The ownership ledger, adoption and installer-attribution flows, background updater,
  transactional publish/rollback/orphan sweep, and all automatic writes into user-owned
  skill directories.
- Phases 3–4 of skill-auto-update-design.md (WSL/SSH remote file reconcilers). Wherever the
  skill is useful the `orca` binary is present, and the remote binary serves the guide
  matching its own host's version. No remote file-sync problem remains.

Kept (read-only):
- Bounded discovery, LF-normalized content identities, the released-snapshot registry,
  release mapping, and CI gates. Statuses are `current`, `outdated`, `newer-known`,
  `unrecognized`, and `inaccessible`; no ledger is needed to compute them.
- Name-scoped eligibility across every placement. One newer, unrecognized, external,
  read-only, repo-scoped, plugin, or inaccessible placement poisons the update offer for
  that skill name.
- The skills-CLI round-trip CI, extended to prove historical fat installs migrate to stubs
  through targeted global updates across supported hosts and topologies.
- Read-only settings rows and a dismissible nudge that pre-fill a targeted
  `npx skills update <eligible-names...> --global` command. Orca never submits it or writes
  into a skill directory.

## Prior art (verified live 2026-07-13)

- vercel-labs/agent-browser — canonical stub + `agent-browser skills get core`; docs frame
  it explicitly: "the installed SKILL.md rarely changes, while the CLI always serves content
  matching its own version." Stub self-describes as a discovery stub that "cannot change
  between releases."
- Canner/WrenAI (skills/wren/SKILL.md) — independent (non-Vercel) adopter: "The actual
  workflow guides … live inside the `wren` CLI itself, so they always match the installed
  wrenai version (no skill cache, no version drift)." Uses `wren skills list` /
  `wren skills get <topic>` / `--full` — the verb convention to match.
- vercel-labs/zerolang (skills/zero/SKILL.md) — "This file is only a discovery stub… ask the
  installed compiler for the skill content that matches that exact binary." Adds the nuance
  of warning agents not to replace a pinned binary.
- vercel/next.js (skills/next-dev-loop/SKILL.md) — consumes the pattern: instructs agents to
  "run `agent-browser skills get core` once for the version-matched usage guide — don't
  guess subcommands from memory." Normalization signal.
- Ecosystem discourse (Snyk threat model, HN, vercel-labs/skills issues #500/#542, Anthropic
  skill-trust guidance) demands pinning + reviewable updates and condemns silent pulls from
  mutable remotes. Stub indirection satisfies the audit-once trust model: the audited file
  never changes meaning; served content is exactly as trusted as the installed binary.

## Migration plan

0. Release `orca skills list/get` first from authoritative `skill-guides/` sources while
   distributed skills remain fat. No stub may reach repository main before a public binary
   can serve it.
1. Add read-only freshness detection, name-scoped update eligibility, the targeted
   user-invoked `npx skills update <names...> --global` action, and migration-rail CI. Keep
   distributed skills fat.
2. Spike pointer compliance against the released guide-serving binary with Claude Code and
   Codex, including Linux/WSL/SSH/dev command resolution, old-binary fallback, task success,
   and token cost.
3. Convert only `orca-cli` to a first-generation hybrid stub. Existing exact official fat
   copies become eligible for the targeted ecosystem update rail; users who ignore the
   nudge retain their existing skills.
4. Cut an RC, measure the gates, and thin the hybrid only if it passes. Convert remaining
   skills gradually in later PRs.

## Open questions

- Compliance failure mode: if agents skim the stub and skip the fetch, options are stronger
  stub wording, frontmatter `description` nudging ("requires running orca skills get"),
  or hybrid stubs carrying a minimal command table plus the pointer. Spike decides.
- Multi-file skills: current shipped packages are single-file; if a future skill needs
  scripts/assets, decide whether the binary serves them (`--script <name>` like WrenAI) or
  they stay in the package (then that skill keeps the fat-update path).
- Topic/verb naming: `orca skills get` collides conceptually with the `skills` installer
  CLI; confirm no confusion in agent behavior during the spike.
- Old binaries: a user can hold a stub while running an older orca without `skills get`
  (downgrade case). Stub wording should fail gracefully ("if the command is missing, update
  Orca"); acceptable residual.
- Whether settings should surface "guide served by binary" as a distinct row state so
  support can tell stub-era installs from fat-era ones at a glance.