docs(skill): customize-opencode table omits project-level .claude/skills and .agents/skills auto-discovery

Problem

The customize-opencode built-in skill's "Where files live" table states:

This reads as if .claude/skills and .agents/skills are picked up only from the home directory. Agents following this guidance conclude that a project-level .agents/skills/ (or .claude/skills/) is not scanned unless it is registered manually via skills.paths in opencode.json — which is wrong.

What the code actually does

In the skill loader (discoverSkills), the external directories are scanned at both scopes:

const CLAUDE_EXTERNAL_DIR = ".claude"
const AGENTS_EXTERNAL_DIR = ".agents"
const EXTERNAL_SKILL_PATTERN = "skills/**/SKILL.md"

// 1) global: ~/.claude/skills/**/SKILL.md and ~/.agents/skills/**/SKILL.md
for (const dir of externalDirs) {
  const root = path.join(global.home, dir)
  // ...
  yield* scan(state, root, EXTERNAL_SKILL_PATTERN, { dot: true, scope: "global" })
}

// 2) project: walk up from cwd to the worktree root, scanning
//    <dir>/.claude/skills/**/SKILL.md and <dir>/.agents/skills/**/SKILL.md
const upDirs = yield* fsys.up({ targets: externalDirs, start: directory, stop: worktree })
for (const root of upDirs) {
  yield* scan(state, root, EXTERNAL_SKILL_PATTERN, { dot: true, scope: "project" })
}

FileSystem.up walks from the current directory up to the worktree root and collects every existing .claude / .agents directory along the way, so project-level .agents/skills/ and .claude/skills/ are auto-discovered with no config needed (verified on v1.18.15). Both scopes are gated by OPENCODE_DISABLE_EXTERNAL_SKILLS=1, and the .claude part additionally by OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1.

Why it matters

The vendor-neutral .agents/skills/ convention is shared across multiple agent tools (Claude Code, Codex, etc.). Users who want a single cross-tool skills folder per project currently get steered toward .opencode/skills/ + a manual skills.paths entry, duplicating configuration for no reason.

Suggested fix

Add a row to the table (and mention the disable flags apply to both scopes), e.g.:

Optionally clarify in the "Skills" section that skills.paths is only needed for non-default locations, not for project-level .agents/skills / .claude/skills.

Start with the customize-opencode built-in skill and its “Where files live” table, then review the discoverSkills entry point described in the issue. Document project-level .claude/skills and .agents/skills auto-discovery, the applicable disable flags, and that skills.paths is for non-default locations. Done means the table and Skills section no longer imply these project paths require manual registration.