docs: document ~/.opencode as valid global config directory

[malhashemi]

Problem Statement

What pain point in the dev workflow does this address?

Users who version control their OpenCode configurations in ~/.opencode/ (instead of ~/.config/opencode/) found that the documentation was inconsistent about which paths are valid for global configuration.

What was the previous state?

• Skills docs mentioned only ~/.opencode/skill/ and incorrectly listed .claude/skills/ as supported
• Other docs (agents, commands, modes, plugins, tools) mentioned only ~/.config/opencode/
• Users were confused about which path to use

Why is this change needed now?

Issue #6171 reported this inconsistency. Users need clear documentation to properly organize their configurations.

---

Technical Changes

High-level approach:

Updated all configuration documentation to consistently document both ~/.config/opencode/ and ~/.opencode/ as valid global configuration directories.

Key components modified/added:

• packages/web/src/content/docs/skills.mdx - Complete rewrite with table format, XDG note
• packages/web/src/content/docs/agents.mdx - Added ~/.opencode/agent/
• packages/web/src/content/docs/commands.mdx - Added ~/.opencode/command/
• packages/web/src/content/docs/modes.mdx - Added ~/.opencode/mode/
• packages/web/src/content/docs/plugins.mdx - Added ~/.opencode/plugin/
• packages/web/src/content/docs/custom-tools.mdx - Added ~/.opencode/tool/
• packages/web/src/content/docs/config.mdx - Updated agent/command references

Design decisions and rationale:

The code in packages/opencode/src/config/config.ts (lines 70-86) shows that BOTH paths are scanned:

const directories = [
  Global.Path.config,  // ~/.config/opencode (XDG)
  ...(await Array.fromAsync(
    Filesystem.up({
      targets: [".opencode"],  // Scans for .opencode directories
      start: Instance.directory,
      stop: Instance.worktree,
    }),
  )),
  ...(await Array.fromAsync(
    Filesystem.up({
      targets: [".opencode"],  // Also scans ~/.opencode
      start: Global.Path.home,
      stop: Global.Path.home,
    }),
  )),
]

And lines 108-112 confirm ALL features use this same directory list:

result.command = mergeDeep(result.command ?? {}, await loadCommand(dir))
result.agent = mergeDeep(result.agent, await loadAgent(dir))
result.agent = mergeDeep(result.agent, await loadMode(dir))
result.plugin.push(...(await loadPlugin(dir)))

Skills also use Config.directories() in packages/opencode/src/skill/skill.ts.

Alternatives considered:

Could have documented only ~/.config/opencode/ as the canonical path, but since ~/.opencode/ is actively supported in the code and some users prefer it for dotfiles management, documenting both is the correct approach.

Dependencies added/updated:

• None

---

Impact

For Developers

New commands/workflows available:

No new commands - this is documentation only.

Changed behavior:

None - the code already supported both paths.

Breaking changes:

• [x] No breaking changes

For AI Agents

Can agents discover and use the new functionality?

• [x] Documented in skills.mdx and other docs
• [x] Commands are self-documenting
• [x] N/A for session management

How does this enhance agent capabilities?

N/A - documentation fix only.

---

Verification

Automated Tests

• [x] N/A - documentation only change

Manual Testing

• [x] Verified code paths in config.ts confirm both directories are scanned
• [x] Removed incorrect .claude/skills/ reference (not supported in code)

Manual testing steps performed:

1. Reviewed packages/opencode/src/config/config.ts lines 70-112
2. Reviewed packages/opencode/src/skill/skill.ts to confirm it uses Config.directories()
3. Searched codebase for .claude/skills - confirmed it's NOT supported

---

Related Work

Related PRs/Issues:

• Closes #6171

---

Changelog Entry

Type: docs

Summary (1-2 lines):

Document that both ~/.config/opencode/ and ~/.opencode/ are valid global configuration directories for all features (agents, commands, modes, plugins, skills, tools).

Full entry:

- docs: document ~/.opencode as valid global config directory for all features