plugins/doc
2
0
Fork 0
Code Pull Requests Activity
121 Commits 2 Branches 0 Tags
e9c021adbe676d85ff490bd57892c0979f49b712
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

jsc-doc — 跨 AI 助理文件化 Skill 集合

一個可同時被 Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot 使用的文件化 skill 集合。 目前內含六個實作型 skills：docker 用於整理 docker-compose.yaml 的行內註解與標題日期；funcs 用於掃描專案 functions、建立 .docs/ 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；issues-analyze 用於把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日排序留言（不實作程式碼，實作交由 code plugin 的 issues）；issues-sync 用於讀取 Gitea 專案或議題，依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位、產生進度留言；指定「關閉專案／專案完成」時改為批次把專案所有議題搬到「已完成」並關閉；worklog 用於把 session stop 的內容透過 README 定義的 headless CLI 整理成六欄工作紀錄並追加到 Gitea wiki。 核心是以 Agent Skills（SKILL.md） 標準撰寫的共用 skills（唯一真實來源放在 skills/）， 搭配各助理各自的 plugin manifest，讓同一個 repo 可用各家原生 plugin CLI 安裝。 在 Claude Code 與 Antigravity 中，skill 以 /jsc-doc: 前綴呼叫（例如 /jsc-doc:docker）。

前綴與呼叫方式

助理 安裝方式 呼叫 /jsc-doc: 前綴
Claude Code claude plugin（marketplace） /jsc-doc:<name> 或自動觸發 ✅
Codex codex plugin（marketplace） $<name> 或 /skills 選單 ❌（用 $name）
Antigravity agy plugin install /jsc-doc:<name> 或自動觸發 ✅
OpenCode skills 目錄（複製/clone） 描述需求自動觸發 ❌（依名稱）
GitHub Copilot CLI copilot plugin（marketplace） 自然語言或 plugin skills ❌（無 /jsc-doc: 前綴）

Codex 不支援自訂前綴（skill 以 $name 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆不強制前綴。

目錄結構

同一個 repo 同時帶四種 manifest，彼此以路徑隔離、互不干擾；各助理都讀同一份 skills/。

doc/
├── .claude-plugin/
│   ├── plugin.json          # Claude 外掛定義（name: "jsc-doc"）
│   └── marketplace.json     # Claude marketplace（name: "doc"，source 指向本 repo）
├── .codex-plugin/
│   └── plugin.json          # Codex 外掛定義（name: "jsc-doc"，skills: "./skills"）
├── .agents/plugins/
│   └── marketplace.json     # Codex marketplace（name: "doc"，url source 指向本 repo）
├── plugin.json              # Antigravity 外掛定義（name: "jsc-doc"，skills: "./skills/"）
├── hooks/
│   └── hooks.json           # Stop → worklog；Claude 用 plugin root，Codex fallback 到安裝 cache
├── scripts/
│   └── worklog/             # worklog 自動記錄的可執行元件（skill 與 hook 共用）
│       ├── worklog.sh       # 主流程：抽本輪 → 濃縮成六欄 → 遮蔽 → 追加到 wiki
│       ├── wiki_api.py      # Gitea wiki 讀寫、token 解析、append 重試、週頁命名
│       └── transcript.py    # transcript 本輪抽取、耗時估算與機密遮蔽
├── skills/                  # ★ 唯一真實來源：所有 skills
│   ├── docker/          # 對齊 docker-compose 註解（含 scripts/）
│   │   ├── SKILL.md
│   │   └── scripts/
│   ├── funcs/           # 為 function 補齊 XML 文件、指令檔逐行註解（含 templates/）
│   │   ├── SKILL.md
│   │   └── templates/       # 指令檔開頭「用途／更新時間」標頭範本（command-header.md）
│   ├── issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
│   ├── issues-analyze/SKILL.md         # 讀來源 → 保存議題 → 小功能議題（看板移待處理）→ 排序留言（不實作）
│   ├── issues-sync/SKILL.md            # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤／調整看板欄位 → 進度留言；關閉專案時批次搬「已完成」並關閉
│   └── worklog/SKILL.md                    # 工作證明自動記錄的操作與維護
├── AGENTS.md                # 跨助理共用指引
└── README.md

worklog 適用範圍

功能 Claude Code Codex Antigravity OpenCode GitHub Copilot
Stop hook 自動記錄 ✅ ✅ 需可讀 Codex session JSONL ❌ ❌ ❌
worklog 手動模式 ✅ ⚠️ 需安裝後保留 scripts/ ⚠️ 同左 ⚠️ 需完整 plugin 目錄 ⚠️ 需安裝後保留 scripts/
摘要 CLI claude -p codex exec agy -p opencode run copilot -p

worklog 自動記錄仍依賴相容的 Stop hook 與 transcript JSONL 結構；Claude Code 會用 CLAUDE_PLUGIN_ROOT 定位腳本，Codex 會從 ~/.codex/plugins/cache/doc/jsc-doc 找已安裝的 worklog 腳本並解析 Codex session JSONL。摘要執行器可用 WORKLOG_CLI=auto|claude|codex|agy|opencode|copilot 指定；預設 auto 會先依目前 hook/session 環境判斷正在使用的 CLI，判斷不到或該 CLI 不可執行時才 fallback 到已安裝工具。

安裝 / 更新 / 移除（各助理）

指令中的 repo 網址：https://gitea.jsc.idv.tw/plugins/doc.git

Claude / Codex 從 git URL 安裝（會 clone 遠端），請先把本 repo push 到 gitea。 Antigravity 的 agy plugin install <url> 目前只支援 github.com；gitea 請改用「clone + 本地路徑」（見 Antigravity 節）。 本機/離線：Claude 可用本地路徑加 marketplace；Antigravity 用本地路徑安裝。

Claude Code

# 安裝
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git
claude plugin install jsc-doc@doc

# 更新
claude plugin marketplace update doc
claude plugin update jsc-doc@doc

# 移除
claude plugin uninstall jsc-doc@doc
claude plugin marketplace remove doc
  • 工作階段內 slash 版（等價）：把 claude plugin 換成 /plugin。
  • 本機開發（免 push）：claude plugin marketplace add C:\Users\h3285\source\repos.plugins\doc（本地路徑）後再 install。
  • 呼叫：/jsc-doc:<name>（例 /jsc-doc:docker）。

Codex

# 安裝
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git
codex plugin add jsc-doc@doc

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

# 移除
codex plugin remove jsc-doc@doc
codex plugin marketplace remove doc
  • 安裝 token jsc-doc@doc = plugin 名（.codex-plugin/plugin.json 的 name）@ marketplace 名（.agents/plugins/marketplace.json 的 name）。
  • 本 repo 的 Codex marketplace 以 url 來源指向自己，故 Codex 一律從 gitea 安裝（需先 push）；安裝後重啟 Codex。
  • 呼叫：$<name>（例 $docker），或用 /skills 選單。

Antigravity（agy）

agy plugin install <url> 目前只支援 github.com；gitea 等自架 git 不支援 URL 安裝，請先 git clone 再用本地路徑安裝。

# 安裝：clone 後用本地路徑
git clone https://gitea.jsc.idv.tw/plugins/doc.git ~/plugins/doc
agy plugin install ~/plugins/doc

# 更新（agy 無 update 子指令 → git pull 後重裝）
git -C ~/plugins/doc pull
agy plugin uninstall jsc-doc
agy plugin install ~/plugins/doc

# 移除
agy plugin uninstall jsc-doc
  • 若把 skills 放到 GitHub，則可直接 agy plugin install https://github.com/<owner>/<repo>。
  • 其他：agy plugin list、agy plugin enable jsc-doc / disable jsc-doc、agy plugin validate <path>。安裝後重啟工作階段。
  • 呼叫：/jsc-doc:<name>（例 /jsc-doc:docker）或依描述自動觸發。

OpenCode

OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於 skill 包；skills 改用目錄安裝。 OpenCode 會讀 ~/.config/opencode/skills/（也會讀 ~/.claude/skills/、~/.agents/skills/）。

# 安裝
git clone https://gitea.jsc.idv.tw/plugins/doc.git ~/jsc-plugin
mkdir -p ~/.config/opencode/skills
cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/

# 更新
git -C ~/jsc-plugin pull
cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/

# 移除
rm -rf ~/.config/opencode/skills/docker ~/.config/opencode/skills/funcs ~/.config/opencode/skills/issues-analyze-to-file ~/.config/opencode/skills/issues-analyze ~/.config/opencode/skills/issues-sync ~/.config/opencode/skills/worklog

worklog 在 OpenCode 的 skills 目錄安裝不可用：上面的複製只帶 skills/，不含 scripts/ 與 hooks/，worklog 的所有模式都會失敗；若以完整 plugin 目錄執行並能解析 scripts/worklog，可用 WORKLOG_CLI=opencode 作為摘要 CLI。

Windows PowerShell：cp -r A B → Copy-Item A B -Recurse -Force、rm -rf X → Remove-Item X -Recurse -Force、~ → $HOME。

  • 呼叫：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。

GitHub Copilot CLI

Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，可直接從 marketplace 安裝、更新與移除本 plugin。

# 安裝
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git
copilot plugin install jsc-doc@doc

# 更新
copilot plugin marketplace update doc
copilot plugin update jsc-doc@doc

# 移除
copilot plugin uninstall jsc-doc@doc
copilot plugin marketplace remove doc
  • 安裝 token jsc-doc@doc = plugin 名（plugin manifest 的 name）@ marketplace 名。
  • copilot plugin marketplace add 支援 GitHub owner/repo、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。
  • 呼叫：在 Copilot CLI 中用自然語言描述需求，例如 copilot -i "請使用 docker 整理 docker-compose 註解"。
  • worklog 的 Stop hook 自動記錄仍只有相容 hook 環境會實際執行；Copilot CLI 可作為 WORKLOG_CLI=copilot 摘要執行器，但不會執行 Claude Code hook。

用 CLI 直接執行 skill（headless / 一次性）

安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果：

助理 headless 指令 執行 docker skill
Claude Code claude -p "<prompt>" claude -p "/jsc-doc:docker"
Codex codex exec "<prompt>" codex exec '$docker'
Antigravity agy -p "<prompt>" agy -p "/jsc-doc:docker"
OpenCode opencode run "<message>" opencode run "整理 docker-compose 註解"
GitHub Copilot CLI copilot -p "<message>" copilot -p "整理 docker-compose 註解"
  • Claude / Antigravity 支援 /jsc-doc: 前綴，直接 -p "/jsc-doc:<name>" 即可。
  • Codex 以 $<name> 觸發；在 shell 請用單引號避免 $ 被展開：codex exec '$docker'。
  • OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。
  • 帶引數就接在後面，例如 claude -p "/jsc-doc:docker docker-compose.yaml"、codex exec '$docker docker-compose.yaml'。

Skills 目錄

此區塊列出本 plugin 內含的所有 skills（名稱／描述／使用方法）。 新增或修改 skill 後，請同步手動更新標記之間的內容。

docker

整理並對齊 docker-compose.yaml 的行內註解與標題區塊，優先透過內建 shell/awk 腳本批次處理或處理指定檔案。當使用者要對齊 docker-compose 註解、整理 compose 檔註解欄位、更新 compose 標題日期，或提到 docker-compose、dc-tidy、align_comments、註解對齊時使用此 skill。

  • Claude Code / Antigravity：/jsc-doc:docker
  • Codex：$docker，或用 /skills 選單
  • OpenCode：描述需求自動觸發

funcs

掃描目前專案所有可文件化的 function/method，建立 .docs/doc-funcs-index.md 與逐 function 草稿，再依草稿補齊 XML documentation comments；指令檔（腳本／CI／部署設定檔）草稿開頭的「用途／更新時間」標頭固定依 skills/funcs/templates/command-header.md 範本產生（依檔案類型選 # 或 ::/REM 變體）；Dockerfile 與 README 的檔名會依專案內多數檔案的大小寫命名慣例正規化（無明顯多數則保留原檔名），改名時同步更新引用；同時整理 .gitea/workflows/readme.md 的 workflow 說明、觸發條件與相關參數草稿，最後重建 README 專案列表、功能列表與使用範例。README 更新時間固定使用台灣時區（Asia/Taipei）與 yyyy/MM/dd HH:mm:ss 格式，專案列表會拆成「專案名稱／專案描述」、「專案名稱／參考專案列表」、「專案名稱／NuGet 套件列表」三張表，且專案名稱會連到 Gitea/GitHub 遠端上的專案資料夾；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、整理 workflow README、建立 .docs 草稿，或提到 funcs、function 文件化、workflow 文件化、XML documentation comments 時使用此 skill。

  • Claude Code / Antigravity：/jsc-doc:funcs
  • Codex：$funcs，或用 /skills 選單
  • OpenCode：描述需求自動觸發

issues-analyze-to-file

讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq），把 issue 正文與留言彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑與專案、依需求性質從既有標籤挑選填入），再配合使用者指定的 repositories 或 issue 所在 repo，對每個階段派 subagent 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。建立 issue 與留言前會先產生全部草稿並以 AskUserQuestion 讓使用者確認執行方式（全部執行／只建立 issue／只產文件不動 Gitea／逐階段確認）。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析，或提到 issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill；全程不落地檔案、以議題描述與留言保存中間成果的拆分流程改用 issues-analyze，兩者都可能符合時先詢問使用者要「檔案交付」還是「議題留言」。

  • Claude Code / Antigravity：/jsc-doc:issues-analyze-to-file
  • Codex：$issues-analyze-to-file，或用 /skills 選單
  • OpenCode：描述需求自動觸發

issues-analyze

讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取——文字附件直接取內容、圖片等二進位附件唯讀暫存讀取後即刪、無法讀取的附件列出檔名標註需人工確認），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時，母議題（保存議題）必須所有子議題都關閉後才可關閉——優先以 Gitea issue dependency 阻擋，不支援時在母議題描述加入子議題清單與關閉前檢查），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），會把議題移到「待處理」欄位（不往回移、Gitea 介面不支援時改列建議清單請使用者手動拖曳）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，不實作程式碼（不修改原始碼、不 commit、不 push、不開 PR），實作交由 /jsc-code:issues。所有中間成果都不落地成草稿檔，一律使用 tea 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill；要產出需求／交付文件檔案時改用 issues-analyze-to-file。

  • Claude Code / Antigravity：/jsc-doc:issues-analyze
  • Codex：$issues-analyze，或用 /skills 選單
  • OpenCode：描述需求自動觸發

issues-sync

讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；輸入是專案時因 tea／Gitea API 無法直接查詢專案，改先取得該 repo 所有開啟中的議題、再過濾掉與此專案無關的議題，輸入是議題就只同步該議題，找不到目標時以 AskUserQuestion 請使用者補齊。議題若有標籤就依標籤分組、以 AskUserQuestion（多選）讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，以工作目錄下的所有檔案為依據：判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補 TODO 追加到正文、依需求從既有標籤更新議題標籤、逐條勾稽未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議議題應在的欄位，經確認後移動（Gitea 介面不支援 project 欄位操作時改列建議清單請使用者手動拖曳）。若輸入為專案且使用者明確指定「關閉專案／專案完成」，進入專案完成模式：只執行到取得專案議題清單，跳過其後所有同步步驟，列出議題清單（含仍有未完成 TODO 者）經使用者確認後，把專案擁有的所有議題搬到「已完成」欄位並關閉，單筆失敗不中斷整批並於回報列出。全程不落地任何檔案（不建立 .docs/、不寫草稿檔），所有中間成果只留在對話／subagent 回傳，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先以 AskUserQuestion 讓使用者確認執行方式。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 issues-sync、issue sync、議題同步、TODO 勾稽、Gitea 專案議題時使用此 skill。

  • Claude Code / Antigravity：/jsc-doc:issues-sync
  • Codex：$issues-sync，或用 /skills 選單
  • OpenCode：描述需求自動觸發

worklog

工作證明自動記錄與手動維護流程。相容的 Stop hook 會把每輪工作透過 WORKLOG_CLI 指定的 headless CLI 整理成六個固定欄位：專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式，並追加到 Gitea wiki 當週頁（Worklog-yyyy-MM-W<週>）。手動模式提供 --init、--tune（Claude Code 專屬）、--diagnose、--append、--show。

  • Claude Code / Antigravity：/jsc-doc:worklog --diagnose
  • Codex：$worklog --diagnose，或用 /skills 選單
  • OpenCode / GitHub Copilot：需完整 plugin 目錄保留 scripts/；可用 WORKLOG_CLI=opencode 或 WORKLOG_CLI=copilot 作為摘要 CLI

新增一個 skill

  1. 複製既有 skill 作範本：cp -r skills/docker skills/<your-skill-name>
  2. 編輯 skills/<your-skill-name>/SKILL.md 的 frontmatter：
    • name：小寫、數字、連字號（-），最長 64 字元。這就是 Claude Code / Antigravity 的 /jsc-doc:<name>。
    • description：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。
  3. 在內文寫下 skill 的具體步驟。
  4. 手動把這個 skill 補進上方「Skills 目錄」區塊。
  5. bump 版本並 push：各助理都以 git 內容/版本判斷更新，請把 .claude-plugin/plugin.json、.codex-plugin/plugin.json、plugin.json 三個 manifest 的 version 一起 bump，commit 後 push 到 gitea。
  6. 讓各助理更新：
    • Claude：claude plugin update jsc-doc@doc
    • Codex：codex plugin marketplace upgrade doc
    • Antigravity：git -C ~/jsc-plugin pull && agy plugin uninstall jsc-doc && agy plugin install ~/jsc-plugin
    • OpenCode：git pull 後重新複製 skills/
    • Copilot：copilot plugin marketplace update doc && copilot plugin update jsc-doc@doc
View Git Blame Copy Permalink
S
Description
Doc 指令 for AI 助理
https://gitea.jsc.idv.tw/plugins/doc
Readme
848 KiB
Languages
Python 63.1%
Shell 35.3%
Awk 1.6%