skills: new ~/.agents/skills skill not discovered until reload when ~/.agents was absent at startup #61410

Activity

1. sathvicp

   closed this as completedon Nov 3, 2026
2. opencodejr commented on Nov 3, 2026

   

   opencodejrBot

   on Nov 3, 2026

   Contributor

   More actions

   Thanks for the detailed report and logs. I reproduced this on 2.2.5, and it still happens on the latest dev (6d1c444).

   Steps, using an isolated HOME with no ~/.agents and the background service running:

   1. Create ~/.agents (for example, an installer writing a lock file there), and about a second later create ~/.agents/skills/caveman/SKILL.md.
   2. After 15s, opencode api get /api/skill still doesn't list caveman.
   3. After opencode reload, it does.

   If the whole path ~/.agents/skills/caveman/SKILL.md is created in one step, the skill is picked up without a reload. So the trigger seems to be ~/.agents appearing before skills/. When ~/.agents appears, OpenCode rescans once; skills/ isn't there yet, so nothing gets watched and its later creation is missed. The script below reproduces it.

   Related:

   • fix(core): watch for skills/ inside existing .agents and .claude roots #55280: open PR that watches skills/ when .agents/.claude exists but skills/ doesn't. It's the same pattern, but it may not cover a missing ~/.agents.
   • skills: newly added skill directories are not discovered until service restart #52701: newly added skill directories not discovered until restart.

   Until this is fixed, your workarounds still work: run opencode reload, or list ~/.agents/skills under skills in your config.

   Reproduction script (repro.sh)

   #!/usr/bin/env bash
   # Reproduces #61410: a skill created in ~/.agents/skills after the service starts
   # (with ~/.agents absent at startup) is not discovered until `opencode reload`.
   # Usage: OC="opencode" bash repro.sh   (or OC="bun ... packages/cli/src/index.ts")
   # From source: PROJ=/workspace/repo/packages/cli OC="bun --conditions=browser --preload=.../preload.js .../packages/cli/src/index.ts" bash repro.sh
   # (PROJ inside packages/cli so the spawned service picks up its bunfig preload)
   set -u
   OC=${OC:-opencode}
   export HOME=$(mktemp -d /tmp/opencode/home.XXXX)
   export XDG_CONFIG_HOME=$HOME/.config XDG_DATA_HOME=$HOME/.local/share XDG_STATE_HOME=$HOME/.local/state XDG_CACHE_HOME=$HOME/.cache
   mkdir -p $XDG_CONFIG_HOME/opencode; echo "{}" > $XDG_CONFIG_HOME/opencode/opencode.json
   PROJ=${PROJ:-$(mktemp -d /tmp/opencode/proj.XXXX)}; mkdir -p $PROJ; cd $PROJ
   echo "HOME=$HOME"; $OC --version
   skills() { $OC api get /api/skill 2>&1 | grep -o '"id": *"[^"]*"\|"name": *"[^"]*"' | sort -u | tr '\n' ' '; echo; }
   echo "--- initial (~/.agents absent)"; ls -d ~/.agents 2>&1; skills; sleep 2; skills
   sleep 3
   # Like a skill installer: ~/.agents is created first (e.g. a lock file), skills/ a moment later
   mkdir -p ~/.agents; echo "{}" > ~/.agents/.skill-lock.json; sleep 1
   mkdir -p ~/.agents/skills/caveman
   printf -- '---\nname: caveman\ndescription: Talk like a caveman\n---\nUse short words.\n' > ~/.agents/skills/caveman/SKILL.md
   echo "--- created ~/.agents/skills/caveman/SKILL.md, waiting 15s"; sleep 15
   skills
   echo "--- opencode reload"; $OC reload 2>&1 | tail -2; sleep 5
   skills
   $OC service stop >/dev/null 2>&1 || true

   Run it: bash repro.sh
3. opencodejr

   added

   reproduced

   on Nov 3, 2026