4.5 KiB
name, description
| name | description |
|---|---|
| spec-script-path | JSC plugins 共用「plugin 內腳本路徑解析」規範：Claude Code 用 `${CLAUDE_PLUGIN_ROOT}`、其他助理用 skill 載入時提示的 base directory 往上兩層推導出 plugin 根目錄，絕不可用相對路徑呼叫腳本，解析不到就回報並停止。當其他 skill 內文引用 spec-script-path 或 /jsc-shared:spec-script-path、或需要呼叫 plugin 內 `scripts/` 下的腳本時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 |
spec-script-path — 共用 plugin 內腳本路徑解析
skill 執行時的工作目錄是使用者的專案目錄，不是 plugin 根目錄，因此絕不可用相對路徑呼叫 plugin 內的腳本。所有 JSC skill 呼叫 scripts/ 下的腳本前，一律先依本節解析出 plugin 根目錄，再組成絕對路徑。
核心規則：plugin 根目錄解析
| 環境 | plugin 根目錄 |
|---|---|
| Claude Code | ${CLAUDE_PLUGIN_ROOT} |
| 其他助理 | 本 skill 載入時提示的 base directory（形如 .../skills/<skill-name>）往上兩層 |
- Claude Code 有現成環境變數可直接取用；其他助理沒有這個變數，只能從「skill 被載入時系統提示的 base directory」往上推導——
skills/<skill-name>往上兩層即為 plugin 根目錄（<base>/../..）。 - 兩種環境推導出的路徑指向同一個 plugin 根目錄，只是取得方式不同，接到
scripts/...之後即為腳本絕對路徑。
鐵則：絕不用相對路徑重試
- 一律使用上面解析出的絕對路徑呼叫腳本；不可因為解析失敗就退回用相對路徑（例如
./scripts/xxx或../scripts/xxx）試著呼叫——工作目錄是使用者專案目錄，相對路徑幾乎必定指向錯誤位置，靜默失敗或誤動作都比明確報錯更危險。 - 解析出的路徑要實際指向存在的目錄／檔案才算解析成功，不可只組出字串就當作可用。
解析不到時的標準錯誤處理
解析不到 plugin 根目錄，或組出的路徑下不存在對應的 scripts/ 內容時：
- 回報「plugin 目錄未包含 scripts/xxx，本 skill 在此環境不可用」（
xxx替換為實際缺少的腳本或目錄名）。 - 停止該 skill 的後續流程，不要改用相對路徑重試，也不要臆測其他路徑。
兩種合規寫法
以下兩種表達方式都符合本規範，各 skill 可依自身複雜度（是否只呼叫一個固定 CLI、或需要組多個腳本路徑）自由選用。
寫法一：多行版（適合需要說明推導細節、或腳本路徑本身會被多處引用的 skill）
# Claude Code
WORKLOG_DIR="${CLAUDE_PLUGIN_ROOT}/scripts/worklog"
# 其他助理：以 skill base directory 推導（<base>/../.. 即 plugin 根）
WORKLOG_DIR="<skill base directory>/../../scripts/worklog"
之後全文以 ${WORKLOG_DIR} 表示該目錄，不重複解析。若解析不到或該目錄不存在，回報「plugin 目錄未包含 scripts/worklog，本 skill 在此環境不可用」並停止。
（範例出處：doc/skills/worklog/SKILL.md 的「腳本路徑解析（重要）」一節。）
寫法二：單行 CLI 宣告版（適合整個 skill 只圍繞單一 CLI 腳本的情況）
**CLI**：路徑與呼叫慣例見 `/jsc-shared:spec-script-path`（本 skill 為 `node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs"`，一律帶 `--session <PERSONA_SESSION>`）。
之後全文的指令範例一律以 node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" <子指令> 的形式呈現；其他助理讀到這行時，依核心規則表格自行把 ${CLAUDE_PLUGIN_ROOT} 換成 base directory 往上兩層推導出的路徑。這一行只點出「本 skill 實際用哪支腳本、需不需要額外參數（如 --session）」，推導規則與絕不用相對路徑等鐵則一律回頭看本節，不在每個 skill 裡重複解釋。
（範例出處：persona/skills/persona-chat/SKILL.md、persona/skills/persona-create/SKILL.md 等 12 個 persona skill 開頭的 **CLI**： 宣告行，皆已收斂為此單行格式。）
兩種寫法本質是同一套「Claude Code 用環境變數、其他助理用 base directory 推導」規則的不同表達密度——寫法一把推導過程完整展開並存進一個變數方便全文引用，寫法二把推導過程收進一行宣告、後續直接照抄同一行指令模板。兩者都必須保留「絕不用相對路徑」與「解析不到就回報並停止」這兩條鐵則，不可省略。