refactor(skills 共用規範): 抽出共用規範至 generic spec-*，以引用＋一行 fallback 摘要取代重複內容

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

skills/code-action-composite/SKILL.md

@@ -17,32 +17,28 @@ argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑
 
 ---
 
-## 輸出規範（務必遵守）
+## 共用規範（generic plugin，必要前置）
 
-- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、git 指令、API 路徑、YAML 鍵名、程式碼等技術標識保留原文，**不可**使用簡體字。
-- **編碼無亂碼**：凡輸出含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。產生／覆寫的 `action.yml`／`action.yaml`、被引用腳本、`README.md` 同樣需 UTF-8（不含 BOM）。
-- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策，否則各階段只需輸出簡短計畫／進度後直接執行到完成。**一定會中斷詢問的點**：階段 B 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
-- **不破壞既有工作**：改寫 `action.yml`／搬移或改寫被引用腳本前，若工作區有未提交變更，先提醒使用者建議先 commit／備份；**絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼。移動檔案優先用 `git mv` 以保留歷史。
-- **保留行為**：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 `steps` 的執行順序、輸入（`inputs`）／輸出（`outputs`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依「參數來源優先序」經使用者同意後為之。
-- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：`action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
+執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
+
+- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
+- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
+- `/jsc:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）、`git mv` 保留歷史。
+- `/jsc:spec-action-params`：action 參數來源優先序（context → 經同意新增 `inputs`）、`secrets`／`vars` 一律視為不可用。
+- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、完成後統一同步時間戳。
+- `/jsc:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc:doc-funcs` 的標準流程。
+
+本 skill 特有補充：
+
+- **一定會中斷詢問的點**：階段 B 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
+- **保留行為**：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 `steps` 的執行順序、輸入（`inputs`）／輸出（`outputs`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc:spec-action-params` 經使用者同意後為之。
+- **本 skill 只動**：action 專案根目錄內的 `action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標。
 
 ---
 
 ## 參數來源優先序（開發中需要新參數時）
 
-從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，依下列順序處理，**前一項可取得就不往下**：
-
-1. **`${{ gitea.* }}`／`${{ github.* }}` context**：在 Gitea composite action 的 `runs.steps` 內**可直接使用**（Gitea 中 `gitea` 與 `github` context 互為別名）。常用如 `github.repository`、`github.ref_name`、`github.server_url`、`github.token`、`github.event.*`。為同時相容 GitHub Actions，composite action 內建議寫 `github.*`（Gitea 亦支援）；確定只跑 Gitea 的專案可用 `gitea.*`。`run` 腳本內可改讀同源的執行期環境變數（`$GITHUB_REPOSITORY`、`$GITHUB_SERVER_URL`、`$GITHUB_REF_NAME` 等）。
-2. **context 無法取得 → 詢問使用者新增 `inputs`**：以 `AskUserQuestion` 詢問使用者是否新增對應 `input`（名稱／description／`required`／`default`），經同意後於 `inputs` 宣告並在 step 內以 `${{ inputs.<name> }}` 取用；未經同意**不得**擅自更動 `inputs`／`outputs` 契約。
-
-**secrets／vars 一律視為不可用，不列入優先序**：`${{ secrets.* }}`／`${{ vars.* }}` context 在 composite action 的 `action.yml` 內於 GitHub 為**官方明文不可用**（composite action 取不到 `secrets`／`vars` context，`inputs` 的 `default` 也不能引用）；Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。為求兩邊相容，本 skill 一律視為不可用——參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 `input`，回報時附上呼叫端 workflow 的傳入寫法：
-
-```yaml
-- uses: <owner>/<action>@<ref>
-  with:
-    token: ${{ secrets.MY_TOKEN }}     # secrets 由呼叫端 workflow 傳入
-    registry: ${{ vars.MY_REGISTRY }}  # vars 亦同
-```
+從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，一律依 `/jsc:spec-action-params` 的優先序處理：composite 的 `runs.steps` 內優先取 `${{ gitea.* }}`／`${{ github.* }}` context（建議寫 `github.*` 以相容兩邊；`run` 腳本內可改讀 `$GITHUB_*` 環境變數），取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端 workflow 傳入（範例見該 spec）。
 
 ---
 
@@ -146,7 +142,7 @@ runs:
 
 在 `runs.steps` **最前面**插入（或更新）一個輸出橫幅的 step，讓 composite action 一啟動就**輸出 action 名稱、用途、更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊。
 
-- **更新時間**語意為「本檔最後由本 skill 產生／更新的時間」，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。本階段先寫入暫定時間戳，**階段 D 完成後會統一同步各處時間戳**（見階段 D）。
+- **更新時間**依 `/jsc:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 D 完成後會統一同步各處時間戳**（見階段 D）。
 - 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
 - 橫幅 step 須有可辨識的 `name`（如 `顯示 action 資訊`）與 `shell: bash`；其後緊接既有／對齊後的 steps，**不更動既有 steps**。
 - 若已存在本 skill 先前插入的橫幅 step（依 `name` 辨識），則**更新**其內容與更新時間，不重複插入。
@@ -182,16 +178,7 @@ runs:
 
 ## 階段 D：完整執行 /jsc:doc-funcs 處理流程
 
-標準化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
-
-- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
-- 以階段 A1 的 action 根目錄為目標，執行 `doc-funcs` skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
-- doc-funcs 會把 `action.yml`／`action.yaml` 視為 CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 內引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。
-- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
-- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
-- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步橫幅 step 內文、`action.yml` 開頭註解區塊與 README 的更新時間，**確保各處時間戳一致**。
-
-> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。
+標準化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README）。完成後依該 spec **統一時間戳**：回頭同步橫幅 step 內文、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
 
 ---