Skip to content

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

New issue
New issue
Closed as not planned
Closed as not planned
v2: compatibility skill sources ~/.agents/skills not loaded (regression vs v1)#43742
Assignees
kitlangton
Labels
2.0

Description

@JValdivia23
JValdivia23
opened on Aug 21, 2026

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.

Activity

  1. github-actions
    assigned
    kitlangton
    on Aug 21, 2026

  2. github-actions commented on Aug 21, 2026

    @github-actions
    github-actionsBot
    on Aug 21, 2026 – with GitHub Actions
    Contributor

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

    If you find your issue is covered by #41213, feel free to add a comment there with your v2-specific findings and we can close this one as a duplicate.

  3. opencode-agent
    added
    2.0
    on Aug 21, 2026

  4. sebastianw commented on Oct 15, 2026

    @sebastianw
    sebastianw
    on Oct 15, 2026

    Confirming this on the 2.0.29 GA release (Homebrew, latest channel), and adding what I think is the root cause — plus a caveat that the ~-prefixed workaround in this issue's body doesn't actually hold up when OPENCODE_TEST_HOME is set (which is the default for anyone running opencode under nono, a growing install path now that the nono-sandbox plugin/skill ships in the nolabs-ai opencode pack).

    Root cause: OPENCODE_TEST_HOME shadows HOME for ~/ expansion in the skills array

    Env trace from the failing session:

    HOME=/Users/<user>                                          # correct
OPENCODE_TEST_HOME=/Users/<user>/repositories/work/skills    # overridden to the workdir
OPENCODE_DISABLE_PROJECT_CONFIG=1

    $HOME is correct; only OPENCODE_TEST_HOME differs. Yet "skills": ["~/.agents/skills"] resolves to <OPENCODE_TEST_HOME>/.agents/skills (= /Users/<user>/repositories/work/skills/.agents/skills, which does not exist) instead of /Users/<user>/.agents/skills. The source is then silently dropped.

    The asymmetry that makes this hard to debug: global config at ~/.config/opencode/opencode.jsonc is still read from the real home (the skills array itself is parsed correctly), but the ~/ paths inside it are subsequently resolved against OPENCODE_TEST_HOME. The config is honoured; the paths vanish.

    This also explains why the auto compat-scan of ~/.agents/skills (the original symptom in this issue) fails to fire under nono — same tilde-redirection.

    The workaround in this issue's body breaks under nono

    Adding "skills": ["~/.agents/skills"] (as suggested above) produces zero watchers, zero registered skills, zero log lines when OPENCODE_TEST_HOME is set. Verified across five consecutive server boots in ~/.local/share/opencode/log/opencode.log — the only .agents watcher is path=<cwd>/.agents type=file (the project-level compat marker scan, unrelated to the home source). No watcher on the real ~/.agents/skills ever appears.

    Working workaround: absolute path

    "skills": ["/Users/<user>/.agents/skills"]

    Absolute paths skip tilde expansion, so OPENCODE_TEST_HOME can't intercept. After this change + opencode service restart + a fresh session, the source registers and skills load.

    Probe matrix (identical procedure before/after the absolute-path fix)

    Probe Source Autoinvoke off? ~/.agents/skills (relative) Abs path
    find-skills ~/.agents/skills/ no Unable to load skill find-skills ✅ loaded
    code-review ~/.agents/skills/ no Unable to load skill code-review ✅ loaded
    implement ~/.agents/skills/ yes Unable to load skill implement ✅ loaded via @implement
    nono-sandbox (control) ~/.config/opencode/skills/ no ✅ loaded ✅ loaded

    After the fix, 16 of the 39 skills in ~/.agents/skills/ appear in the model's advertised skill list (the remainder set opencode/autoinvoke: false by author intent and load via @skill-id). Skill footers read Base directory for this skill: /Users/<user>/.agents/skills/<id>.

    Minimal env-only repro (no sandbox strictly required)

    mkdir -p /tmp/fake-home/.agents/skills/my-skill
cat > /tmp/fake-home/.agents/skills/my-skill/SKILL.md <<'EOF'
---
name: my-skill
description: reproduction probe
---
hello
EOF

OPENCODE_TEST_HOME=/tmp/fake-home opencode --standalone
# with "skills": ["~/.agents/skills"] in config, observe whether my-skill registers

    Suggestions

    • Either honour HOME (not OPENCODE_TEST_HOME) for ~/ expansion in the skills array to match the docs (opencode.ai/v2/docs/skills says ~/ resolves "from the current user's home directory"), or document that OPENCODE_TEST_HOME affects ~/ resolution for skill sources and clarify the precedence.
    • Emit a WARN/INFO log line when a skills entry resolves to a nonexistent path (especially after env-var substitution). The silent-drop failure mode is what made this take hours instead of minutes.
    • This affects anyone running opencode under nono (and potentially other sandboxes/tools that set OPENCODE_TEST_HOME). The nono base profile sets OPENCODE_TEST_HOME=$WORKDIR deliberately, as a compatibility workaround to keep instruction-init probing inside the sandbox grant — so users can't just unset it without breaking other things. The absolute-path workaround is safe and doesn't disturb that env var.

    (Note: #41213 — the V1 version of this bug — was closed by @thdxr on Oct 11 with "OpenCode 2.0 is now out…reopen or open a new one with your 2.0 version." This comment serves that purpose by attaching to the existing V2-tracked issue.)

  5. opencodejr commented on Oct 28, 2026

    @opencodejr
    opencodejrBot
    on Oct 28, 2026
    Contributor

    Thanks for the detailed report! I couldn't reproduce this on the current release.

    I couldn't install 0.0.0-next-17403 because it's no longer published, so I tested @opencode/[email protected] with a clean home folder containing:

    • ~/.agents/skills/agy/SKILL.md (with name: agy and a description)
    • ~/.config/opencode/opencode.json containing only $schema

    After opencode service start, opencode api skill.list (both for $HOME and for a project directory) returned agy from ~/.agents/skills/agy/SKILL.md, along with the built-ins and a skill in ~/.config/opencode/skills. Right after the service starts, the first call can briefly return only the built-in skills, so give it a few seconds.

    Your build is an early pre-release, and skill discovery has changed a lot since. Could you upgrade to the latest 2.x (@opencode/cli), restart the service (opencode service restart) and check again? If agy is still missing, please reply with:

    • the output of opencode --version
    • opencode api skill.list | jq '[.data[].id]'
    • opencode debug config
    • whether ~/.agents or ~/.agents/skills is a symlink

    Related issues:

  6. opencodejr
    closed this as not plannedon Oct 31, 2026

  7. opencodejr commented on Oct 31, 2026

    @opencodejr
    opencodejrBot
    on Oct 31, 2026
    Contributor

    Closing this for now, since we haven't heard back. When I tested @opencode/[email protected], a skill in ~/.agents/skills/agy/SKILL.md showed up in opencode api skill.list. I couldn't test your build (0.0.0-next-17403) because it's no longer published, and skill discovery has changed a lot since then.

    If ~/.agents/skills still isn't picked up after you upgrade to the latest 2.x and run opencode service restart, please reply here or open a new issue with the output of opencode --version, opencode api skill.list | jq '[.data[].id]' and opencode debug config, and we'll take another look. Thanks for the detailed report!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

2.0

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions