feat(doctor): honor OpenCode switches that turn off external skills

With OPENCODE_DISABLE_CLAUDE_CODE_SKILLS set, OpenCode does not read
.claude/skills, yet doctor still warned that skills leak in through
it, so a user who had already fixed the leak could never clear the
warning.

Record in targets.yaml which environment variables turn off each
also_scans folder and skip those folders in RuntimeScanPaths when a
variable is true in skillshare's environment, read the way OpenCode
reads it. doctor, sync, the dashboard and readsFrom then agree, and
doctor says which variable caused the skip, because OpenCode may run
with another environment. The doctor hint now comes from the same
table.

Refs #458
This commit is contained in:
Willie
2026-10-07 11:40:51 +08:00
parent 211efa0ee6
commit 8606dc4940
10 changed files with 194 additions and 20 deletions
+29 -14
View File
@@ -2,6 +2,7 @@ package main
import (
"fmt"
"maps"
"path/filepath"
"slices"
"sort"
@@ -42,24 +43,24 @@ func crossTargetDiscoverySuggestion(scanner string, writers []string, isProject
scanner, scanner, strings.Join(writers, ", "), scanner, targetRemoveDryRunCommand(isProject), strings.Join(writers, ", "))
}
// scanOffHint says how a runtime can stop reading the given folders of other
// targets, or "" when that is not known.
func scanOffHint(scanner string, paths []string) string {
if scanner != "opencode" {
// scanOffHint names the most specific environment variable that makes the
// runtime skip every one of paths, or "" when none does.
func scanOffHint(scanner string, paths []string, isProject bool) string {
if len(paths) == 0 {
return ""
}
for _, p := range paths {
// OPENCODE_DISABLE_CLAUDE_CODE_SKILLS leaves .agents/skills loaded.
if filepath.Base(filepath.Dir(p)) == ".agents" {
return "set OPENCODE_DISABLE_EXTERNAL_SKILLS=1 to skip .claude/skills and .agents/skills"
disabledBy := config.AlsoScansDisabledBy(scanner, isProject)
for _, v := range disabledBy[paths[0]] {
if !slices.ContainsFunc(paths[1:], func(p string) bool { return !slices.Contains(disabledBy[p], v) }) {
return "set " + v + "=1"
}
}
return "set OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 to skip .claude/skills, or OPENCODE_DISABLE_EXTERNAL_SKILLS=1 to also skip .agents/skills"
return ""
}
func leakedSkillsSuggestion(scanner string, paths []string) string {
func leakedSkillsSuggestion(scanner string, paths []string, isProject bool) string {
s := fmt.Sprintf("Sync leaves these skills out of %s's folder, but %s also reads other targets' folders. Allow them for %s", scanner, scanner, scanner)
if hint := scanOffHint(scanner, paths); hint != "" {
if hint := scanOffHint(scanner, paths, isProject); hint != "" {
s += ", or where " + scanner + " runs, " + hint
}
return s + "."
@@ -154,6 +155,20 @@ func checkCrossTargetDiscovery(cfg *config.Config, result *doctorResult, isProje
writersByPath[path] = append(writersByPath[path], name)
}
// Say which written folders a runtime skips because of this environment:
// the runtime may run with another one.
var skipped []string
for _, scanner := range slices.Sorted(maps.Keys(primaryByName)) {
for _, s := range config.ScansTurnedOff(scanner, isProject) {
if _, written := writersByPath[filepath.Clean(s.Path)]; !written {
continue
}
note := fmt.Sprintf("%s skips %s: %s is set in this environment", scanner, shortenPath(s.Path), s.EnvVar)
ui.Note(note)
skipped = append(skipped, note)
}
}
type pathOverlap struct {
sharedPath string
writers []string
@@ -209,7 +224,7 @@ func checkCrossTargetDiscovery(cfg *config.Config, result *doctorResult, isProje
}
if len(overlapsByScanner) == 0 {
result.addCheck("cross_target_discovery", checkPass, "No cross-target discovery overlap", nil)
result.addCheck("cross_target_discovery", checkPass, "No cross-target discovery overlap", skipped)
return
}
@@ -220,7 +235,7 @@ func checkCrossTargetDiscovery(cfg *config.Config, result *doctorResult, isProje
}
sort.Strings(scannerNames)
var details []string
details := skipped
var suggestions []string
for _, name := range scannerNames {
so := overlapsByScanner[name]
@@ -254,7 +269,7 @@ func checkCrossTargetDiscovery(cfg *config.Config, result *doctorResult, isProje
details = append(details, fmt.Sprintf("%s (%s) also scans %s ← %s and loads skills its filters leave out: %s",
so.scanner, so.scannerPath, p.sharedPath, strings.Join(p.writers, ", "), strings.Join(p.leaked, ", ")))
}
suggestion := leakedSkillsSuggestion(so.scanner, leakPaths)
suggestion := leakedSkillsSuggestion(so.scanner, leakPaths, isProject)
ui.Note("suggestion: " + suggestion)
suggestions = append(suggestions, suggestion)
result.addWarning()
@@ -225,6 +225,22 @@ func TestCheckCrossTargetDiscovery_OpenCodeNamesLeakedSkills(t *testing.T) {
}
}
func TestCheckCrossTargetDiscovery_OpenCodeEnvOffPassesWithNote(t *testing.T) {
cfg := opencodeAndClaude(t)
t.Setenv("OPENCODE_DISABLE_CLAUDE_CODE_SKILLS", "1")
r := &doctorResult{}
checkCrossTargetDiscovery(cfg, r, false, []sync.DiscoveredSkill{
{FlatName: "claude-only", Targets: []string{"claude"}},
})
if r.warnings != 0 || r.checks[0].Status != checkPass {
t.Fatalf("expected a passing check, got %+v", r.checks)
}
if d := strings.Join(r.checks[0].Details, "\n"); !strings.Contains(d, "OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set") {
t.Errorf("details %q do not say why ~/.claude/skills is skipped", d)
}
}
func TestCheckCrossTargetDiscovery_OpenCodeAgentsLeakOnlySuggestsExternalOff(t *testing.T) {
// OPENCODE_DISABLE_CLAUDE_CODE_SKILLS leaves .agents/skills loaded.
cfg := opencodeAndClaude(t)
+67 -1
View File
@@ -27,6 +27,9 @@ type targetPathPair struct {
type targetAlsoScans struct {
Global []string `yaml:"global,omitempty"`
Project []string `yaml:"project,omitempty"`
// DisabledByEnv maps an also_scans path to the environment variables that
// make the runtime skip it, most specific first.
DisabledByEnv map[string][]string `yaml:"disabled_by_env,omitempty"`
}
// targetInstructions is the instruction file (CLAUDE.md, AGENTS.md, ...) a
@@ -348,6 +351,65 @@ func AlsoScansProject(name string) []string {
return nil
}
// ScanOff is an also_scans path a target's runtime skips because EnvVar is set.
type ScanOff struct {
Path string
EnvVar string
}
// AlsoScansDisabledBy returns, per also_scans path (normalised like
// AlsoScansGlobal/AlsoScansProject), the environment variables that make the
// target's runtime skip it, most specific first.
func AlsoScansDisabledBy(name string, isProject bool) map[string][]string {
specs, err := loadTargetSpecs()
if err != nil {
return nil
}
for _, spec := range specs {
if spec.Name != name {
continue
}
raw := spec.AlsoScans.Global
if isProject {
raw = spec.AlsoScans.Project
}
out := make(map[string][]string)
for _, p := range raw {
if vars := spec.AlsoScans.DisabledByEnv[p]; len(vars) > 0 {
out[normalizeTargetPath(p)] = vars
}
}
return out
}
return nil
}
// ScansTurnedOff returns the also_scans paths an environment variable of this
// process turns off. It assumes the runtime sees the same environment.
func ScansTurnedOff(name string, isProject bool) []ScanOff {
var off []ScanOff
for path, vars := range AlsoScansDisabledBy(name, isProject) {
for _, v := range vars {
if envTrue(os.Getenv(v)) {
off = append(off, ScanOff{Path: path, EnvVar: v})
break
}
}
}
sort.Slice(off, func(i, j int) bool { return off[i].Path < off[j].Path })
return off
}
// envTrue reports whether v is a true value as OpenCode's flags read it
// (Effect's Config.boolean).
func envTrue(v string) bool {
switch v {
case "true", "yes", "on", "1", "y":
return true
}
return false
}
// DetectDir returns the install directory that identifies a target's tool,
// tilde-expanded and OS-normalised. Returns "" for unknown targets or targets
// without detect metadata (their skills path already identifies them).
@@ -379,11 +441,15 @@ func RuntimeScanPaths(name string, isProject bool) []string {
scans = AlsoScansGlobal(name)
primary = DefaultTargets()[name].Path
}
off := make(map[string]bool)
for _, s := range ScansTurnedOff(name, isProject) {
off[s.Path] = true
}
paths := make([]string, 0, len(scans)+1)
seen := make(map[string]bool, len(scans)+1)
for _, p := range scans {
if p == "" || seen[p] {
if p == "" || seen[p] || off[p] {
continue
}
seen[p] = true
+6
View File
@@ -448,6 +448,12 @@ targets:
also_scans:
global: ["~/.claude/skills", "~/.agents/skills"]
project: [".claude/skills", ".agents/skills"]
# packages/opencode/src/effect/runtime-flags.ts; most specific first.
disabled_by_env:
"~/.claude/skills": [OPENCODE_DISABLE_CLAUDE_CODE_SKILLS, OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_EXTERNAL_SKILLS]
"~/.agents/skills": [OPENCODE_DISABLE_EXTERNAL_SKILLS]
".claude/skills": [OPENCODE_DISABLE_CLAUDE_CODE_SKILLS, OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_EXTERNAL_SKILLS]
".agents/skills": [OPENCODE_DISABLE_EXTERNAL_SKILLS]
instructions:
global: "~/.config/opencode/AGENTS.md"
project: "AGENTS.md"
+41
View File
@@ -236,6 +236,47 @@ func TestRuntimeScanPaths_UnionOfAlsoScansAndPrimary(t *testing.T) {
}
}
func TestRuntimeScanPaths_SkipsPathTurnedOffByEnv(t *testing.T) {
t.Setenv("OPENCODE_DISABLE_CLAUDE_CODE_SKILLS", "1")
got := RuntimeScanPaths("opencode", false)
if slices.Contains(got, normalizeTargetPath("~/.claude/skills")) {
t.Errorf("RuntimeScanPaths(opencode) = %v, want ~/.claude/skills skipped", got)
}
if !slices.Contains(got, normalizeTargetPath("~/.agents/skills")) {
t.Errorf("RuntimeScanPaths(opencode) = %v, want ~/.agents/skills kept", got)
}
}
func TestRuntimeScanPaths_ExternalSkillsOffSkipsBothProjectPaths(t *testing.T) {
t.Setenv("OPENCODE_DISABLE_EXTERNAL_SKILLS", "true")
got := RuntimeScanPaths("opencode", true)
if len(got) != 1 || filepath.ToSlash(got[0]) != ".opencode/skills" {
t.Errorf("RuntimeScanPaths(opencode, project) = %v, want only .opencode/skills", got)
}
}
func TestRuntimeScanPaths_KeepsPathWhenEnvIsFalse(t *testing.T) {
t.Setenv("OPENCODE_DISABLE_CLAUDE_CODE_SKILLS", "0")
if got := RuntimeScanPaths("opencode", false); !slices.Contains(got, normalizeTargetPath("~/.claude/skills")) {
t.Errorf("RuntimeScanPaths(opencode) = %v, want ~/.claude/skills kept", got)
}
}
// A disabled_by_env key that is not an also_scans path would never apply.
func TestAlsoScans_DisabledByEnvKeysAreScannedPaths(t *testing.T) {
specs, err := loadTargetSpecs()
if err != nil {
t.Fatalf("loadTargetSpecs: %v", err)
}
for _, spec := range specs {
for path := range spec.AlsoScans.DisabledByEnv {
if !slices.Contains(spec.AlsoScans.Global, path) && !slices.Contains(spec.AlsoScans.Project, path) {
t.Errorf("%s: disabled_by_env key %q is not in also_scans", spec.Name, path)
}
}
}
}
func TestRuntimeScanPaths_Deduplicates(t *testing.T) {
// warp's primary path is ~/.agents/skills and it has no also_scans.
got := RuntimeScanPaths("warp", false)
+7 -1
View File
@@ -173,7 +173,13 @@ OpenCode keeps one skill per name across `~/.claude/skills`, `~/.agents/skills`,
~/.claude/skills ← claude: claude-only
```
Resolution: allow those skills for `opencode`, or set `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1` (or `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`, which also skips `.agents/skills`) where OpenCode runs. `doctor` cannot see OpenCode's environment, so the warning stays after you set either variable.
Resolution: allow those skills for `opencode`, or set `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1` (or `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`, which also skips `.agents/skills`) where OpenCode runs. skillshare only sees its own environment: when the variable is also set where you run skillshare, `doctor`, `sync`, and the dashboard treat that folder as skipped, and `doctor` notes it:
```text
opencode skips ~/.claude/skills: OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set in this environment
```
If OpenCode starts with a different environment, for example from a desktop launcher, set the variable there as well.
`shared_target_paths` reads configured paths only. `cross_target_discovery` also reads the built-in `also_scans` table, and for `opencode` the skills each target receives.
@@ -173,7 +173,13 @@ OpenCode は `~/.claude/skills`、`~/.agents/skills`、自分のフォルダの
~/.claude/skills ← claude: claude-only
```
対処:その skill を `opencode` にも許可するか、OpenCode を実行する環境で `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(`.agents/skills` も読まない場合は `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`)を設定します。`doctor` からは OpenCode の環境が見えないため、設定後も警告は表示されます。
対処:その skill を `opencode` にも許可するか、OpenCode を実行する環境で `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(`.agents/skills` も読まない場合は `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`)を設定します。skillshare が見えるのは自分の環境だけです。skillshare を実行する環境でもこの変数を設定すると、`doctor`、`sync`、dashboard はそのフォルダを読まれないものとして扱い、`doctor` はその旨を表示します:
```text
opencode skips ~/.claude/skills: OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set in this environment
```
OpenCode を別の環境(デスクトップのランチャーなど)から起動する場合は、そちらでも変数を設定してください。
`shared_target_paths` は設定済みのパスだけを読みます。`cross_target_discovery` は組み込みの `also_scans` テーブルも読み、`opencode` については各 target が受け取る skill も確認します。
@@ -173,7 +173,13 @@ OpenCode는 `~/.claude/skills`, `~/.agents/skills`, 자신의 폴더 사이에
~/.claude/skills ← claude: claude-only
```
해결: 해당 skill을 `opencode`에도 허용하거나, OpenCode를 실행하는 환경에 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(`.agents/skills`도 건너뛰려면 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`)을 설정합니다. `doctor`는 OpenCode의 환경을 볼 수 없으므로 설정한 뒤에도 경고는 계속 표시됩니다.
해결: 해당 skill을 `opencode`에도 허용하거나, OpenCode를 실행하는 환경에 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(`.agents/skills`도 건너뛰려면 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`)을 설정합니다. skillshare는 자신의 환경만 볼 수 있습니다. skillshare를 실행하는 환경에도 이 변수를 설정하면 `doctor`, `sync`, dashboard는 해당 폴더를 건너뛴 것으로 처리하고, `doctor`는 이를 표시합니다:
```text
opencode skips ~/.claude/skills: OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set in this environment
```
OpenCode를 다른 환경(예: 데스크톱 런처)에서 실행한다면 그쪽에도 변수를 설정하세요.
`shared_target_paths`는 구성된 경로만 읽습니다. `cross_target_discovery`는 내장된 `also_scans` 테이블도 읽고, `opencode`의 경우 각 target이 받는 skill도 확인합니다.
@@ -177,7 +177,13 @@ OpenCode 在 `~/.claude/skills`、`~/.agents/skills` 和自己的文件夹之间
~/.claude/skills ← claude: claude-only
```
解决方法:让 `opencode` 也能拿到这些 skill,或在运行 OpenCode 的环境设置 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(或 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,连 `.agents/skills` 也跳过)。`doctor` 看不到 OpenCode 的环境,所以设置后警告仍会出现。
解决方法:让 `opencode` 也能拿到这些 skill,或在运行 OpenCode 的环境设置 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(或 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,连 `.agents/skills` 也跳过)。skillshare 只看得到自己的环境:运行 skillshare 的环境也设置了这个变量时,`doctor`、`sync` 和 dashboard 会把该文件夹当成已跳过,`doctor` 也会注明:
```text
opencode skips ~/.claude/skills: OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set in this environment
```
如果 OpenCode 是从其他环境启动(例如桌面快捷方式),那边也要设置这个变量。
`shared_target_paths` 只读取已配置的路径。`cross_target_discovery` 也会读内置的 `also_scans` 表,对 `opencode` 还会看每个 target 拿到哪些 skill。
@@ -173,7 +173,13 @@ OpenCode 在 `~/.claude/skills`、`~/.agents/skills` 和自己的資料夾之間
~/.claude/skills ← claude: claude-only
```
解決方式:讓 `opencode` 也能拿到這些 skill,或在執行 OpenCode 的環境設定 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(或 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,連 `.agents/skills` 也略過)。`doctor` 看不到 OpenCode 的環境,所以設定後警告仍會出現。
解決方式:讓 `opencode` 也能拿到這些 skill,或在執行 OpenCode 的環境設定 `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`(或 `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,連 `.agents/skills` 也略過)。skillshare 只看得到自己的環境:執行 skillshare 的環境也設定了這個變數時,`doctor`、`sync` 和 dashboard 會把該資料夾當成已略過,`doctor` 也會註明:
```text
opencode skips ~/.claude/skills: OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is set in this environment
```
如果 OpenCode 是從其他環境啟動(例如桌面捷徑),那邊也要設定這個變數。
`shared_target_paths` 只讀取已設定的路徑。`cross_target_discovery` 也會讀內建的 `also_scans` 表,對 `opencode` 還會看每個 target 拿到哪些 skill。