From 01a2ac78b06634bc118ad188d6921bc89c1e6285 Mon Sep 17 00:00:00 2001 From: "M. Adel Alhashemi" Date: Fri, 26 Dec 2025 07:29:56 +0800 Subject: [PATCH] docs: document ~/.opencode as valid global config directory Both ~/.config/opencode/ and ~/.opencode/ are scanned for all config types (agents, commands, modes, plugins, skills, tools). Previously, docs inconsistently mentioned only one path or the other. Fixes #6171 --- packages/web/src/content/docs/agents.mdx | 2 +- packages/web/src/content/docs/commands.mdx | 2 +- packages/web/src/content/docs/config.mdx | 4 ++-- .../web/src/content/docs/custom-tools.mdx | 2 +- packages/web/src/content/docs/modes.mdx | 4 ++-- packages/web/src/content/docs/plugins.mdx | 4 ++-- packages/web/src/content/docs/skills.mdx | 19 ++++++++++++++----- 7 files changed, 23 insertions(+), 14 deletions(-) diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx index 6c1b15239c9..1182a099a9f 100644 --- 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 index 463ad9e498f..f84b767ff36 100644 --- 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 index 5ba22ff2d78..42e7647224f 100644 --- a/packages/web/src/content/docs/config.mdx +++ b/packages/web/src/content/docs/config.mdx @@ -190,7 +190,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). --- @@ -254,7 +254,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 index 2701be65086..132d0ed65f7 100644 --- 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 index ae14c2f32b5..301c3fd8863 100644 --- 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 index 6be545482c1..624487d54d0 100644 --- 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 index c1d433a839f..aed443937af 100644 --- 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//SKILL.md` -- Global config: `~/.opencode/skill//SKILL.md` -- Claude-compatible: `.claude/skills//SKILL.md` +| Location | Path | Description | +| -------------- | ------------------------------------------ | ------------------------------------- | +| XDG config | `~/.config/opencode/skill//SKILL.md` | Primary global location (recommended) | +| Home directory | `~/.opencode/skill//SKILL.md` | Alternative global location | +| Project | `.opencode/skill//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 `~/.opencode/skill/*/SKILL.md`. +You can also set the `OPENCODE_CONFIG_DIR` environment variable to add a custom config directory. ---