v2: compatibility skill sources ~/.agents/skills not loaded (regression vs v1)

Summary

V2 (opencode2) does not load skills from the compatibility source ~/.agents/skills, while V1 does. opencode debug skill shows agy -> ~/.agents/skills/agy/SKILL.md, but opencode2 /api/skill (and filesystem watchers) only show built-ins + ~/.config/opencode/skills. V2 docs list ~/.agents/skills as a global compatibility source, so this is a regression / missing parity.

Environment

• opencode version: 1.18.18 (brew, stable) — loads ~/.agents/skills/agy correctly
• opencode2 version: 0.0.0-next-17403 (next channel, ~/.opencode/bin/opencode2)
• OS: Darwin 25.6.0 (darwin arm64) — Darwin UCB-PXWCWTM9N9 25.6.0 Darwin Kernel Version 25.6.0: Fri Jul 31 19:18:43 PDT 2026; root:xnu-12377.161.14~5/RELEASE_ARM64_T8112 arm64
• Terminal: ghostty 1.3.1 — TERM=xterm-256color, TERM_PROGRAM=ghostty, COLORTERM=truecolor
• Shell: /bin/zsh
• Install/channel: next (service: ~/.opencode/bin/opencode2 serve --service pid 39922, update check: latest=0.0.0-beta-17728, auto-update skipped: installation method not found)
• Active plugins: ~/.config/opencode/plugins/herdr-agent-state.js (fails to load in V2: Missing key at ["default"] — export const HerdrAgentStatePlugin but V2 expects export default)

Reproduction

1. Have a skill at ~/.agents/skills/agy/SKILL.md:

   ~/.agents/skills/agy/SKILL.md
   ~/.agents/skills/agy/scripts/agy-run.sh
   ~/.agents/skills/agy/references/*.md
   

   with frontmatter:

   name: agy
   description: >-
     Delegate a task to the Antigravity CLI (agy) in headless print mode...
   

2. opencode debug skill (V1) -> shows agy -> /Users/java1127/.agents/skills/agy/SKILL.md (total 3: customize-opencode, agy, skill-creator)
3. curl -u opencode:$PASS "http://127.0.0.1:49374/api/skill?directory=$HOME" -H "Accept: application/json" | jq (V2 service) -> ["opencode","report","skill-creator"] — no agy
4. curl -u ... "/api/config?directory=$HOME" -> [{"type":"document","path":"~/.config/opencode/opencode.json"}, {"type":"directory","path":"~/.config/opencode"}, {"type":"directory","path":"~/.opencode"}] — no type:"agents" entry for ~/.agents
5. ~/.local/share/opencode/log/opencode.log watchers for V2 location ~ show subscriptions for ~/.config/opencode/skill, ~/.config/opencode/skills, ~/.opencode/skill, ~/.opencode/skills only — no ~/.agents/skills watcher (expected from opencode.config.skill plugin f() mapping agents type -> join(path,"skills")).

Consistently reproducible. Also tested OPENCODE_TEST_HOME=/tmp/fake/.agents/skills/hello/SKILL.md with opencode2 debug config — still no agents entry.

Expected Behavior

V2 should auto-discover skills from the compatibility sources documented at https://opencode.ai/v2/docs/skills:

| Scope | Sources |
| Global compatibility | ~/.claude/skills, ~/.agents/skills |
| Project compatibility | .claude/skills, .agents/skills |

Discovery section states project sources are searched upward and within each source *.md at root and **/SKILL.md at any depth are discovered. Precedence section lists ~/.agents/skills after .claude/skills.

~/.agents/skills/agy/SKILL.md should appear in V2 /api/skill and be watchable, matching V1 external auto-loaded behavior (packages/core/src/plugin/skill/customize-opencode.md external row + packages/core/src/skill/index.ts scan with CLAUDE_EXTERNAL_DIR=".claude", AGENTS_EXTERNAL_DIR=".agents", EXTERNAL_SKILL_PATTERN="skills/**/SKILL.md").

Actual Behavior

V2 next-17403 ignores ~/.agents/skills entirely. No error is logged at INFO level (file-skip would be DEBUG skill file skipped). The running binary (strings ~/.opencode/bin/opencode2) does contain the opencode.config.skill plugin with type==="agents" source construction (join(O,"skills") for agents/claude entries) and Config.discover creating type:"agents" entries from T.isDir(~/.agents), yet at runtime no agents entry or watcher materializes and no skill is registered.

Additional Context

• V1 docs (opencode debug skill built-in customize-opencode skill) explicitly list External skills (auto-loaded) | ~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md.
• V2 binary Config.discover (extracted via strings) includes:

  j=b_.make(join(A.home,".agents")), F=b_.make(join(A.home,".claude")),
  h_=[...new Set([...T.isDir(j)?[j]:[], ...c.filter(basename===".agents")])].map(i=>new f9({type:"agents",path:b_.make(i)}))
  

  and ConfigSkillPlugin f() does:

  h=entries.flatMap(O=>O.type==="claude"?[O.path]:[]), $=entries.flatMap(O=>O.type==="agents"?[O.path]:[]),
  for(O of[...h,...$]) k(DirectorySource({path:join(O,"skills")}))
  

  So the running service should create ~/.agents/skills source — but watchers prove it doesn't.
• Workaround: add explicit skills config (V2 native array form after A1.normalize: T.skills=[...paths,...urls]):

  // ~/.config/opencode/opencode.json
  { "$schema":"https://opencode.ai/config.json", "skills":["~/.agents/skills"] }
  

  This bypasses the missing compatibility source.
• Related: second Location services booted for ~/Library/CloudStorage/.../GC_voxel shows the service hosts multiple locations; both locations lack the agents source.
• Herdr plugin load failure in V2 is unrelated but noted for completeness.
• No OPENCODE_DISABLE_EXTERNAL_SKILLS / OPENCODE_DISABLE_CLAUDE_CODE_SKILLS set (checked env | grep OPENCODE).
• update check: current=0.0.0-next-17403 latest=0.0.0-beta-17728 — not yet on the newer beta where the fix may exist.

Config for reference:

// ~/.config/opencode/opencode.json
{ "$schema":"https://opencode.ai/config.json" }

~/.agents/skills/agy was verified isDir true and contains a valid SKILL.md that V1 parses.