.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "jsc",
       "source": "./",
-      "description": "JSC 文件化 skills：整理 docker-compose 註解、補齊 function XML 文件並更新 README 功能目錄。"
+      "description": "JSC 文件化 skills：整理 docker-compose 註解、補齊 function XML 文件並重建 README 功能列表與使用範例。"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jsc",
-  "version": "0.0.2",
-  "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並更新 README 功能目錄。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
+  "version": "0.0.3",
+  "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
   "skills": "./skills",
   "author": {
     "name": "JSC"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.0.2",
-  "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並更新 README 功能目錄。所有 skills 以 SKILL.md 為共通標準。",
+  "version": "0.0.3",
+  "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準。",
   "skills": "./skills"
 }

README.md

@@ -1,7 +1,7 @@
 # jsc — 跨 AI 助理文件化 Skill 集合
 
 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 skill 集合。
-目前內含兩個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並更新 README 功能目錄。
+目前內含兩個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。
 核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
 搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
 在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。
@@ -175,7 +175,7 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
 
 ### `doc-funcs`
 
-掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments，最後更新 README 功能目錄並執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。
+掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments，最後重建 README 功能列表與使用範例並執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。
 
 - **Claude Code / Antigravity**：`/jsc:doc-funcs`
 - **Codex**：`$doc-funcs`，或用 `/skills` 選單

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.0.2",
-  "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並更新 README 功能目錄。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
+  "version": "0.0.3",
+  "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
   "skills": "./skills/"
 }

skills/doc-funcs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-funcs
-description: 為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML 文件，最後更新 README 功能目錄。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。
+description: 為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML 文件，最後重建 README 功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。
 ---
 
 # 補齊 function 文件
@@ -20,14 +20,17 @@ description: 為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML
 4. 在實作到原始碼之前，主 agent 必須檢查所有草稿內容是否以繁體中文為主、英文為輔，且沒有任何亂碼、編碼錯誤、不可讀字元或明顯破損文字。若發現問題，先修正草稿並重新檢查，通過後才能進入下一步。
 5. 所有草稿完成且通過檢查後，主 agent 要閱讀草稿並實作到原始碼。若是 C#，使用 XML documentation comments：`<summary>`、`<param>`、`<remarks>`。註解盡量使用繁體中文；保留既有正確文件，僅補齊缺漏或明顯不足處；不要為了文件改變 runtime 行為。
 6. 若遇到大量 function，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 .docs/doc-funcs-index.md 標記 pending。
-7. 補齊後，產生或更新專案根目錄的 README.md 功能目錄。功能目錄只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test`、`Fact`、`Theory`、`TestMethod`、`TestCase`、`SetUp`、`TearDown`、`Initialize`、`Cleanup`），即使是 public 也要排除。功能目錄依專案名稱分組；每個專案使用一張 Markdown 表格呈現公開方法，欄位固定為「功能名稱」、「功能描述」、「使用範例」。功能名稱需做成 Markdown 連結，導向目標專案 git `origin` 遠端上的對應檔案 function 起始行；連結必須以執行此 skill 的目標專案為準，先用 `git remote get-url origin` 取得遠端，再搭配目前分支、檔案相對於目標專案根目錄的路徑與 function 起始行號產生，不得使用本 skill repo、工作區外 repo 或硬編碼的外部 repo 座標。若 origin 是 SSH 格式（例如 `git@gitea.example.com:owner/repo.git`），需轉為對應 HTTPS 瀏覽 URL；若 origin 已是 HTTPS，沿用同一個 host 與 repo path，並移除尾端 `.git`。Gitea 類網址使用 `/src/branch/<branch>/<path>#L123`，GitHub 類網址使用 `/blob/<branch>/<path>#L123`；無法可靠判斷平台時，優先採 Gitea 格式。若無法可靠解析目標專案的 `origin` 遠端、目前分支、檔案路徑或行號，才退回純文字功能名稱；README 功能目錄不必列出內部呼叫方法。功能目錄必須包含更新時間；若 README.md 已有既有內容，保留既有內容並以最小變更更新或新增功能目錄區塊。
-8. README 功能目錄完成後，刪除本次產生的所有草稿與索引：`.docs/doc-funcs/` 與 `.docs/doc-funcs-index.md`。若 `.docs/` 內已無其他內容，可一併移除空的 `.docs/` 目錄；不得刪除使用者既有的 `.docs/` 其他檔案。
+7. 補齊後，重建專案根目錄的 README.md。若根目錄已有 README.md，先刪除既有檔案，再產生新的 README.md；不要保留或合併舊內容。README 必須包含更新時間，且只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test`、`Fact`、`Theory`、`TestMethod`、`TestCase`、`SetUp`、`TearDown`、`Initialize`、`Cleanup`），即使是 public 也要排除。README 內容拆成兩個主要區塊：
+   - 功能列表：依專案名稱分組；每個專案使用一張 Markdown 表格呈現公開方法，欄位固定為「功能名稱」、「功能描述」。功能名稱需做成 Markdown 連結，導向目標專案 git `origin` 遠端上的對應檔案 function 起始行；功能描述使用簡單版描述，並做成 Markdown 連結，導向同一份 README 內「使用範例」區塊中該功能的標題錨點。
+   - 使用範例：每個功能各有一個標題，標題文字使用功能名稱；標題下方包含完整版功能描述與使用範例。完整版功能描述可依草稿的行為分析、`<summary>`、`<param>`、`<remarks>` 整理；使用範例需展示典型呼叫方式、重要前置條件與預期結果。若無法可靠產生可執行範例，提供保守的情境式範例並標註需人工確認。
+   功能名稱連結必須以執行此 skill 的目標專案為準，先用 `git remote get-url origin` 取得遠端，再搭配目前分支、檔案相對於目標專案根目錄的路徑與 function 起始行號產生，不得使用本 skill repo、工作區外 repo 或硬編碼的外部 repo 座標。若 origin 是 SSH 格式（例如 `git@gitea.example.com:owner/repo.git`），需轉為對應 HTTPS 瀏覽 URL；若 origin 已是 HTTPS，沿用同一個 host 與 repo path，並移除尾端 `.git`。Gitea 類網址使用 `/src/branch/<branch>/<path>#L123`，GitHub 類網址使用 `/blob/<branch>/<path>#L123`；無法可靠判斷平台時，優先採 Gitea 格式。若無法可靠解析目標專案的 `origin` 遠端、目前分支、檔案路徑或行號，才退回純文字功能名稱；README 不必列出內部呼叫方法。
+8. README 重建完成後，刪除本次產生的所有草稿與索引：`.docs/doc-funcs/` 與 `.docs/doc-funcs-index.md`。若 `.docs/` 內已無其他內容，可一併移除空的 `.docs/` 目錄；不得刪除使用者既有的 `.docs/` 其他檔案。
 9. 完成後執行合適的格式化/建置或至少語法驗證；若無法執行，說明原因。
 
 ## 重要限制
 
-- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼檔，除非是建立草稿與索引。
+- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼檔，除非是建立草稿、索引，或依流程刪除並重建根目錄 README.md。
 - 不要新增與文件無關的 helper、測試或重構。
 - 草稿是實作依據，不能跳過。
 - 若 function 行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
-- 原始碼註解與 README 功能目錄盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。
+- 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。