fix(install): expose Ring skills as opencode slash commands

[alexgarzao]

Summary

• Ring skills now appear in opencode's TUI / slash-command autocomplete as /ring:<skill-name> (e.g. /ring:codereview, /ring:dev-cycle, /ring:commit).
• Build pipeline generates a per-skill slash-command shim into .ring-build/opencode/command/<team>/<skill>.md; real command files (today only dev-team/commands/dev-license.md) keep precedence — shims never overwrite.
• New --emit-opencode-skill-shim mode added to scripts/_codex_frontmatter.py (stdlib-only, reuses the existing frontmatter parser).

Why

When the user types / in the opencode TUI, only /ring:dev-license shows up among Ring entries — the other 69 skills are missing. Tracing it down:

packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:

for (const serverCommand of sync.data.command) {
  if (serverCommand.source === "skill") continue   // <-- filtered out
  ...
}

The TUI explicitly drops every command whose source is "skill". Skills are still loaded by the runtime (Skill.Service.all() works, and the agent can invoke them via the Skill tool), but they never surface to the / autocomplete. Only files placed under command/ or commands/ register with source: "command" and pass the filter.

Before this fix, the Ring repo had a single commands/ file (dev-team/commands/dev-license.md), so /ring:dev-license was the only Ring command visible to opencode users. Verified live against http://127.0.0.1:9876/command:

State	source=command (visible in /)	source=skill (hidden)
Before	1 ring entry	94 ring entries
After	70 ring entries	23 ring entries*

* the 23 remaining source=skill entries are from ~/.claude/skills/ (opencode also scans Claude Code's external skills dir) — these are leftovers from older Ring installs and are outside this fix's scope.

The shim approach mirrors what other plugins (e.g. Optimus) do to expose their skills to opencode — a minimal .md that delegates back to the skill tool.

Implementation

scripts/_codex_frontmatter.py — adds --emit-opencode-skill-shim mode:

• Reads the source SKILL.md, extracts name and description from frontmatter (reuses _extract_description so multi-line block scalars collapse correctly).
• Writes a shim like:

  ---
  name: ring:codereview
  description: Gate 8 of development cycle - dispatches 10 specialized reviewers ...
  ---
  
  Invoke the `ring:codereview` skill via the Skill tool. Arguments: $ARGUMENTS

• Stdlib-only, atomic write via tmp + os.replace.

install-symlinks.sh — adds build_make_opencode_skill_commands():

• Iterates $RING_DIR/<team>/skills/*/SKILL.md, skipping shared-patterns.
• Skips destinations that already exist (so build_copy_opencode_commands runs first and keeps precedence for real commands).
• Honors DRY_RUN and vlog.
• Called once per team inside do_build() right after build_copy_opencode_commands.

Coupling is tight: bash invokes the Python helper per skill. Single atomic commit because splitting would land a helper flag that nothing calls, then a bash function whose runtime dependency is in the previous commit.

Test plan

• bash install-symlinks.sh build produces .ring-build/opencode/command/ with 70 files (1 real dev-license.md + 69 shimmed skills).
• wc -l .ring-build/opencode/command/dev-team/dev-license.md still matches the source (102 lines) — real command file unmodified by the shim pass.
• Sample shim content verified for: single-line description (commit), multi-line block scalar (codereview), folded YAML (pre-dev-research).
• bash install-symlinks.sh doctor --opencode reports all opencode targets PASS.
• Live verification via curl http://127.0.0.1:9876/command after opencode serve boot: 70 Ring entries with source: "command" (was 1).
• Open TUI, type /ring: — confirm /ring:codereview, /ring:dev-cycle, /ring:commit etc. appear in autocomplete.
• Invoke /ring:codereview and confirm the shim template delegates to the skill via the Skill tool.

Out of scope

• The 23 source=skill Ring entries that remain visible to the opencode runtime come from ~/.claude/skills/ (opencode scans Claude Code's external skill dir). These are stale skills from older Ring installs in that directory, not from this repo. Cleaning them up is a separate housekeeping task.
• Codex output unchanged — this fix only touches the opencode build path.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: de8430c8-be3e-4af9-a77c-9c15207f58b5

📥 Commits

Reviewing files that changed from the base of the PR and between 79d0953 and 3284ada.

📒 Files selected for processing (2)

• install-symlinks.sh
• scripts/_codex_frontmatter.py

---

Walkthrough

This PR adds infrastructure to generate Opencode command shims from Ring skills. A new Python CLI mode reads skill frontmatter, validates required fields, and writes minimal shims containing name, description, and an invocation line. A corresponding shell helper iterates per-team skill folders and generates shims during the ring build process, respecting --dry-run and avoiding overwrites.

Changes

Opencode Skill Command Shim Generation

Layer / File(s)	Summary
Python CLI mode for skill shim generation scripts/_codex_frontmatter.py	New --emit-opencode-skill-shim CLI flag and emit_opencode_skill_shim function read source skill frontmatter, validate the required name field, derive description using existing normalization logic, and emit a minimal frontmatter-only shim with name, description, and a single invocation line for calling the skill via the Skill tool.
Build script integration install-symlinks.sh	New build_make_opencode_skill_commands helper iterates per-team skill folders, generates destination shim files from each SKILL.md via the Python CLI, skips shared-patterns and missing SKILL.md, avoids overwriting real commands, and honors --dry-run. The helper is integrated into the .ring-build per-team build loop alongside existing agent/skill/command copying.

---

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