feat(skill-loader): support skills.paths config for plugin skill discovery

[ventsislav-georgiev]

Summary

• Add support for reading skills.paths from opencode.json/opencode.jsonc config files
• Plugin authors can ship SKILL.md files in their packages and users point to them via config
• Scans project root, .opencode/, and global ~/.config/opencode/ config paths

Problem

OpenCode plugins can register tools via the plugin API, but there's no mechanism for plugins to ship discoverable skills (SKILL.md files). Users had to manually copy or symlink skill files into .opencode/skills/ directories.

OpenCode natively supports skills.paths in config, but oh-my-opencode's skill loader override didn't read this setting, causing a gap where configured skill paths were silently ignored.

Solution

Added readOpenCodeSkillsPaths() that reads skills.paths from opencode config files (checking project root, .opencode/, and global config in precedence order). Wired into both discoverSkills() and discoverAllSkills() with "config" scope priority between opencode and project scopes.

Config example

{
  "skills": {
    "paths": [
      "/absolute/path/to/plugin/skills",
      "relative/path/to/skills",
      "~/home-relative/path"
    ]
  }
}

Changes

• New: opencode-config-skills-paths.ts — reads and resolves skills.paths from config
• Modified: loader.ts — added discoverConfigPathsSkills(), wired into both discovery flows
• New: opencode-config-skills-paths.test.ts — 7 tests covering absolute/relative/JSONC/filtering/integration

Testing

• 7 new tests pass
• 97/97 existing skill-loader tests pass (no regressions)
• Verified live: plugins' SKILL.md files discovered and available via /skills command

---

Summary by cubic

Adds support for skills.paths in OpenCode config so plugin SKILL.md folders are auto-discovered with the right precedence and registered as commands automatically.

• New Features
  • Reads skills.paths from opencode.jsonc (preferred) and opencode.json in the project root, .opencode/, and the global config dir (respects OPENCODE_CONFIG_DIR).
  • Resolves absolute, relative, and ~/ paths; .opencode entries resolve against the project root, global entries against the global config dir; skips missing dirs.
  • Introduces a config scope with priority: opencode-project > opencode > config paths > project > user.
  • Adds discoverConfigPathsSkills(), loadConfigPathsSkills(), and readOpenCodeSkillsPaths(); integrated into discoverSkills, discoverAllSkills, and the command config handler.

^{Written for commit 549aaf7. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[ventsislav-georgiev]

I have read the CLA Document and I hereby sign the CLA

[cubic-dev-ai]

4 issues found across 3 files

Confidence score: 3/5

• There is concrete cross-platform risk in src/features/opencode-skill-loader/opencode-config-skills-paths.ts: hardcoding ~/.config/opencode (severity 8/10, confidence 10/10) can miss the real global config location on Windows and other OS setups.
• src/features/opencode-skill-loader/loader.ts may not wire newly discovered skills.paths into command registration, so skills could be found but not become executable commands (user-facing behavior gap).
• The remaining findings are test-focused but still meaningful: src/features/opencode-skill-loader/opencode-config-skills-paths.test.ts has Windows JSONC escaping fragility and environment leakage into real global config, which can cause flaky/platform-dependent failures.
• Pay close attention to src/features/opencode-skill-loader/opencode-config-skills-paths.ts, src/features/opencode-skill-loader/loader.ts, and src/features/opencode-skill-loader/opencode-config-skills-paths.test.ts - path resolution and command wiring need validation, and tests should be made platform-safe and isolated.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/opencode-skill-loader/opencode-config-skills-paths.ts">

<violation number="1" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:13">
P1: Custom agent: **Opencode Compatibility**

Do not hardcode `~/.config/opencode` for OpenCode's global configuration directory. Use the shared `getOpenCodeConfigPaths` utility to ensure OS-specific paths (e.g., `%APPDATA%` on Windows, `Library/Application Support` on macOS) and environment variables like `OPENCODE_CONFIG_DIR` are respected, maintaining compatibility with OpenCode.</violation>
</file>

<file name="src/features/opencode-skill-loader/loader.ts">

<violation number="1" location="src/features/opencode-skill-loader/loader.ts:49">
P2: New `skills.paths` discovery is not wired into command registration, so those skills may not become executable commands.</violation>
</file>

<file name="src/features/opencode-skill-loader/opencode-config-skills-paths.test.ts">

<violation number="1" location="src/features/opencode-skill-loader/opencode-config-skills-paths.test.ts:72">
P2: Test is not environment-isolated: it can read real global `~/.config/opencode` config and fail on machines with `skills.paths` configured.</violation>

<violation number="2" location="src/features/opencode-skill-loader/opencode-config-skills-paths.test.ts:101">
P2: Raw Windows path interpolation creates invalid JSONC string escapes, making the JSONC test platform-dependent and likely to fail on Windows.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin-handlers/command-config-handler.ts">

<violation number="1" location="src/plugin-handlers/command-config-handler.ts:63">
P2: configPathsSkills is merged too early, giving it lower precedence than user/project/opencode skills; this conflicts with the documented priority (config paths should outrank project/user) and can cause config-path skills to be overridden.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin-handlers/command-config-handler.ts">

<violation number="1">
P1: Spread precedence regression: `systemCommands` now overrides project commands/skills due to reordered merge order.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin-handlers/command-config-handler.ts">

<violation number="1">
P2: Spread order now gives project/config-path commands higher precedence than opencode global/system, contradicting documented priority where opencode should override config paths/project. This behavior change can cause global/system commands to be silently overridden on name collisions.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[ventsislav-georgiev]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@ventsislav-georgiev I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

3 issues found across 4 files

Confidence score: 3/5

• There is some risk here because the config resolution logic in src/features/opencode-skill-loader/opencode-config-skills-paths.ts diverges from OpenCode behavior, which can load the wrong skills.paths and affect skill discovery.
• The current implementation returns only the first skills.paths list and ignores later config layers, so additive/merged configs may silently drop entries and change runtime behavior.
• Relative skills.paths from global configs are resolved against the project directory, which can point to incorrect locations when global configs are used.
• Pay close attention to src/features/opencode-skill-loader/opencode-config-skills-paths.ts - config precedence/merging and relative path resolution.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/opencode-skill-loader/opencode-config-skills-paths.ts">

<violation number="1" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:1">
P1: Custom agent: **Opencode Compatibility**

Config search precedence is reversed relative to native OpenCode, which can load the wrong `skills.paths` when both project and `.opencode` configs exist.</violation>

<violation number="2" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:35">
P2: Custom agent: **Opencode Compatibility**

Returns the first `skills.paths` list and ignores the rest of the config layers, which conflicts with OpenCode’s merged/additive config behavior.</violation>

<violation number="3" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:38">
P2: Relative `skills.paths` are resolved against the project directory even when they come from global config files, so global relative entries point to the wrong location.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

3 issues found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/opencode-skill-loader/opencode-config-skills-paths-precedence.test.ts">

<violation number="1" location="src/features/opencode-skill-loader/opencode-config-skills-paths-precedence.test.ts:31">
P2: Incorrect expected path for `.opencode`-scoped relative `skills.paths`; it should resolve under `.opencode`, not the workspace root.</violation>
</file>

<file name="src/features/opencode-skill-loader/opencode-config-skills-paths.ts">

<violation number="1" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:21">
P2: Preferring only one config file per directory means valid `skills.paths` in `opencode.json` are skipped whenever `opencode.jsonc` exists but has no usable paths.</violation>

<violation number="2" location="src/features/opencode-skill-loader/opencode-config-skills-paths.ts:61">
P1: Relative paths from `.opencode/opencode.json` are resolved against `.opencode/` instead of the project root, causing configured skill directories to be missed.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Auto-approved: Additive changes for skill discovery via config. Robust path resolution, comprehensive tests for precedence/JSONC, and no modifications to existing core logic ensure zero regressions.}