Skip to content

rdcrystallab/vault-assistant

v0.3.1MIT

Subagent + slash commands for running a PARA-structured Obsidian vault end-to-end: daily/weekly/monthly ceremony, project status, research-repo patrol, wiki knowledge extraction, archival, and a GitHub Issues ↔ vault Hub issue workflow — all auto-committed to git. Quartz-compatible wikilinks enforced.

GitHub

vault-assistant

在任何 PARA 結構的 Obsidian vault 上跑完整 ceremony 的 Claude Code plugin。內建 vault-assistant subagent、14 個 slash command、4 個 skill，涵蓋日 / 週 / 月報、專案狀態、research-repo 巡檢、wiki 知識萃取與歸檔、以及 GitHub Issues ↔ vault 雙向 Hub issue workflow，每次寫入都自動 git add + commit + push（對齊 AGENTS.md 規則）。

目標使用者

用 Obsidian + Quartz 發佈的個人 vault 作者，採用 PARA（Projects / Areas / Resources / Archives）組織、每天寫 daily note、每週 weekly、每月 monthly，想讓 Claude Code 接手儀式性操作。

功能總覽

Subagent

  • vault-assistant — 知道 PARA 放置規則、Quartz-shortest wikilink 格式、每次寫入要 auto commit+push，會把多步 ceremony（morning briefing、end-of-day、weekly retrospective、monthly rollup）串起來跑。任何涉及 vault 的指令都建議改委派給它。

Slash commands（14）

Command作用
/vault-assistant:install初始化當前目錄為 PARA vault（建骨架、複製 templates、寫 AGENTS.md、issue templates）
/vault-assistant:start-day建立今日 daily note，產出 morning briefing（含 label:now issue 簡報）
/vault-assistant:end-day收尾 daily note、reconcile checkbox、同步 Objectives 進度、auto commit+push
/vault-assistant:end-weekWeekly retrospective — 彙整本週 daily 進 weekly 報
/vault-assistant:end-monthMonthly rollup、評估 Objectives、建立下月 skeleton
/vault-assistant:plan-weekly規劃下週 weekly report（訪談式、含 issue re-label reminder）
/vault-assistant:sync-projects從最新 weekly / monthly 反推同步 Projects/index.md
/vault-assistant:update-project-status更新指定專案的狀態表與最後更新日
/vault-assistant:add-project-note在專案下新增研究筆記
/vault-assistant:extract-pattern從當前工作萃取 wiki article（跳過 raw/ 流程）
/vault-assistant:archive-project-doc搬檔案到 Archives（處理 assets + wikilink 重寫）
/vault-assistant:gh-daily-log抓 GitHub 活動寫入 daily note 的 Logs
/vault-assistant:repo-patrol巡檢 Areas/development/research-repos/ 的 upstream 變化
/vault-assistant:watch-repo加 GitHub repo 進 research-repos monitoring list
/vault-assistant:capture-issue從 vault 工作流開 GitHub issue，自動套 project/type/horizon 三軸 label，並優先依 vault 內的 project routing table 選 repo

Skills（4）

  • new-project — 在 vault 新增專案、更新 Projects/index.md
  • gh-contribution-report — 從 GitHub org 抓 commits / PRs 生成月報與年報
  • gh-issues-to-doc — 把 GitHub Issues 轉成結構化 Obsidian 筆記
  • github-query — vault-first 的 GitHub repo / issue / PR 查詢層，優先讀 research-repos note，未命中才 fallback 到本地 clone 與 gh CLI，並在值得追蹤時建議 /watch-repo 沉澱

安裝

透過 marketplace：

/plugin install vault-assistant@agentic-plugins

或本地測試：

claude --plugin-dir ~/workspaces/agentic-plugins/plugins/vault-assistant

初始化 vault

在你想當作 vault root 的目錄執行：

/vault-assistant:install

這會：

  1. 建立 PARA 骨架（0-inbox/daily/、Projects/、Areas/、Resources/、Archives/、Templates/ 等）
  2. 從 plugin 內建 templates 複製 Daily / Weekly / Monthly Report Template.md 到 Templates/
  3. 複製 AGENTS.md（vault 操作規範 — PARA placement、wikilink 格式、git workflow）
  4. 建立 CLAUDE.md（@AGENTS.md import）

既有檔案一律不覆蓋，只補缺。

使用範例

> 手上有哪些專案
> 今日還有哪些項目
> /vault-assistant:start-day
> /vault-assistant:end-day
> 幫我把今天完成的 CSI 除錯經驗萃取成 wiki article

前三種會自動委派給 vault-assistant subagent。

依賴

  • Obsidian vault 使用 PARA 結構（plugin 的 install command 會幫你建）
  • Git — 每次 vault 寫入會 auto commit + push，remote 需預先設好
  • gh CLI — gh-daily-log、gh-contribution-report、gh-issues-to-doc 用到
  • Quartz（可選）— 若要發佈成靜態網站，plugin 的 wikilink 規則就是為此校對的

Ceremony 與 PARA 規則

完整規則見 templates/AGENTS.md.template，install 後會複製到 vault root 的 AGENTS.md：

  • PARA 放置：Projects（執行）/ Areas（持續責任）/ Resources（參考）/ Archives（完成）
  • Wikilink：Quartz shortest 模式，一律用 [[檔名]]，不加路徑前綴
  • Git workflow：任何 vault 寫入 → auto git add + commit + push，conventional commits
  • Daily note：0-inbox/daily/YYYY-MM-DD.md，由 /start-day 建立
  • Reports：Weekly Areas/reports/Weekly/YYYY-Wnn.md、Monthly Areas/reports/Monthly/YYYY-MM.md

Hub issue workflow

Vault 以 GitHub Issues 為「執行單位」、vault notes 為「比 issue 活更久的知識」。

  • Issue 放哪：code-bearing 工作放該 code repo，meta/跨 repo 工作集中到 hub repo（就是 vault 本身的 repo，例如 ricky1698/sb）
  • Repo routing：/capture-issue 會先讀 vault 內 Projects/project-repos.md 的 project→repo mapping；只有沒配到時才退回 repo 名稱 heuristic / hub fallback
  • Label 三軸：project:<slug> + type:{task,bug,research,decision,idea} + {now,next,later}——每個 issue 三軸齊全才算歸類好
  • Issue ↔ vault note：task / bug 不配 note，research / decision 配雙向連結的 vault note
  • Flow：Capture（/capture-issue）→ Triage（/start-day 會帶 now issue 簡報）→ Work → Sync → Close → Report（/end-day / /end-week / /end-month 自動回灌 issue 事件流到 vault）

完整規則、label schema、anti-patterns 見 templates/AGENTS.md.template 的「Hub issue workflow」章節；install 時會連同 .github/ISSUE_TEMPLATE/{decision,task,research}.md 與 Projects/project-repos.md seed 一起複製到 vault。

License

MIT