From 8606dc4940faf44fd369de26cecd35353f5c9f45 Mon Sep 17 00:00:00 2001 From: Willie Date: Wed, 7 Oct 2026 11:40:51 +0800 Subject: [PATCH] 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 --- cmd/skillshare/doctor_shared_paths.go | 43 ++++++++---- cmd/skillshare/doctor_shared_paths_test.go | 16 +++++ internal/config/targets.go | 68 ++++++++++++++++++- internal/config/targets.yaml | 6 ++ internal/config/targets_test.go | 41 +++++++++++ website/docs/reference/commands/doctor.md | 8 ++- .../current/reference/commands/doctor.md | 8 ++- .../current/reference/commands/doctor.md | 8 ++- .../current/reference/commands/doctor.md | 8 ++- .../current/reference/commands/doctor.md | 8 ++- 10 files changed, 194 insertions(+), 20 deletions(-) diff --git a/cmd/skillshare/doctor_shared_paths.go b/cmd/skillshare/doctor_shared_paths.go index 3c90df936..fa7cc0416 100644 --- a/cmd/skillshare/doctor_shared_paths.go +++ b/cmd/skillshare/doctor_shared_paths.go @@ -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() diff --git a/cmd/skillshare/doctor_shared_paths_test.go b/cmd/skillshare/doctor_shared_paths_test.go index e28ce0ae7..c4e98d9e2 100644 --- a/cmd/skillshare/doctor_shared_paths_test.go +++ b/cmd/skillshare/doctor_shared_paths_test.go @@ -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) diff --git a/internal/config/targets.go b/internal/config/targets.go index 6dcff46e8..86305ff24 100644 --- a/internal/config/targets.go +++ b/internal/config/targets.go @@ -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 diff --git a/internal/config/targets.yaml b/internal/config/targets.yaml index 2cf5bdd62..bf30ecc40 100644 --- a/internal/config/targets.yaml +++ b/internal/config/targets.yaml @@ -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" diff --git a/internal/config/targets_test.go b/internal/config/targets_test.go index 114cb375a..6d53f72c8 100644 --- a/internal/config/targets_test.go +++ b/internal/config/targets_test.go @@ -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) diff --git a/website/docs/reference/commands/doctor.md b/website/docs/reference/commands/doctor.md index f9ccf518e..5014d3880 100644 --- a/website/docs/reference/commands/doctor.md +++ b/website/docs/reference/commands/doctor.md @@ -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. diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index 442e95be2..c3ad163f6 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -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 も確認します。 diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index a104c53e7..78642478c 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -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도 확인합니다. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index a3abc5393..9498dfeb8 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -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。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md index a5defa09f..851e85af0 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/doctor.md @@ -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。