Skill enumeration is non-deterministic when the same skill is reachable through multiple discovery roots

[rikkarth]

Summary

opencode auto-discovers skills from six default locations including ~/.claude/skills/ and ~/.agents/skills/. When the same skill basename is reachable through more than one root (a common Claude Code setup, where ~/.claude/skills/<name> is symlinked to ~/.agents/skills/<name>), opencode's discovery randomly assigns one path or the other per session in the emitted <skill><location>...</location></skill> entries. This injects per-session volatility into the system prompt at random offsets, defeating prefix-cache reuse on every upstream backend.

Environment

• opencode dev branch (also reproduced on 1.15.11 release)
• Skills available in both ~/.claude/skills/ (mostly symlinks → ~/.agents/skills/) and ~/.agents/skills/
• 20 skills are reachable through both roots in our setup

Steps to reproduce

1. Have ~/.agents/skills/foo/SKILL.md and ~/.claude/skills/foo -> ../../.agents/skills/foo (symlink, or independent copy)
2. Open two fresh opencode sessions
3. Capture the outgoing system prompt in each session (we did this via a LiteLLM async_pre_call_hook writing the full system payload to disk)
4. Diff the two captures

Observed

Two fresh sessions in the same cwd, with identical config, produced byte-different <skill><location>...</location></skill> entries:

@@ -443,7 +443,7 @@
   <skill>
     <name>linear-reporting</name>
-    <location>file:///Users/.../.agents/skills/linear-reporting/SKILL.md</location>
+    <location>file:///Users/.../.claude/skills/linear-reporting/SKILL.md</location>
   </skill>
@@ -453,7 +453,7 @@
   <skill>
     <name>officecli</name>
-    <location>file:///Users/.../.agents/skills/officecli/SKILL.md</location>
+    <location>file:///Users/.../.claude/skills/officecli/SKILL.md</location>
   </skill>
@@ -495,7 +495,7 @@
   <skill>
     <name>pr-verify</name>
-    <location>file:///Users/.../.claude/skills/pr-verify/SKILL.md</location>
+    <location>file:///Users/.../.agents/skills/pr-verify/SKILL.md</location>
   </skill>

Note that the resolved root flips both directions across skills: linear-reporting goes .agents → .claude between sessions, while pr-verify goes .claude → .agents. So this isn't "preferred root" inconsistency — it's purely non-deterministic per-skill resolution.

Why it matters

Each one of these <location> flips changes ~30 characters of the system prompt at a deep offset. Every upstream prefix cache (Anthropic cache_control, OpenAI auto-cache, vLLM APC, oMLX paged SSD) keys on byte/block-level prefix match. Even with the prompt structurally identical, the location-string flips break cache hit rate.

Measured impact in our setup (Qwen3-Coder-Next-80B-A3B via oMLX on M3 Ultra):

• With this non-determinism: cache.read=0 or ~4096 tokens of 30,000 (~13%) per fresh session, ~30 s TTFT every session
• After workaround (see below): cache.read=28,672 / 30,000 (95.6%), 3–5 s TTFT on subsequent fresh sessions

Workaround

Set OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 in the launching environment. This drops ~/.claude/skills/ from external discovery entirely, leaving ~/.agents/skills/ as the only external root and eliminating the duplicate-resolution path. Tested and confirmed effective.

This workaround is not documented. We discovered it by reading packages/opencode/src/skill/index.ts (the disableClaudeCodeSkills flag) and packages/opencode/src/effect/runtime-flags.ts (the env var wire-up).

Proposed fix

In packages/opencode/src/skill/index.ts, deduplicate skills by basename at discovery time. When the same skill name appears in multiple roots, pick a canonical location (e.g., prefer .agents/skills/<name> over .claude/skills/<name>, or sort roots alphabetically and take the first match). Then sort the final set deterministically before emitting <skill> blocks.

This would:

• Eliminate the per-session non-determinism
• Restore prefix-cache hit rate to the structural maximum
• Make the OPENCODE_DISABLE_CLAUDE_CODE_SKILLS workaround unnecessary for this scenario

Related

• Companion PR: fix(session): move env block to tail of system prompt for cache stability #29949 — fix(session): move env block to tail of system prompt for cache stability
• Anthropic prompt caching misses when dynamic user.system is merged into the static prefix #20110, System environment prompt causes cache invalidation #5224 (system-prompt cache invalidation issues this is adjacent to)

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Non-deterministic agent/skill ordering in tool descriptions breaks prompt caching #18215: Non-deterministic agent/skill ordering in tool descriptions breaks prompt caching — covers the same root theme (non-deterministic skill/agent enumeration breaking prefix-cache hit rate), though it was closed and addressed ordering within a session rather than cross-session path randomness from multiple discovery roots. Your issue is a distinct scenario (same-named skill reachable via multiple roots resolving to different paths per session), so it may warrant its own fix even if Non-deterministic agent/skill ordering in tool descriptions breaks prompt caching #18215 was resolved.
• Skill discovery follows symlinks into large directories, causing 120s+ startup on slow filesystems #27027: Skill discovery follows symlinks — related symlink traversal behavior during skill discovery, though the problem there is performance rather than path non-determinism.

If you've already verified that #18215's fix did not address your specific case, feel free to note that here to help maintainers triage.