sst · malhashemi · Dec 25, 2025 · Dec 25, 2025
diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx
@@ -157,7 +157,7 @@ Configure agents in your `opencode.json` config file:
 
 You can also define agents using markdown files. Place them in:
 
-- Global: `~/.config/opencode/agent/`
+- Global: `~/.config/opencode/agent/` or `~/.opencode/agent/`
 - Per-project: `.opencode/agent/`
 
 ```markdown title="~/.config/opencode/agent/review.md"

diff --git a/packages/web/src/content/docs/commands.mdx b/packages/web/src/content/docs/commands.mdx
@@ -79,7 +79,7 @@ Now you can run this command in the TUI:
 
 You can also define commands using markdown files. Place them in:
 
-- Global: `~/.config/opencode/command/`
+- Global: `~/.config/opencode/command/` or `~/.opencode/command/`
 - Per-project: `.opencode/command/`
 
 ```markdown title="~/.config/opencode/command/test.md"

diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
@@ -194,7 +194,7 @@ You can configure specialized agents for specific tasks through the `agent` opti
 }
 ```
 
-You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
+You can also define agents using markdown files in `~/.config/opencode/agent/`, `~/.opencode/agent/`, or `.opencode/agent/`. [Learn more here](/docs/agents).
 
 ---
 
@@ -258,7 +258,7 @@ You can configure custom commands for repetitive tasks through the `command` opt
 }
 ```
 
-You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
+You can also define commands using markdown files in `~/.config/opencode/command/`, `~/.opencode/command/`, or `.opencode/command/`. [Learn more here](/docs/commands).
 
 ---
 

diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx
@@ -18,7 +18,7 @@ Tools are defined as **TypeScript** or **JavaScript** files. However, the tool d
 They can be defined:
 
 - Locally by placing them in the `.opencode/tool/` directory of your project.
-- Or globally, by placing them in `~/.config/opencode/tool/`.
+- Or globally in `~/.config/opencode/tool/` or `~/.opencode/tool/`.
 
 ---
 

diff --git a/packages/web/src/content/docs/modes.mdx b/packages/web/src/content/docs/modes.mdx
@@ -87,7 +87,7 @@ Configure modes in your `opencode.json` config file:
 
 You can also define modes using markdown files. Place them in:
 
-- Global: `~/.config/opencode/mode/`
+- Global: `~/.config/opencode/mode/` or `~/.opencode/mode/`
 - Project: `.opencode/mode/`
 
 ```markdown title="~/.config/opencode/mode/review.md"
@@ -268,7 +268,7 @@ You can create your own custom modes by adding them to the configuration. Here a
 
 ### Using markdown files
 
-Create mode files in `.opencode/mode/` for project-specific modes or `~/.config/opencode/mode/` for global modes:
+Create mode files in `.opencode/mode/` for project-specific modes, or `~/.config/opencode/mode/` / `~/.opencode/mode/` for global modes:
 
 ```markdown title=".opencode/mode/debug.md"
 ---

diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
@@ -20,8 +20,8 @@ functions. Each function receives a context object and returns a hooks object.
 
 Plugins are loaded from:
 
-1. `.opencode/plugin` directory either in your project
-2. Or, globally in `~/.config/opencode/plugin`
+1. `.opencode/plugin` directory in your project
+2. Or globally in `~/.config/opencode/plugin` or `~/.opencode/plugin`
 
 ---
 

diff --git a/packages/web/src/content/docs/skills.mdx b/packages/web/src/content/docs/skills.mdx
@@ -13,18 +13,27 @@ Skills are loaded on-demand via the native `skill` tool—agents see available s
 Create one folder per skill name and put a `SKILL.md` inside it.
 OpenCode searches these locations:
 
-- Project config: `.opencode/skill/<name>/SKILL.md`
-- Global config: `~/.config/opencode/skill/<name>/SKILL.md`
-- Claude-compatible: `.claude/skills/<name>/SKILL.md`
+| Location       | Path                                       | Description                           |
+| -------------- | ------------------------------------------ | ------------------------------------- |
+| XDG config     | `~/.config/opencode/skill/<name>/SKILL.md` | Primary global location (recommended) |
+| Home directory | `~/.opencode/skill/<name>/SKILL.md`        | Alternative global location           |
+| Project        | `.opencode/skill/<name>/SKILL.md`          | Project-specific skills               |
+
+:::note
+On macOS and Linux, `~/.config/opencode/` follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
+Both global locations work identically—use whichever fits your dotfiles setup.
+:::
 
 ---
 
 ## Understand discovery
 
 For project-local paths, OpenCode walks up from your current working directory until it reaches the git worktree.
-It loads any matching `skill/*/SKILL.md` in `.opencode/` and any matching `.claude/skills/*/SKILL.md` along the way.
+It loads any matching `skill/*/SKILL.md` in `.opencode/` directories along the way.
+
+Global definitions are loaded from both `~/.config/opencode/skill/*/SKILL.md` and `~/.opencode/skill/*/SKILL.md`.
 
-Global definitions are also loaded from `~/.config/opencode/skill/*/SKILL.md`.
+You can also set the `OPENCODE_CONFIG_DIR` environment variable to add a custom config directory.
 
 ---
-Original file line number
+Diff line change
@@ Expand Up @@
     }
     ```
-    You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
+    You can also define agents using markdown files in `~/.config/opencode/agent/`, `~/.opencode/agent/`, or `.opencode/agent/`. [Learn more here](/docs/agents).
     ---
@@ Expand Down Expand Up @@
     }
     ```
-    You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
+    You can also define commands using markdown files in `~/.config/opencode/command/`, `~/.opencode/command/`, or `.opencode/command/`. [Learn more here](/docs/commands).
     ---
@@ Expand Down @@