shared/skills/spec-model/SKILL.md

name, description

name	description
spec-model	JSC plugins 共用「取得可用模型並加上標籤」規範：固定標籤體系（能力等級／成本／延遲／上下文／用途／可用性）、任務→必要標籤對映表、取得模型清單的權威來源優先序（`claude-api` skill／CLI 自陳／使用痕跡／smoke test）、`~/.claude/jsc/models.json` 快取設計（30 天過期）、強制切換規則，以及讀到帶 `model:` frontmatter 清單檔時的模型檢查義務。當其他 skill 內文引用 spec-model 或 /jsc-shared:spec-model、或需要挑選模型／驗證模型可用性／開啟帶 `model:` frontmatter 的清單檔時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-model — 共用「取得可用模型並加上標籤」規範

所有 JSC skills 需要查詢目前可用哪些模型、為模型加上可供選型決策的標籤、依任務挑選推薦模型，或檢查執行者目前使用的模型是否符合某份清單／某個 skill 的要求時，一律遵守以下規範。

一、標籤體系（固定字彙表，不可自由發揮）

下表為唯一標籤字彙表；新增或改名標籤前一律先改本表，不得在其他 skill 內文自創同義詞。

面向	標籤	判準
能力等級	#深度推理	多步推理、架構設計、跨檔案分析、需求拆解
	#均衡實作	一般編碼、文件重整、規格落地
	#輕量快速	摘要、分類、格式轉換、固定欄位抽取
成本	#高成本 #中成本 #低成本	依當下官方定價分三段，不憑記憶，每次都要查
延遲	#延遲敏感可用	在使用者等待路徑上仍可接受
	#可長時間跑	背景／批次工作
上下文	#長上下文	≥ 1M（如 [1m] 變體）
	#標準上下文	200k 級
用途	#分析 #實作 #審查 #摘要 #對話人格	一個模型可帶多個標籤
可用性	#本機可用	已通過 smoke test
	#不可用	smoke test 失敗（無權限或不存在）
	#未驗證	無法在此 CLI 驗證，只有文件記載

二、任務 → 必要標籤對映表

挑選模型時，先依任務類型找出下表的「必要標籤」——候選模型必須同時具備必要標籤才可推薦；「加分標籤」不具備也可推薦，只是排序上較後。

任務類型	必要標籤	加分標籤
需求分析／拆 TODO／架構決策	#深度推理 #分析 #本機可用	#長上下文
依清單實作／規格落地	#均衡實作 #實作 #本機可用	#中成本
code review／findings 判讀	#深度推理 #審查 #本機可用	—
逐輪摘要（worklog）／分類	#輕量快速 #摘要 #延遲敏感可用 #低成本	—
人格對話	#對話人格 #本機可用	#延遲敏感可用

同一任務有多個候選都滿足必要標籤時，優先挑加分標籤命中較多者；仍並列則挑 verified_at（見〔四、快取設計〕）較新者。

三、取得清單的權威來源優先序

依序取得可用模型清單與其中繼資料（id／定價／上下文長度），前一項可取得就不往下：

1. Claude Code 內建 claude-api skill——模型 id／定價／上下文長度的權威來源，不憑記憶，每次查都要實際載入這個 skill 取得當下資料，不可用過去對話中記得的數字代替。

2. CLI 自陳：

   • Claude Code：claude --help 的 --model 說明列出的 alias（例如 fable／opus／sonnet 這類最新模型別名，實際列出內容以當次 --help 輸出為準，不可硬編碼）。
   • 其他 CLI（codex／opencode／agy／copilot）用各自的列出指令取得；取不到就把該模型標為 #未驗證，不得省略、也不得用其他 CLI 的結果替代。

3. 使用痕跡：~/.claude/stats-cache.json 內 dailyModelTokens／modelUsage 等欄位出現過的模型 id（例如曾實際用過的 claude-opus-5、claude-sonnet-5、claude-haiku-4-5-20251001）。這一層只當補充候選，用來發現前兩層沒列出但實際上帳號可用的模型，不當權威——出現在這裡不代表現在仍可用，仍須走第 4 步驗證。

4. Smoke test 驗證可用性（標準做法，所有候選模型都要跑）：

   CLAUDE_CODE_CHILD_SESSION=1 timeout 45 claude -p 'OK' --model <id>
   

   不可用時 stderr／stdout 會出現「is not a model this version of Claude Code recognizes」或「There's an issue with the selected model」；出現任一即標 #不可用；正常回應則標 #本機可用。

   ⚠️ 必須帶 CLAUDE_CODE_CHILD_SESSION=1，否則會觸發巢狀 session 與 SessionStart hook，汙染 smoke test 結果也可能造成非預期副作用。

四、快取設計

• 路徑：~/.claude/jsc/models.json。
• 每筆模型記錄的欄位：{ id, aliases[], tags[], context, pricing, verified_at, verdict, reason }。
  • id：模型完整 id（如 claude-sonnet-5）。
  • aliases[]：CLI 自陳取得的別名（如 sonnet）。
  • tags[]：依〔一、標籤體系〕貼上的標籤陣列。
  • context：上下文長度（依〔一〕分類為 #長上下文／#標準上下文 的依據數值）。
  • pricing：查證當下的定價摘要（來源為 claude-api skill 或對應 CLI 文件）。
  • verified_at：本筆最後驗證（含 smoke test）的時間，格式依 /jsc-shared:spec-time-log。
  • verdict：本機可用／不可用／未驗證 三者之一，對應〔一〕的可用性標籤。
  • reason：判定 verdict 的簡短依據（例如 smoke test 的錯誤訊息摘要、或「僅文件記載未能於此 CLI 驗證」）。
• 過期規則：verified_at 距今超過 30 天視為過期（沿用 worklog 快取的年限慣例），過期記錄需重新走〔三、取得清單的權威來源優先序〕更新，不得直接沿用。
• 內容邊界（重要）：快取檔只准存模型中繼資料（上述欄位），不得寫入任何工作內容或使用者資料（例如對話內容、專案路徑、議題內容、任何個資）。任何要寫進這份快取的內容，寫入前都要檢查是否落在這個邊界內。

五、強制切換規則（供 /jsc-shared:todo-wiki 與其他 skill 使用）

任何 skill 宣告了必要標籤（依〔二〕的對映表）或直接指定模型時，執行者當前模型不符就停止並要求使用者切換：

• 不得自行降級或升級到別的模型頂替。

• 不得先做一部分再提醒使用者切換——必須在動手前就完成檢查並停下。

• 錯誤訊息格式依 /jsc-shared:spec-time-log 的 [時間][階段][等級]: 訊息：

  [yyyy/MM/dd HH:mm:ss][模型檢查][ERR]: 本清單/本 skill 指定 <model>（<alias>），當前模型為 <current-model-id>。
  請執行 /model <alias> 切換後重新載入，本次不進行任何修改。
  

• 限制：Claude Code 沒有環境變數可讀取當前模型 id，只能以 agent 對自己當下模型的自我回報為準；自我回報不確定時，請使用者執行 /status 確認目前模型後再繼續判斷，不得用猜測代替確認。

六、讀到帶 model: frontmatter 的清單檔時的檢查義務

任何 agent 開啟像 todo.md 這種帶 model: frontmatter 的清單檔時，開始執行清單內容之前都要先依〔五、強制切換規則〕做一次模型檢查：

1. 讀出清單檔 frontmatter 的 model（與可能並列的 model_alias）。
2. 依〔五〕的方式確認當前模型（agent 自我回報，不確定就請使用者 /status 確認）。
3. 兩者不符 → 依〔五〕的錯誤訊息格式停止，不得先執行清單中的任何一項再提醒。
4. 相符才繼續往下執行清單內容。

具體操作步驟（可直接照做，不需另外解讀）：開啟一份 .md 檔案、發現其 YAML frontmatter 含 model 欄位時，在做任何修改前先自我回報目前模型 id，並與 frontmatter 的 model 欄位比對；不符就依〔五、強制切換規則〕的錯誤訊息格式中斷，本次不進行任何修改；相符才繼續往下執行檔案內容。

本節會被 /jsc-shared:todo-wiki（產生指定模型 wiki TODO 頁的 skill）與其他消費這類清單檔的 skill（例如處理 TARGET.md、處理議題 TODO 的 skill）引用，各消費端不必重抄本節內容，直接引用本節即可。