Skill-name collision: opencode-sdlc-wizard's .opencode/skills are shadowed by sibling claude/codex .claude+.agents skills at runtime

[BaseInfinity]

Summary

When opencode-sdlc-wizard is installed alongside its siblings (claude-sdlc-wizard in .claude/, codex-sdlc-wizard in .codex/, plus .agents/skills/), OpenCode's native skill discovery loads the sibling copies, not the wizard's own .opencode/skills/ copies, for any same-named skill.

The installer already detects siblings and prints both can coexist — and they do coexist on disk. But at runtime, OpenCode dedupes skills by name and the .opencode copy loses.

Evidence

Repo has sdlc in .opencode/skills/ AND .claude/skills/; gdlc in .opencode/skills/ AND .claude/skills/; rdlc in .opencode/skills/, .claude/skills/, AND .agents/skills/.

opencode debug skill resolves:

sdlc -> .claude/skills/sdlc/SKILL.md     (NOT .opencode/skills/sdlc)
gdlc -> .claude/skills/gdlc/SKILL.md     (NOT .opencode/skills/gdlc)
rdlc -> .agents/skills/rdlc/SKILL.md     (NOT .opencode/skills/rdlc)

Observed precedence: .agents > .claude > .opencode. So the wizard's own .opencode/skills/sdlc/SKILL.md is shadowed by claude-sdlc-wizard's .claude/skills/sdlc/SKILL.md on any machine where both wizards are installed — which is exactly the "third lane" scenario the wizard is built for.

Per OpenCode docs (Agent Skills → Troubleshoot): "Ensure skill names are unique across all locations." The wizard ships colliding names by design.

Impact

• The opencode-sdlc-wizard's curated .opencode/skills/sdlc/SKILL.md never loads via the skill tool when the Claude wizard is also present. Users think they're running the OpenCode skill; they're running the Claude one.
• Any OpenCode-native ports a user adds (e.g. .opencode/skills/gdlc, .opencode/skills/rdlc) are silently shadowed.
• instructions: [".opencode/skills/sdlc/SKILL.md"] (path-based load) still works, because that bypasses the skill-tool dedupe — but the skill({ name: "sdlc" }) path does not.

Suggested fixes (pick any)

1. Post-install verification. After install, run opencode debug skill and warn if any wizard-installed .opencode/skills/* is shadowed by a .claude/.agents copy. The installer already detects siblings at write time; extend it to a runtime-resolution check.
2. Document the precedence + escape hatch. Note that OpenCode discovers .claude/skills and .agents/skills natively and ranks them above .opencode/skills. Document OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 + OPENCODE_DISABLE_EXTERNAL_SKILLS=1 for users who want .opencode skills to win (note the side effect: hides claude-only meta-skills from OpenCode).
3. Consider namespacing wizard skill names (or a config-level skill allowlist) so coexistence is real at runtime, not just on disk.

Bonus recipe request: skills vs slash-commands for Claude/Codex users

Related doc gap. Users coming from Claude Code / Codex expect /-commands, but OpenCode skills are invoked by the model via the skill tool, not as slash commands. A short recipe would help:

• Skills = workflow brains (auto-invoked by the model from their description).
• Commands = user-facing entrypoints (.opencode/commands/<name>.md).
• Pattern: thin /sdlc, /gdlc, /rdlc command wrappers whose body is invoke skill({ name: "..." }) — gives Claude/Codex-style ergonomics while OpenCode still loads the skill on demand.
• Note that auto-invoke depends on a sharp description; slash wrappers are the deterministic fallback.

Environment

• OpenCode: 1.16.2
• opencode-sdlc-wizard: 0.13.4
• Siblings present: claude-sdlc-wizard (.claude/), codex-sdlc-wizard (.codex/), .agents/skills/
• macOS 15.1 arm64

[BaseInfinity]

Correction + stronger finding: resolution is NON-DETERMINISTIC, not a fixed precedence

My original report claimed a fixed precedence (.agents > .claude > .opencode). That's wrong — verified by re-running opencode debug skill against an unchanged tree. The winner of a skill-name collision flips between identical runs:

Skill	run 1	run 2	run 3 (--pure)
rdlc	.agents	.opencode	.agents
setup-wizard	.opencode	.claude	.opencode

(rdlc was later also observed resolving to .claude. So across runs it has resolved to all three trees.)

So when a user has opencode-sdlc-wizard + claude-sdlc-wizard + codex/agents installed (the exact 'third lane' scenario), which skill version loads is effectively random per session. For functionally-equivalent workflow skills that's cosmetic; for the wizard's own maintenance skills it's a real foot-gun.

Additional collisions found

.claude/skills/update/SKILL.md declares name: update-wizard and .claude/skills/setup/SKILL.md declares name: setup-wizard — i.e. the directory name and the skill name differ, and the name collides with the OpenCode wizard's own setup-wizard/update-wizard. So skill({ name: "update-wizard" }) in OpenCode can non-deterministically load the Claude updater (which maintains .claude/ + the Claude wizard), not the OpenCode one.

Verified fix

Launching OpenCode with OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 + OPENCODE_DISABLE_EXTERNAL_SKILLS=1 makes it read only .opencode/skills/ — deterministic across runs, no external-tree leakage, and the wizard's own .opencode skills win cleanly. (No opencode.json key exists for this; it's env-var only, and .env is NOT honored for these flags — tested. A repo wrapper script or direnv .envrc is the persistence mechanism.)

Suggestion (updated)

The installer already detects sibling wizards. Consider: (1) at install time, warn that OpenCode skill resolution across the sibling trees is non-deterministic and recommend the isolation flags (or a generated bin/oc wrapper / .envrc); and/or (2) namespace the wizard's skills (e.g. opencode-setup-wizard) so name collisions with the Claude wizard's setup/update skills can't happen.

Environment: OpenCode 1.16.2, opencode-sdlc-wizard 0.13.4, macOS 15.1 arm64.