doc/skills/doc-funcs/SKILL.md

name, description

name	description
doc-funcs	為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML 文件，最後重建 README 功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。

補齊 function 文件

你要替目前工作區內的專案補齊 function XML 文件。請依序完成：

1. 掃描專案內所有可文件化的 function/method。以目前 repo 的主要語言為準；若是 C#，包含 public/internal/protected/private method、constructor、extension method、operator，排除 generated/bin/obj/.git/.docs 與第三方依賴。
2. 建立 .docs/ 目錄（若不存在）。先產生總索引 .docs/doc-funcs-index.md，列出所有 function：專案名稱、檔案、型別、可見性、簽名、是否已有 XML doc、草稿檔路徑。
3. 針對每一個 function 派出一個 subagent。每個 subagent 只分析指定 function 與必要上下文，不直接改 code；回傳並在 .docs/ 底下建立一份草稿。草稿檔名需可追溯來源，例如 .docs/doc-funcs/{relative-path}.{type}.{function}.md。草稿內容必須包含：
   • 位置：檔案與行號
   • 簽名：完整簽名
   • 行為分析：方法實際做什麼、重要分支、副作用、例外/失敗行為
   • 建議 <summary>：根據功能產生，不要只改寫方法名稱
   • 建議 <param>：每個參數的用途、限制、null/empty 行為（能從 code 推論才寫；不能確定就標註需人工確認）
   • 建議 <remarks>：至少一個使用情境，描述何時呼叫、前置條件、結果或注意事項
   • 內部呼叫：此 function 內直接呼叫的 internal/private/protected/private protected 方法；列出方法名稱、所屬型別、可見性與用途推論。若無呼叫則明確標註「無」。
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。若根目錄已有 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 以外的非原始碼檔，除非是建立草稿、索引，或依流程刪除並重建根目錄 README.md。
• 不要新增與文件無關的 helper、測試或重構。
• 草稿是實作依據，不能跳過。
• 若 function 行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
• 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。