code-review/skills/code-review-action-composite/SKILL.md

---
name: code-review-action-composite
description: 將 Gitea／GitHub「composite action」專案標準化並串接文件化流程：(1) 確認 action 為 composite（`runs.using: composite`），非 composite 則保守確認後對齊；(2) 在 `runs.steps` 最前面注入啟動橫幅 step，輸出 action 名稱／用途／更新時間（Asia/Taipei `yyyy/MM/dd HH:mm:ss`），並於 `action.yml` 開頭補用途／更新時間註解區塊；(3) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說整理 composite action、把 action 標準化為 composite、讓 composite action 啟動時印名稱／用途／更新時間、對 composite action 補文件，或提到 code-review-action-composite 時觸發。不適用於：Docker 容器 action（用 code-review-action-docker）、非 action 專案、或不需文件化的一般 repo。
argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]"
---

# code-review-action-composite — composite action 標準化＋文件化

四階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷是否為 composite），再**確認／對齊為 composite action**，接著在 `runs.steps` 最前面**注入會輸出 action 名稱／用途／更新時間的啟動橫幅 step**，最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。

| 階段 | 動作 |
| --- | --- |
| A. 前置設定與偵測 | 決定 action 根目錄 → 讀 `action.yml`／`action.yaml` 的 `name`／`description`／`runs` → 判斷是否為 composite |
| B. 對齊為 composite | 已是 composite 則保留既有 `steps`；非 composite 則**保守確認後對齊**（高風險，先確認），整理被引用的腳本路徑 |
| C. 注入啟動橫幅 step | 在 `runs.steps` 最前面插入一個 shell step，輸出 action **名稱／用途／更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊 |
| D. 串接 doc-funcs | 對整個 action 專案完整執行 `/jsc:doc-funcs` 流程（function 文件、指令檔逐行註解、重建 README） |

---

## 輸出規範（務必遵守）

- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。
- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：`action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。

---

## 參數

格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]`

- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
- `--manifest <action.yml 路徑>`：指定 action manifest 檔（相對 action 根目錄）。省略時依 A1 自動尋找 `action.yml`／`action.yaml`。
- `--yes`：盡量不中斷。即使帶此參數，「非 composite 需對齊」與 doc-funcs 的「如何實作」仍會詢問。

---

## 階段 A：前置設定與偵測

### A1. 決定 action 根目錄與 manifest

- 帶 `--action-dir` → 採用（展開 `~`）；省略 → 用目前工作目錄。
- manifest：帶 `--manifest` → 採用；否則於根目錄找 `action.yml`，再退而 `action.yaml`。
- **找不到** action manifest → 回報「此目錄不是 action 專案（缺 action.yml／action.yaml）」並詢問正確路徑，**不臆測**、不在非 action 專案上動工。

### A2. 讀取 action 名稱與用途

從 action manifest 讀取：

- `name`：action 名稱（供啟動橫幅與 README 使用）。
- `description`：action 用途。
- `runs`：目前的執行設定（`using`、`steps`、`main`、`image`、`entrypoint` 等）。
- `inputs`／`outputs`：對外契約（後續不得破壞）。

若 `name`／`description` 缺漏，回報並請使用者補；無法取得時於後續輸出以「（未提供）」保守標示，**不編造**。

### A3. 判斷是否為 composite

依 `runs.using` 判定：

- `composite` → 即為目標型態，記下既有 `runs.steps`，直接進入階段 B 的「已是 composite」分支。
- `node*`（JS action）／`docker`（Docker 容器 action）／其他 → 視為**非 composite**。

輸出偵測結果（action 名稱、用途、`runs.using`、是否為 composite、既有 step 數量），再進入階段 B。

> 若偵測為 **Docker 容器 action**，且使用者本意是容器化而非 composite，提醒可改用 `/jsc:code-review-action-docker`，再依使用者裁示決定是否續行。

---

## 階段 B：確認／對齊為 composite action

### B1. 已是 composite

- 確認 `runs.using: composite` 與既有 `runs.steps`，**不更動既有 steps 的順序與邏輯**，直接進入階段 C。
- 順手檢查 step 的必要欄位（`run` step 須有 `shell`；`uses` step 的引用是否存在），有疑慮以回報標註，不擅改。

### B2. 非 composite（需對齊）

這是**破壞性高風險決策**：先以 `AskUserQuestion` 向使用者確認，選項至少含「對齊為 composite」「維持原樣只做文件化（略過對齊）」「改用 code-review-action-docker」「其他」。經確認「對齊為 composite」後才改寫：

- 將 `runs` 保守對齊為 composite，把原執行入口轉為 composite step：
  - 原 JS action（`runs.using: node*`，`runs.main: <x>.js`）→ 轉為一個 `run` step，於 step 內以 `node <x>.js` 執行（`shell: bash`），保留 `inputs`／`outputs` 與環境變數（`INPUT_*`）契約。
  - 原 Docker action（`runs.using: docker`）→ Docker 行為通常無法可靠等價地塞進 composite；**不臆測改寫**，以回報＋`# 需人工確認` 標註，並建議改用 `/jsc:code-review-action-docker`。
- 任何無法可靠等價對齊處，**不臆測**：以 `# 需人工確認：...` 標註並回報，保留原檔行為。

對齊後的 `runs` 形如：

```yaml
runs:
  using: composite
  steps:
    # （階段 C 會在此處最前面插入啟動橫幅 step）
    - name: <原執行入口轉成的 step>
      shell: bash
      run: node ./index.js
```

---

## 階段 C：注入啟動橫幅 step（輸出名稱／用途／更新時間）

在 `runs.steps` **最前面**插入（或更新）一個輸出橫幅的 step，讓 composite action 一啟動就**輸出 action 名稱、用途、更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊。

- **更新時間**為產生此檔當下的時間戳，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。
- 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
- 橫幅 step 須有可辨識的 `name`（如 `顯示 action 資訊`）與 `shell: bash`；其後緊接既有／對齊後的 steps，**不更動既有 steps**。
- 若已存在本 skill 先前插入的橫幅 step（依 `name` 辨識），則**更新**其內容與更新時間，不重複插入。

範例（既有 steps 接在橫幅 step 之後）：

```yaml
name: <action name>
description: <action description>

runs:
  using: composite
  steps:
    # 啟動橫幅：輸出名稱／用途／更新時間（此 step 由 code-review-action-composite 產生）
    - name: 顯示 action 資訊
      shell: bash
      run: |
        echo "================================================"
        echo "Action  : <action name>"
        echo "用途    : <action description>"
        echo "更新時間: 2026/06/30 18:30:05"
        echo "================================================"
    # === 以下為既有／對齊後的 steps（保持原順序與邏輯）===
    - name: <既有 step>
      shell: bash
      run: node ./index.js
```

- `action.yml` 開頭的「用途／更新時間」註解區塊與每行註解，最終會在階段 D 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式（用途與更新日期同一註解區塊、逐行註解）；本階段先確保**執行期橫幅輸出**正確即可。
- 自我檢查：插入橫幅 step 後 YAML 仍可解析（縮排、`steps` 為 list、每個 `run` step 都有 `shell`），且 `inputs`／`outputs` 未被更動。

---

## 階段 D：完整執行 /jsc:doc-funcs 處理流程

標準化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：

- 以階段 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`（含台灣時區更新時間、專案列表、功能列表、使用範例）。

> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。

---

## 總結

各階段執行後輸出：

- **階段 A**：action 根目錄、manifest 路徑、action 名稱／用途、`runs.using`、是否為 composite、既有 step 數量。
- **階段 B**：是否對齊為 composite（及對齊摘要與「需人工確認」清單），或維持原樣的理由。
- **階段 C**：橫幅 step 的輸出內容（名稱／用途／更新時間）與插入位置，並確認既有 steps、`inputs`／`outputs` 未被破壞。
- **階段 D**：doc-funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `action.yml` 可正常解析、composite action 能正確啟動並輸出橫幅。

---

## 呼叫方式

格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]` — 全部可省略（根目錄預設目前工作目錄；manifest 自動尋找）。

| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc:code-review-action-composite`，或 `/jsc:code-review-action-composite --action-dir ~/work/my-action` |
| Codex | `$code-review-action-composite`，或 `$code-review-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單 |
| OpenCode | 描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |