---
name: spec-plugin-cli
description: JSC plugins 共用「五種助理 plugin 安裝／更新／移除指令」規範：Claude Code、Codex、Antigravity（agy）、OpenCode、GitHub Copilot CLI 各自的 marketplace add／plugin install／plugin update／plugin uninstall 完整指令語法，以 <host>/<name>/<plugin>/<marketplace>/<token>/<url> 佔位符套用到任一 JSC plugin repo（code／doc／persona／shared），本機開發（免 push）的本地路徑一律用 %USERPROFILE%\...／$HOME/... 佔位符示範，不得寫死真實使用者帳號路徑。當其他 skill 或 README 內文引用 spec-plugin-cli 或 /jsc-shared:spec-plugin-cli、或需要說明／產生某個 plugin 的安裝、更新、移除指令時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
---

# spec-plugin-cli — 共用 Plugin 安裝／更新／移除指令規範

四個 JSC plugin repo（`code`／`doc`／`persona`／`shared`）各自的 README 都有一節「安裝 / 更新 / 移除（各助理）」，內容除了 plugin 名稱之外幾乎完全重複；`shared/skills/plugins-install/SKILL.md`、`shared/skills/plugins-uninstall/SKILL.md` 又各自重述一次同一組指令。本規範是這組指令的**唯一權威版本**：其他 skill 內文或 README 需要說明某個助理的 plugin 安裝／更新／移除指令時，一律引用本節並只代換下方佔位符，不得另行複述完整指令區塊。

## 佔位符（唯一權威定義）

| 佔位符 | 意義 | 以 `jsc-shared` 為例 |
| --- | --- | --- |
| `<host>` | gitea 主機；決定順序見 `/jsc-shared:spec-gitea` 的「gitea 主機決定順序」一節，本規範不重複定義 | `gitea.jsc.idv.tw` |
| `<name>` | plugin repo 短名 | `shared`（其餘為 `doc`／`code`／`persona`） |
| `<url>` | repo 網址 = `https://<host>/plugins/<name>.git` | `https://gitea.jsc.idv.tw/plugins/shared.git` |
| `<plugin>` | plugin 名（各助理 manifest 的 `name` 欄位，例如 `.claude-plugin/plugin.json`） | `jsc-shared` |
| `<marketplace>` | marketplace 名（Claude／Codex／Copilot marketplace 登錄名） | `shared` |
| `<token>` | 安裝／更新／移除用的 install token，固定等於 `<plugin>@<marketplace>` | `jsc-shared@shared` |

> **`persona` 沒有例外**：現行 marketplace 名就是 repo 名 `persona`（即 `<token>` = `jsc-persona@persona`），跟其他三個 repo 規則一致。`jsc-plugins` 是**已停用的舊名**，只會出現在早期安裝過的本機殘留鍵裡；遇到使用者本機還留著 `jsc-persona@jsc-plugins`，要提醒先移除舊鍵再用 `jsc-persona@persona` 重裝，不要把舊名當成現行規則的例外套用。

## 通用前提

- **Claude / Codex 從 git URL 安裝會 clone 遠端**，安裝前請先把該 repo `push` 到 gitea。
- **Antigravity 的 `agy plugin install <url>` 目前只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，一律走「clone 到本機固定目錄 + 本地路徑安裝」，且**該 clone 目錄持久保留、更新用 `git pull` 而非每次重新 clone**（與 `plugins-install`／`plugins-uninstall` 的階段 C 實作一致）。
- **OpenCode 沒有原生 plugin 匯入指令，但可使用 skill**：改用「clone 到本機固定目錄 → 複製 `skills/` 到工具的 skills 目錄」的目錄安裝法，同樣採持久 clone + `git pull`。
- **GitHub Copilot CLI** 具備與 Claude Code 相同形態的 `marketplace` / `plugin` 原生指令。
- 下方每個助理小節的指令都以「安裝 → 更新 → 移除」固定順序給出。

---

## Claude Code

```bash
# 安裝
claude plugin marketplace add <url>
claude plugin install <token>

# 更新
claude plugin marketplace update <marketplace>
claude plugin update <token>

# 移除
claude plugin uninstall <token>
claude plugin marketplace remove <marketplace>
```

- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
- **本機開發（免 push）**：改用本地路徑安裝，例如 Windows `claude plugin marketplace add %USERPROFILE%\<你的工作區路徑>\<name>`、Linux／macOS／WSL `claude plugin marketplace add $HOME/<你的工作區路徑>/<name>`，安裝後同樣接 `claude plugin install <token>`。**路徑僅示範結構，實際位置依開發者本機安排；引用端產生文件時不得把真實使用者帳號名稱寫死進路徑**，一律用 `%USERPROFILE%\...`／`$HOME/...` 這類佔位符。正式安裝仍以 Gitea 遠端＋上方指令為準。
- 呼叫：Claude Code / Antigravity 用 `/jsc-<name>:<skill>`（例 `/jsc-shared:spec-output`）。

## Codex

```bash
# 安裝
codex plugin marketplace add <url>
codex plugin add <token>

# 更新（重新抓取 marketplace 的 git 快照）
codex plugin marketplace upgrade <marketplace>

# 移除
codex plugin remove <token>
codex plugin marketplace remove <marketplace>
```

- 安裝 token `<token>` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
- 該 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
- 呼叫：`$<skill>`（例 `$spec-output`），或用 `/skills` 選單。

## Antigravity（`agy`）

> `agy plugin install <url>` 目前**只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，一律走「clone 到本機固定目錄，再用本地路徑安裝」；`agy` 沒有 `update` 子指令，更新＝`git pull` 後重裝。

```bash
# 安裝（本機尚無 clone）
git clone <url> <clone-dir>/<name>
agy plugin install <clone-dir>/<name>

# 更新（已有 clone → git pull 後重裝，不重新 clone）
git -C <clone-dir>/<name> pull
agy plugin uninstall <plugin>
agy plugin install <clone-dir>/<name>

# 移除
agy plugin uninstall <plugin>
```

- `<clone-dir>` 沒有跨助理強制的唯一值：Windows 佔位符範例 `%USERPROFILE%\plugins`，Linux／macOS／WSL 佔位符範例 `$HOME/plugins`；引用端（README、`plugins-install` 等）可自訂自己的預設 clone 根目錄，但**一律用佔位符表示，不得寫死真實使用者帳號路徑**。
- 若把 skills 放到 GitHub，可直接 `agy plugin install https://github.com/<owner>/<repo>`，不需 clone。
- 其他常用子指令：`agy plugin list`、`agy plugin enable <plugin>` / `disable <plugin>`、`agy plugin validate <path>`。安裝或更新後需重啟工作階段。
- 呼叫：`/jsc-<name>:<skill>` 或依描述自動觸發。

## OpenCode

> OpenCode 沒有原生 plugin 匯入／移除指令，但可使用 skill：改用「clone 到本機固定目錄 → 複製 `skills/` 到工具 skills 目錄」的目錄安裝法。OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。

```bash
# 安裝
git clone <url> <clone-dir>/<name>
mkdir -p ~/.config/opencode/skills
cp -r <clone-dir>/<name>/skills/* ~/.config/opencode/skills/

# 更新（git pull 後重新複製，不重新 clone）
git -C <clone-dir>/<name> pull
cp -r <clone-dir>/<name>/skills/* ~/.config/opencode/skills/

# 移除：從 clone 目錄的 skills/ 即時推導清單逐一刪除，不要手抄寫死的 skill 名單（plugin 新增 skill 後手抄清單會漏）
for s in <clone-dir>/<name>/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"; done
```

- `cp -r` 是合併不是覆蓋：上游已刪除的 skill 目錄會在本機殘留，要乾淨更新請先用上面的移除迴圈清掉舊目錄再複製一次。
- **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`、`<clone-dir>` 佔位符範例 `%USERPROFILE%\plugins`。
- 呼叫：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。

## GitHub Copilot CLI

```bash
# 安裝
copilot plugin marketplace add <url>
copilot plugin install <token>

# 更新
copilot plugin marketplace update <marketplace>
copilot plugin update <token>

# 移除
copilot plugin uninstall <token>
copilot plugin marketplace remove <marketplace>
```

- 安裝 token `<token>` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 用上方 HTTPS URL。
- 呼叫：自然語言或 plugin skills，例如 `copilot -i "請使用 <skill> 說明其內容"`。

---

## 各助理速查

| 助理 | 安裝 | 更新 | 移除 |
| --- | --- | --- | --- |
| Claude Code | `marketplace add` + `install` | `marketplace update` + `update` | `uninstall` + `marketplace remove` |
| Codex | `marketplace add` + `add` | `marketplace upgrade` | `remove` + `marketplace remove` |
| Antigravity | `git clone` + `install` | `git pull` + `uninstall`→`install` | `uninstall` |
| OpenCode | `git clone` + `cp -r skills/*` | `git pull` + `cp -r skills/*` | 依 clone 的 `skills/` 逐一 `rm -rf` |
| GitHub Copilot CLI | `marketplace add` + `install` | `marketplace update` + `update` | `uninstall` + `marketplace remove` |

## 給樣板產生器的備註

- 四份 README 的「安裝 / 更新 / 移除（各助理）」章節，之後應改為引用本規範並只代換 `<host>`／`<name>`／`<plugin>`／`<marketplace>`／`<token>`／`<url>`，不再各自重複完整指令區塊；`shared/skills/plugins-install/SKILL.md`、`plugins-uninstall/SKILL.md` 亦同。
- `plugins-install`／`plugins-uninstall` 的階段 C 已採用與本規範一致的「持久 clone + `git pull`」寫法，可視為本規範的既有實作範例；`shared/README.md` 目前的 Antigravity／OpenCode 段落改用「每次重新 clone 到暫存目錄」的寫法，與本規範及 `doc`／`code` README 不一致，樣板產生時請一併改為本規範版本。
- 本機開發本地路徑一律使用 `%USERPROFILE%\...`／`$HOME/...` 佔位符，不得出現真實使用者帳號名稱路徑。