jiantw83
5db1d8a608
What
- `templates/skillset-contents.md`：`SKILLSET_CONTENTS` 的版面從 markdown 表格改成一筆一個 H2 區塊，標題寫成該筆對應內容頁的實際頁名，欄位改成標題底下的一層條列。
- `templates/tooling-contents.md`：同樣轉條列，原本說明用的 `## ` 區段併進 `>` 引言，正式頁上才不會被讀成一筆假紀錄。
- `templates/skillset-page.md`、`templates/tooling-page.md`：引言補上目錄頁與內容頁的版面差別，內容頁本身維持圖表優先、不改版面。
- `README.md`：兩份目錄頁範本的說明同步改寫，兩份 `TOOLING` 範本語意相反那一段補上「版面也相反」。
Why
- 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。
- 條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。
- 三個範本原本除了示範區塊之外還留著說明用的 `## ` 區段，轉條列後那種區段會在正式頁上被當成一筆紀錄讀進去。
How
- 一頁固定三段：H1 頁名、`>` 引言、然後每一筆一個 H2 區塊；區塊之間空一行，H2 與第一條之間空一行。
- 欄位在標題底下一行一條，格式 `- {欄位名}：{值}`，全形冒號，順序照原本的欄位從左到右，鍵那一欄照樣留一條。
- 寫入示例改成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{內容頁頁名}" {區塊檔}`，並註明鍵欄是舊表格裡持有內容頁連結那一欄的序號、只供自動轉檔用、要照線上那一頁實際的欄位排法填。
- 頁上不留任何 markdown 表格，也不放 mermaid。
Who
- 影響照這兩個範本寫目錄頁的技能：`skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 與 `tooling-guide`。
- 舊頁的轉檔與單一區塊 upsert 的實作不在本存取庫，本存取庫只提供範本與說明。
92 lines
13 KiB
Markdown
92 lines
13 KiB
Markdown
# jsc-meta — 技能組自我管理
|
||
|
||
jsc 技能組的 meta domain：新建、更新、刪除技能的流程，以及**全技能組的準則單一來源** `references/guidelines.md`（命名、description 規則、hook / 工具 / sub agent 下放、語言、環境變數、wiki 頁命名總表、審核檢查清單）。
|
||
|
||
## 安裝、更新、移除
|
||
|
||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-meta@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-meta@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-meta@jsc` | `claude plugin uninstall jsc-meta@jsc` |
|
||
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-meta@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-meta@jsc` |
|
||
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-meta@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-meta@jsc` | `copilot plugin uninstall jsc-meta@jsc` |
|
||
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/meta.git ~/plugins/meta && agy plugin install ~/plugins/meta` | `git -C ~/plugins/meta pull && agy plugin uninstall jsc-meta && agy plugin install ~/plugins/meta` | `agy plugin uninstall jsc-meta` |
|
||
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-meta@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-meta@jsc` | `kiro-cli plugin uninstall jsc-meta@jsc` |
|
||
|
||
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
|
||
|
||
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
|
||
|
||
## Skills 目錄
|
||
|
||
呼叫方式：Claude / Antigravity `/jsc-meta:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `skill-new`
|
||
|
||
新建技能：先併行預跑 `list-skills.sh` 與 `sync-domains.sh`，再用決策樹問細節（目標、觸發、輸入輸出、domain）→ 缺 domain 時依 template 結構建立新存取庫 → sub agent 依準則產生技能 → 審核清單自檢 → PR，並依 `references/pr-report.md` 回報 → 依 `references/deploy-verify.md` 部署與驗證。
|
||
|
||
### `skill-update`
|
||
|
||
更新技能：先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫，列出全部技能 → 使用者選擇 → 決策樹問更新細節 → 更新後依審核檢查清單逐項檢查，不符就回到詢問 → PR，並依 `references/pr-report.md` 回報 → 依 `references/deploy-verify.md` 部署與驗證。
|
||
|
||
### `skill-delete`
|
||
|
||
刪除技能：`sync-domains.sh` 依 Gitea 正本 marketplace 同步所有存取庫，`list-skills.sh` 列出全部技能 → 使用者選擇 → `find-skill-refs.sh` 盤點關聯檔案 → 併行的 sub agent 逐檔判斷是否需修正以維持功能（需要就決策樹問修正細節並依準則檢查）→ 刪除 → PR → 依 `references/deploy-verify.md` 部署，再用 `verify-skill-removed.sh` 實地檢查各 CLI 的技能快取與 hook 設定。深層刪除只在部署後查一次：部署前的刪除還沒生效，查了一定乾淨，證明不了任何事。
|
||
|
||
### `skillset-update`
|
||
|
||
批次更新——把一份變更需求套用到整個技能組的多個技能、domain。同步存取庫與決策樹併行起跑，先檢查工具化、sub agent 與環境變數優先規則，再由併行的 sub agent 逐 repo 改檔與開 PR；PR 回報格式見 `references/pr-report.md`，部署與驗證見 `references/deploy-verify.md`；單一技能改用 skill-update。
|
||
|
||
### `skill-check`
|
||
|
||
例行稽核——沒有變更需求時，同步存取庫之後併行跑三組：`lint-scripts.sh` 加 `lint-frontmatter.sh` 加 `check-behaviors.sh` 加 `ste100-lint.sh` 加 `check-wiki-rules.sh` 加 `check-page-name.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化審查先讀回各 domain `SKILLSET_{HASH}` 上已決議的建議，決議欄寫著「套用」或「延後」的不重複掃、不重複問；面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本。不符項目與優化建議分開回報，逐項決策樹確認並記下決議與決議日期後才套用，逐 repo 開 PR，最後把本輪結果附加到每個受影響 domain 的 `SKILLSET_{HASH}` 並登記在 `SKILLSET_CONTENTS`。有變更需求改用 skillset-update。
|
||
|
||
### `ste100-sync`
|
||
|
||
同步上游 speak-human-tw 的語言規則：先只讀上游 `SKILL.md` frontmatter 的版本來比對，判定要更新才 clone；有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式與 `jsc-hooks` 的簡體字表、全庫併行重掃、bump manifest，最後開 PR。適合列為本 repo 的維護方式。
|
||
|
||
### `tooling-guide`
|
||
|
||
盤點目前支援的 plugins、skills、hooks 管理與使用路徑，產出技能組基礎指引。基礎盤點一律沿用 `inventory-tooling.sh` 的輸出，不再重跑它內部已經跑過的三支腳本。適合建立技能組地圖、支援清單、hook 管理總覽與新人交接資料；安裝、更新、刪除、稽核與修復改用對應技能。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 參考與工具
|
||
|
||
| 檔案 | 用途 |
|
||
| --- | --- |
|
||
| `references/guidelines.md` | 技能準則唯一來源，所有 domain 的 AGENTS.md 都指向這裡 |
|
||
| `references/ste100.md` | STE100 擬人台灣感語言規則唯一來源（改寫自 speak-human-tw，MIT） |
|
||
| `references/pr-report.md` | PR 收尾回報格式唯一來源，所有會開 PR 的技能都指向這裡 |
|
||
| `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程：判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 |
|
||
| `references/behaviors.md` | 本 domain 的技能行為清單：一支技能一節，五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，供稽核與驗證比對。格式合約見 `references/guidelines.md` 的「技能行為清單」 |
|
||
| `templates/skillset-contents.md` | `SKILLSET_CONTENTS` 目錄頁樣板。大標題加條列：一個 H2 區塊代表一個 domain 存取庫，標題是內容頁頁名 `SKILLSET_{HASH}`，欄位一行一條；本頁落在 `JSC_WIKI_REPO_CONTENTS`，連結一律寫成 `[{文字}]({連結})` 的絕對網址並先過 `link-check.sh` 驗證，寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}"` 只寫自己那一個區塊。`<key-col>` 那個 `2` 是**舊表格裡持有內容頁連結那一欄的序號**，只供自動轉檔用，序號照**線上那一頁實際的欄位排法**數、不是照範本：線上舊表頭是 `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`，連結在第 2 欄 |
|
||
| `templates/skillset-page.md` | `SKILLSET_{HASH}` 內容頁樣板。歷次異動**累積**分節，每節記日期、異動類型、異動需求、動到的技能、改動檔案、PR 網址、部署路線判定與驗證結果；`skill-check` 那一節另含優化建議表，決議與決議日期兩欄供下一輪讀回 |
|
||
| `templates/tooling-contents.md` | `TOOLING_CONTENTS` 目錄頁樣板。大標題加條列：一個 H2 區塊代表一組「機器、CLI、帳號」，標題是內容頁頁名 `TOOLING_{HASH}`，欄位一行一條；寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert TOOLING 1 "TOOLING_{HASH}"`，只更新自己那一個區塊，別人的區塊原樣保留，**禁止整頁覆蓋** |
|
||
| `templates/tooling-page.md` | `TOOLING_{HASH}` 內容頁樣板。分節對應 `inventory-tooling.sh` 的輸出；**每次盤點覆寫整頁**，只留現況，不留歷史 |
|
||
| `tools/plugins-root.sh` | 推導技能組工作目錄的根，六支腳本共用。以 plugin 形式安裝時「腳本上兩層」會落在快取目錄，所以推導規則抽出來；推不出來 exit 1 並指名要設 `JSC_PLUGINS_ROOT` |
|
||
| `tools/ste100-lint.sh` | 語言規則的機檢工具：中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線；命中 exit 1，沒給檢查對象 exit 2 |
|
||
| `tools/lint-scripts.sh` | 一個 domain 的腳本檢查三合一：`sh -n` 語法、執行權限、檔頭結束碼宣告；有不合格 exit 1，沒有腳本可掃 exit 3（**不等於通過**） |
|
||
| `tools/lint-frontmatter.sh` | 一個 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析檢查：分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」也不以 YAML 特殊字元起頭、引號收得起來。不相依任何 YAML 套件。不合格 exit 1（清單在 stderr），用法錯誤 exit 2，沒有 SKILL.md 可掃 exit 3（**不等於通過**）。frontmatter 壞掉時 Antigravity 會**靜默丟棄整支技能**，沒有任何錯誤訊息 |
|
||
| `tools/check-behaviors.sh` | 比對一個 domain 的 `references/behaviors.md` 與 `skills/`：節對技能、字典序、每節一張表、五個欄位齊全且內容欄非空，另斷言「可驗證跡象」那一列寫到收尾的 `skill-end` 事件或 `events.jsonl`（技能的成敗只有技能自己寫得出來，hook 觸發時實際工作還在後面的模型輪次；有 start 沒有配對的 end 就是中止）；不符 exit 1，用法錯誤 exit 2，找不到清單或找不到技能 exit 3（**不等於通過**） |
|
||
| `tools/check-link-format.sh` | 檢查一個 domain 全部 `*.md` 的連結寫法：一律 `[{文字}]({連結})`，不留同 wiki 的雙括號連結。判定前先剝掉行內程式碼與圍籬區塊，所以說明用的字面與 shell 條件測試不會誤判。有命中 exit 1（清單在 stdout），用法錯誤 exit 2，沒有文件可掃 exit 3（**不等於通過**） |
|
||
| `tools/check-page-name.sh` | 比對 wiki 頁名樣式三處是否一致：`jsc-gitea/tools/page-name.sh`（正本）、`jsc-hooks/hooks/comment-scope.sh`、`jsc-log/tools/worklog-pending.sh`。三處刻意不共用函式，因為 hook 必須自足；斷言十五種型別、40 碼與 8 碼兩種長度。不一致 exit 1，用法錯誤 exit 2，三處一支都找不到 exit 3（**不等於通過**） |
|
||
| `tools/deploy-route.sh` | 判定改動有沒有進存取庫的預設分支，決定走部署路線（exit 0）或工作樹路線（exit 3）；判不出來 exit 1，**不等於工作樹路線** |
|
||
| `tools/sync-domains.sh` | 依 Gitea 正本 marketplace 把所有 domain 存取庫 clone 或 pull 到本機，印出 `domain<TAB>path`；**只有 exit 0 代表全部到位且最新**，exit 3 代表有存取庫跳過或 pull 失敗（stderr 列路徑），exit 2 代表有 domain clone 失敗 |
|
||
| `tools/list-skills.sh` | 列出正本 marketplace 上各 domain 存取庫的技能，印出 `domain<TAB>name<TAB>description`；不在正本清單上的存取庫不列 |
|
||
| `tools/inventory-tooling.sh` | 盤點目前支援的 plugins、skills、tools、hooks，輸出技能組基礎指引 Markdown |
|
||
| `tools/sync-marketplace.sh` | 寫入或更新兩份正本 marketplace 的 plugin 條目，再複製到每個 domain 存取庫（保證位元組一致）。**需要 python3**（json 模組改 JSON），缺 python3 不寫檔並 exit 1；存取庫不在本機 exit 3 |
|
||
| `tools/sync-skill-manifest.sh` | 同步 domain README 的「Skills 目錄」，並 bump 三份 manifest 的 version；`minor` 與 `patch` 不得超過 `9`，`major` 可以超過 `9`。缺目錄、缺標記或缺 version 欄位 exit 1，用法錯誤 exit 2 |
|
||
| `tools/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案（不掃非技能組存取庫與點開頭目錄）；技能名稱為純子字串比對，命中要逐檔確認；零命中 exit 1，掃描失敗 exit 3 |
|
||
| `tools/verify-skill-removed.sh` | 刪除技能後實地檢查各 CLI 的技能快取與 hook 設定有無殘留；有殘留 exit 1，沒偵測到 CLI 或沒有可查位置 exit 3（**不等於乾淨**） |
|
||
|
||
兩份 `TOOLING` 樣板的寫入語意與版面都剛好相反，套用前先分清楚。目錄頁是共用的，整頁覆蓋會刪掉別台機器的紀錄，所以只准動自己那一個 H2 區塊，版面一律大標題加條列，頁上不留 markdown 表格。內容頁只屬於一組「機器、CLI、帳號」，記的是當下現況，舊的安裝內容早就不成立，所以整頁覆寫，版面維持圖表優先。頁名、雜湊與這條版面區分見 `references/guidelines.md` 的「Wiki 頁命名總表」。
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-ask`](https://gitea.jsc.idv.tw/plugins/ask)：決策樹問詢
|
||
- [`jsc-git`](https://gitea.jsc.idv.tw/plugins/git)：完成後的 Push Request
|