Skip to content

Commit 01a2ac7

Browse files
committed
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 anomalyco#6171
1 parent 1bd8e61 commit 01a2ac7

7 files changed

Lines changed: 23 additions & 14 deletions

File tree

‎packages/web/src/content/docs/agents.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ Configure agents in your `opencode.json` config file:
157157

158158
You can also define agents using markdown files. Place them in:
159159

160-
- Global: `~/.config/opencode/agent/`
160+
- Global: `~/.config/opencode/agent/` or `~/.opencode/agent/`
161161
- Per-project: `.opencode/agent/`
162162

163163
```markdown title="~/.config/opencode/agent/review.md"

‎packages/web/src/content/docs/commands.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ Now you can run this command in the TUI:
7979

8080
You can also define commands using markdown files. Place them in:
8181

82-
- Global: `~/.config/opencode/command/`
82+
- Global: `~/.config/opencode/command/` or `~/.opencode/command/`
8383
- Per-project: `.opencode/command/`
8484

8585
```markdown title="~/.config/opencode/command/test.md"

‎packages/web/src/content/docs/config.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ You can configure specialized agents for specific tasks through the `agent` opti
190190
}
191191
```
192192

193-
You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
193+
You can also define agents using markdown files in `~/.config/opencode/agent/`, `~/.opencode/agent/`, or `.opencode/agent/`. [Learn more here](/docs/agents).
194194

195195
---
196196

@@ -254,7 +254,7 @@ You can configure custom commands for repetitive tasks through the `command` opt
254254
}
255255
```
256256

257-
You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
257+
You can also define commands using markdown files in `~/.config/opencode/command/`, `~/.opencode/command/`, or `.opencode/command/`. [Learn more here](/docs/commands).
258258

259259
---
260260

‎packages/web/src/content/docs/custom-tools.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Tools are defined as **TypeScript** or **JavaScript** files. However, the tool d
1818
They can be defined:
1919

2020
- Locally by placing them in the `.opencode/tool/` directory of your project.
21-
- Or globally, by placing them in `~/.config/opencode/tool/`.
21+
- Or globally in `~/.config/opencode/tool/` or `~/.opencode/tool/`.
2222

2323
---
2424

‎packages/web/src/content/docs/modes.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Configure modes in your `opencode.json` config file:
8787

8888
You can also define modes using markdown files. Place them in:
8989

90-
- Global: `~/.config/opencode/mode/`
90+
- Global: `~/.config/opencode/mode/` or `~/.opencode/mode/`
9191
- Project: `.opencode/mode/`
9292

9393
```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
268268

269269
### Using markdown files
270270

271-
Create mode files in `.opencode/mode/` for project-specific modes or `~/.config/opencode/mode/` for global modes:
271+
Create mode files in `.opencode/mode/` for project-specific modes, or `~/.config/opencode/mode/` / `~/.opencode/mode/` for global modes:
272272

273273
```markdown title=".opencode/mode/debug.md"
274274
---

‎packages/web/src/content/docs/plugins.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ functions. Each function receives a context object and returns a hooks object.
2020

2121
Plugins are loaded from:
2222

23-
1. `.opencode/plugin` directory either in your project
24-
2. Or, globally in `~/.config/opencode/plugin`
23+
1. `.opencode/plugin` directory in your project
24+
2. Or globally in `~/.config/opencode/plugin` or `~/.opencode/plugin`
2525

2626
---
2727

‎packages/web/src/content/docs/skills.mdx‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,27 @@ Skills are loaded on-demand via the native `skill` tool—agents see available s
1313
Create one folder per skill name and put a `SKILL.md` inside it.
1414
OpenCode searches these locations:
1515

16-
- Project config: `.opencode/skill/<name>/SKILL.md`
17-
- Global config: `~/.opencode/skill/<name>/SKILL.md`
18-
- Claude-compatible: `.claude/skills/<name>/SKILL.md`
16+
| Location | Path | Description |
17+
| -------------- | ------------------------------------------ | ------------------------------------- |
18+
| XDG config | `~/.config/opencode/skill/<name>/SKILL.md` | Primary global location (recommended) |
19+
| Home directory | `~/.opencode/skill/<name>/SKILL.md` | Alternative global location |
20+
| Project | `.opencode/skill/<name>/SKILL.md` | Project-specific skills |
21+
22+
:::note
23+
On macOS and Linux, `~/.config/opencode/` follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
24+
Both global locations work identically—use whichever fits your dotfiles setup.
25+
:::
1926

2027
---
2128

2229
## Understand discovery
2330

2431
For project-local paths, OpenCode walks up from your current working directory until it reaches the git worktree.
25-
It loads any matching `skill/*/SKILL.md` in `.opencode/` and any matching `.claude/skills/*/SKILL.md` along the way.
32+
It loads any matching `skill/*/SKILL.md` in `.opencode/` directories along the way.
33+
34+
Global definitions are loaded from both `~/.config/opencode/skill/*/SKILL.md` and `~/.opencode/skill/*/SKILL.md`.
2635

27-
Global definitions are also loaded from `~/.opencode/skill/*/SKILL.md`.
36+
You can also set the `OPENCODE_CONFIG_DIR` environment variable to add a custom config directory.
2837

2938
---
3039

0 commit comments

Comments
 (0)