claude-plugins-manager: Skill for Claude Code

update-settings-options

讓 extension 的 settings surface（schema + 衍生 types + UI + i18n + tests + docs + env registry）跟上 Claude Code 目前有哪些設定選項——以官方 docs code.claude.com/docs/en/settings.md 為準，由確定性 CLI 偵測 gap。

Trigger

• sync settings from docs
• update settings options
• Claude settings docs changed

形狀：workflow 探查 → 主迴圈套用

這個 skill 用一個 workflow 跑「探查」，再由主迴圈做「決策 + 套用 + 驗證」。分工不是半套，是兩個硬限制逼出來的：

1. 背景 workflow 不能 AskUserQuestion — section 歸屬的確認必須回主迴圈做。
2. 本 repo 禁止 test/build 併發（見 CLAUDE.md）— workflow 會 fan-out 平行 agent，若在裡面跑 typecheck/test/build 會違反「整台機器同時僅一個」。

所以：workflow 擁有唯讀、可平行、無副作用的部分（跑 CLI 取 gap → 逐 gap 分類），回傳結構化 gap report；主迴圈擁有互動 + 寫檔 + 序列驗證的部分。

Source of truth

• primary：官方 docs code.claude.com/docs/en/settings.md（直接 curl 取 Markdown，確定性 parse）
• env vars：官方 docs code.claude.com/docs/en/env-vars.md（同上）
• 偵測 CLI：scripts/settings-sync-diff.ts（curl live docs → parse → diff against repo schema → 輸出 JSON）。exit 1 = health failure 或 fetch error，workflow 即報錯。
• fail-fast：CLI exit 1 → workflow throw，不 fallback

細節見 references/sources.md。

Key categories

Schema 含多種 key，只有 user-facing 需要進 settings UI。判定準則與完整 excluded 清單以 references/surface-map.md 為準；機器強制排除清單（SSOT）在 src/shared/settings-sync/settings-diff.ts 的 KNOWN_EXCLUDED。

Category	處理
user-facing	同步（按 surface-map 分 section）
anti-direction	同步到現有 AdvancedSection（啟用後違反低成本/高效率/高精度方向）
managed-only	skip → 加入 KNOWN_EXCLUDED
plugin-internal	skip → 加入 KNOWN_EXCLUDED
deprecated	skip → 加入 KNOWN_EXCLUDED
meta	skip → 加入 KNOWN_EXCLUDED

Step 1 — 跑探查 workflow

Workflow({ scriptPath: ".claude/skills/update-settings-options/references/scripts/sync-settings.workflow.js" })

腳本（references/scripts/sync-settings.workflow.js）兩個 phase，全唯讀：

• Detect：一個 agent 跑 Bash npx tsx scripts/settings-sync-diff.ts（cwd repo root），拿回 JSON { settingsGaps, removedKeys, envGaps, envRemoved, counts, health }。四個 diff 方向皆該 CLI 的確定性結果：settingsGaps/removedKeys 已扣掉 KNOWN_EXCLUDED/KNOWN_REPO_ONLY，envRemoved 已扣掉 KNOWN_ENV_REPO_ONLY（docs 記在別頁或僅 prose 提及的 var）；settingsGaps、envGaps 每筆帶 docs 原文 description。CLI exit 1 → 報錯。
• Categorize（平行）：對每個 settingsGap（{key, description}）把 description inline 餵給分類 agent，指派 section（用 surfaceMapHint）、判斷是否 isObjectEditor（需手寫 object editor）、標記 non-user-facing key 需加入 KNOWN_EXCLUDED。removedKeys、envGaps、envRemoved 原樣傳回，不走 LLM 分類——刪除/registry 變更判斷交回主迴圈確認。