From ed31db7fc4d4f417b2bebf8ee46e4e1db9fff543 Mon Sep 17 00:00:00 2001 From: holny Date: Mon, 14 Sep 2026 20:19:52 +0800 Subject: [PATCH] docs(skill): document project-level external skill auto-discovery The 'Where files live' table only listed the home-directory external skill paths, but discoverSkills also scans .claude/skills and .agents/skills from the cwd up to the worktree root. Split the row into project and global entries, note the disable flags cover both scopes, and clarify that skills.paths is only needed for non-default locations. Closes #41850 --- .../core/src/plugin/skill/customize-opencode.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/packages/core/src/plugin/skill/customize-opencode.md b/packages/core/src/plugin/skill/customize-opencode.md index c02ed72efb74..e63df62d9cd0 100644 --- a/packages/core/src/plugin/skill/customize-opencode.md +++ b/packages/core/src/plugin/skill/customize-opencode.md @@ -47,7 +47,8 @@ already-loaded config until then. | Global commands | `~/.config/opencode/command(s)/.md` | | Project skills | `.opencode/skill(s)//SKILL.md` | | Global skills | `~/.config/opencode/skill(s)//SKILL.md` | -| External skills (auto-loaded) | `~/.claude/skills//SKILL.md`, `~/.agents/skills//SKILL.md` | +| Project external skills | `.claude/skills//SKILL.md`, `.agents/skills//SKILL.md` (opencode walks up from the cwd to the worktree root) | +| Global external skills | `~/.claude/skills//SKILL.md`, `~/.agents/skills//SKILL.md` | Configs from each scope are deep-merged. Project overrides global. Unknown top-level keys in `opencode.json` are rejected with `ConfigInvalidError`. @@ -187,7 +188,8 @@ description: One sentence covering what this skill does AND when to trigger it. Register skills from non-default locations via `skills.paths` (scanned recursively for `**/SKILL.md`) and `skills.urls` (each URL serves a list of -skills). +skills). Project and global `.claude/skills` and `.agents/skills` directories +are discovered automatically and do not need entries in `skills.paths`. ## References @@ -434,9 +436,10 @@ When a user's config is broken and opencode won't start, these env vars help: inject inline JSON as a final local-scope merge. - `OPENCODE_DISABLE_DEFAULT_PLUGINS=1`: skip default plugins. - `OPENCODE_PURE=1`: skip external plugins entirely. -- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`, - `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip the external skill scans under - `~/.claude/` and `~/.agents/`. +- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`: skip all project and global skill scans + under `.claude/` and `.agents/`. +- `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip project and global + `.claude/skills/` scans while keeping `.agents/skills/` enabled. ## When proposing edits