OpenCode: dot-namespaced skills aren't auto-loaded — bridge via generated command shims

[devrimcavusoglu]

Summary

OpenCode is already a supported install target (internal/platform/spec.go → TypeOpenCode; project dir .opencode/skills/, user dir ~/.config/opencode/skills/). However, field testing of skill/command chains on OpenCode surfaced a loader limitation that breaks dot-namespaced skills — the exact naming style skern began allowing in #92.

This issue tracks hardening OpenCode support so namespaced skills installed by skern actually auto-load on OpenCode.

Background

• skern installs a skill to OpenCode by copying the skill directory into .opencode/skills/<name>/ (or the user-level equivalent). Adapters are pure copiers today (AGENTS.md design decision CLI Autocompletion #3 — "Platform adapters are copiers").
• Since feat: support dot-namespaced skill names (e.g. myorg.bootstrap) #92, skern accepts dot-namespaced skill names (validated by ^[a-z0-9]+([.-][a-z0-9]+)*$), e.g. myorg.bootstrap. This enables phase-chained skills like aura.bootstrap, aura.<phase>, …

Caveat found in the field

While exercising skills/commands on OpenCode:

OpenCode auto-reads both [skills and commands]. The one catch I found and solved: OpenCode's skill loader rejects dot-named skills (aura.bootstrap…), so the phase chain isn't auto-loaded. But OpenCode commands accept dotted names, so the bridge is a generated .opencode/command/aura.<phase>.md shim per phase that makes the model open + follow the real skill file.

In other words:

• OpenCode skills loader → rejects dot-named skills → a dot-namespaced skill copied into .opencode/skills/ is silently not auto-loaded.
• OpenCode commands → do accept dotted names → a .opencode/command/<name>.md command can act as a shim that points the model at the real SKILL.md and tells it to open + follow it.

Why it matters

#92 made dot-namespaced names first-class in skern, but on OpenCode those are precisely the skills that fail to auto-load. So "OpenCode support" works for flat names yet quietly breaks for the namespaced names skern itself encourages. The two features collide at the OpenCode boundary, and the failure is silent (no error — the skill just never loads).

Proposed approach

When installing to OpenCode, additionally generate a command shim for each dot-namespaced skill:

• For skill <name> containing a dot, write .opencode/command/<name>.md (user/project scope mirroring the skills dir).
• The shim instructs the model to open and follow the corresponding .opencode/skills/<name>/SKILL.md.
• Flat (non-dotted) names load fine as skills and need no shim.

Open questions / discussion

• This would be the first adapter behavior that is not a pure copy (departs from design decision CLI Autocompletion #3). Special-case it inside the OpenCode adapter, or introduce a general "post-install hook" / "companion file" concept on Spec?
• Scope: generate shims only for dot-named skills, or for every skill on OpenCode?
• Uninstall must also remove any generated shim(s) — keep skills dir and command dir in sync.
• Confirm current OpenCode loader behavior before implementing (OpenCode moves fast) and link the relevant OpenCode docs/source — the above is an empirical field finding, not a verified spec.
• Shim content/template: minimal "open + follow" instruction vs. richer passthrough.

Acceptance criteria (draft)

• Installing a dot-namespaced skill to OpenCode produces a working command shim so the skill is reachable.
• Uninstalling removes both the skill dir and the shim.
• OpenCode platform behavior is documented (AGENTS.md + docs site).

---

Filed from a field report while testing skills/commands on OpenCode. Related: #92 (dot-namespaced names), #80 (platform expansion).