docs(助理適用範圍): 補元件適用矩陣、OpenCode 限制與可執行元件注意事項

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -8,6 +8,7 @@
 - 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
 - **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。
 - 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
+- 部分 skill 帶可執行元件（`scripts/`）或 hook（`hooks/hooks.json`），**並非四家助理都適用**；載入前請看該 skill `description` 標示的支援範圍與 `README.md` 的「元件對各助理的適用範圍」。`hooks/hooks.json` 只有 Claude Code 會讀；以複製 `skills/` 目錄安裝的環境（OpenCode）不會帶入 `scripts/`，依賴腳本的 skill 一律不可用。
 
 ## 慣例
 

README.md

@@ -48,7 +48,19 @@ generic/
 └── README.md
 ```
 
-> generic 的定位是「**共用規範 ＋ 全域自動化**」：`skills/spec-*` 是純規範文件（四家助理通用），`hooks/` 與 `scripts/` 是可執行元件。**`hooks/hooks.json` 只有 Claude Code 會讀**；Codex／Antigravity／OpenCode 匯入時只有 skill 可用，自動記錄不會啟動。
+> generic 的定位是「**共用規範 ＋ 全域自動化**」：`skills/spec-*` 是純規範文件（四家助理通用），`hooks/` 與 `scripts/` 是可執行元件。
+
+### 元件對各助理的適用範圍
+
+| 元件 | Claude Code | Codex | Antigravity | OpenCode |
+| --- | --- | --- | --- | --- |
+| `skills/spec-*`（十個共用規範） | ✅ | ✅ | ✅ | ✅ |
+| `skills/worklog` 的手動模式 | ✅ | ⚠️ 需安裝後保留 `scripts/`（請實測一次） | ⚠️ 同左 | ❌ 不支援 |
+| `hooks/hooks.json`（`Stop` 自動記錄） | ✅ | ❌ | ❌ | ❌ |
+
+- **`hooks/hooks.json` 只有 Claude Code 會讀**。且 `scripts/worklog/worklog.sh` 解析的是 **Claude Code 專屬的 transcript JSONL 結構**，即使其他助理提供等效 hook，自動記錄也不能直接沿用。
+- **OpenCode 不支援 worklog**：OpenCode 以「複製 `skills/` 目錄」安裝，不會帶入 `scripts/`，worklog 的所有模式都無法執行（已在該 skill 的 `description` 標明）。
+- Claude Code 的 plugin cache 是完整 repo clone，`scripts/`（含 `100755` 執行權限）與 `hooks/` 都會帶入；Codex／Antigravity 的安裝目錄是否同樣保留 `scripts/` 尚未實測，第一次安裝後請跑 `/jsc:worklog --diagnose` 確認。
 
 ---
 
@@ -136,10 +148,12 @@ cp -r ~/plugins/generic/skills/* ~/.config/opencode/skills/
 git -C ~/plugins/generic pull
 cp -r ~/plugins/generic/skills/* ~/.config/opencode/skills/
 
-# 移除
+# 移除（逐一移除本 plugin 帶入的 skill 目錄；勿只清 spec-*，否則其他 skill 會殘留）
-rm -rf ~/.config/opencode/skills/spec-*
+for s in ~/plugins/generic/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"; done
 ```
 
+> **worklog 在 OpenCode 不可用**：上面的複製只帶 `skills/`，不含 `scripts/`，worklog 的所有模式都會失敗。請不要在 OpenCode 觸發該 skill（其 `description` 已標明不支援）。
+
 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
 
 - **呼叫**：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。
@@ -192,7 +206,7 @@ rm -rf ~/.config/opencode/skills/spec-*
 
 | Skill | 類型 | 內容 |
 | --- | --- | --- |
-| `worklog` | 工作證明記錄 | 每輪工作濃縮成條目追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）；`--init`／`--tune`／`--diagnose`／`--append`／`--show` 五個模式；自動記錄由 Claude Code `Stop` hook 完成 |
+| `worklog` | 工作證明記錄 | 每輪工作濃縮成條目追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）；`--init`／`--tune`（Claude Code 專屬）／`--diagnose`／`--append`／`--show` 五個模式；自動記錄由 Claude Code `Stop` hook 完成，**OpenCode 不支援**（見上方適用範圍表） |
 
 <!-- JSC-SKILLS:END -->
 
@@ -210,5 +224,12 @@ rm -rf ~/.config/opencode/skills/spec-*
 6. 讓各助理更新：
    - Claude：`claude plugin update jsc@generic`
    - Codex：`codex plugin marketplace upgrade generic`
-   - Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc && agy plugin install ~/jsc-plugin`
+   - Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致）
    - OpenCode：`git pull` 後重新複製 `skills/`
+
+> **skill 帶可執行元件時**（腳本、hook）額外注意：
+>
+> - 腳本放 `scripts/<skill-name>/`，**不要**放進 `skills/`；hook 定義放 `hooks/hooks.json`，command 用 `${CLAUDE_PLUGIN_ROOT}/...` 絕對路徑。
+> - 腳本要有執行權限並確實入 git（`git ls-files -s` 應顯示 `100755`）。
+> - `SKILL.md` **不可用相對路徑呼叫腳本** —— skill 執行時的工作目錄是使用者的專案目錄；請以 `${CLAUDE_PLUGIN_ROOT}`（其他助理用 skill base directory 往上兩層）組出絕對路徑。
+> - 在 `SKILL.md` 的 `description` 與上方適用範圍表標明支援哪幾家；OpenCode 因只複製 `skills/`，凡依賴 `scripts/` 的 skill 一律不支援。