前言¶

管理 Obsidian vault 時，很多動作是重複的：建一篇筆記、往日記裏追加一行任務、按狀態改屬性、查某篇筆記的反向鏈接。這些動作都能在圖形界面裏點出來，但點一遍和敲一條命令的成本不一樣，批量做的時候差距更大。插件和主題開發更是如此：改完代碼要重載、看報錯、截圖、查 DOM，來回在編輯器和 Obsidian 之間切換。

這個 Skill 把這類操作統一到命令行。它不自己造一套接口，而是調用 Obsidian 自帶的 obsidian CLI，並把參數寫法、文件定位規則、插件調試流程寫成 Agent 能直接照做的說明。

這是什麼¶

一句話定位：把 Obsidian 官方 CLI 的操作方式整理成 Agent Skill，讓 Agent 能讀寫和管理 vault 內容，也能開發調試插件與主題。

出品方：kepano（Obsidian 官方團隊）維護的開源倉庫 kepano/obsidian-skills，本 Skill 是倉庫裏的 obsidian-cli，版本 1.0.0。SkillHub 上發佈者是 user_2bd73b3a，座標 @user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a，分類 knowledge-management，來源 community，無需 API Key。

解決什麼問題：Agent 想要操作 vault 時，默認只能讀寫文件，不知道 obsidian 這個命令存在、不知道參數怎麼寫、不知道哪些操作需要 Obsidian 處於運行狀態。

核心能力¶

分兩類，都來自 Skill 的 description 與 SKILL.md 正文。

vault 內容操作：

• 讀取、創建、追加筆記
• 搜索 vault 內容
• 管理任務（todo / done，按日記維度）
• 讀寫筆記屬性（properties）
• 列標籤並按使用次數排序
• 查反向鏈接
• 讀寫每日筆記

插件與主題開發：

• 重載插件以加載改動
• 運行 JavaScript（在應用上下文裏 eval）
• 捕獲運行期錯誤
• 截圖
• 檢查 DOM 與 CSS 值
• 切換移動端模擬
• CDP 與 debugger 相關控制

命令約定¶

這部分是動手前必須知道的，否則參數會寫錯。

參數用 = 傳值，帶空格的值要加引號：

obsidian create name="My Note" content="Hello world"

開關（flag）不帶值：

obsidian create name="My Note" silent overwrite

多行內容用 \n 表示換行，\t 表示製表符。

文件定位有兩種方式：file=<name> 按 wikilink 規則解析，只寫名字，不用路徑和擴展名；path=<path> 寫從 vault 根目錄起的精確路徑，例如 folder/note.md。兩條都不給時，命令作用於當前活動文件。

vault 定位：默認作用於最近聚焦的那個 vault，用 vault=<name> 作爲第一個參數可指定：

obsidian vault="My Vault" search query="test"

常用修飾：任意命令加 --copy 把輸出複製到剪貼板；加 silent 防止文件被打開；列表類命令加 total 只拿計數。

完整命令列表以 obsidian help 爲準，它會隨版本更新，官方文檔在 https://help.obsidian.md/cli 。

安裝與啓用¶

這個 Skill 遵循通用 Agent Skills 規範，Claude Code、Codex、Open Code 都能加載，但安裝路徑不一樣。

Claude Code¶

三種方式，任選一種。

走 Claude Code 插件市場：

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

走 npx skills：

npx skills add git@github.com:kepano/obsidian-skills.git

偏好 https 的話用：

npx skills add https://github.com/kepano/obsidian-skills

手動安裝：把倉庫內容放進 Obsidian vault（或你正在配合 Claude Code 使用的目錄）下的 .claude 文件夾。參考 Claude 官方 Agent Skills 文檔。

Codex¶

把倉庫裏的 skills/ 目錄複製到 Codex 的 skills 路徑，通常是 ~/.codex/skills。規範格式見 https://agentskills.io/specification 。

OpenCode¶

這裏有個坑：必須整倉克隆，不能只複製內層 skills/ 文件夾，否則目錄結構不對。

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

目標是 ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md。OpenCode 會自動發現 ~/.opencode/skills/ 下所有 SKILL.md，不需要改 opencode.json 或任何配置文件，重啓後生效。

Cursor¶

倉庫 README 未給出 Cursor 的安裝路徑或配置方式，這裏不做推測。按 Agent Skills 規範，把 SKILL.md 放到 Cursor 能識別的 skills 目錄是常規做法，但具體路徑需要自己查證。

典型用法¶

下面這些命令可以直接在 shell 裏跑，也適合直接交給 Agent 執行。

讀一篇筆記：

obsidian read file="My Note"

按模板新建筆記，不打開窗口：

obsidian create name="New Note" content="# Hello" template="Template" silent

往已有筆記追加內容：

obsidian append file="My Note" content="New line"

搜索 vault，只取前 10 條：

obsidian search query="search term" limit=10

每日筆記讀寫：

obsidian daily:read
obsidian daily:append content="- [ ] New task"

屬性與任務：

obsidian property:set name="status" value="done" file="My Note"
obsidian tasks daily todo
obsidian tags sort=count counts
obsidian backlinks file="My Note"

插件與主題調試流程¶

改完插件或主題代碼後，按這個順序走，能少繞路。

第一步，重載插件讓改動生效：

obsidian plugin:reload id=my-plugin

第二步，查運行期錯誤。有報錯就修完回到第一步：

obsidian dev:errors

第三步，視覺確認。截圖或直接看 DOM：

obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

第四步，翻控制台輸出，排查 warning 和異常日誌：

obsidian dev:console level=error

另外幾個開發期常用命令：在應用上下文裏跑 JavaScript：

obsidian eval code="app.vault.getFiles().length"

查某個元素的 CSS 值：

obsidian dev:css selector=".workspace-leaf" prop=background-color

開啓移動端模擬：

obsidian dev:mobile on

更多開發命令（含 CDP 和 debugger 控制）用 obsidian help 查看。

適用場景與注意¶

適合這幾類人：

• vault 裏筆記、任務、屬性數量已經多到手動點不划算，希望用腳本或 Agent 批量處理的人
• 需要在 CI 或本地腳本里對 vault 做檢索、統計、批量改寫的人
• 正在寫 Obsidian 插件或主題，想要一條可復現的重載—查錯—驗證流程的人

幾個限制和坑：

• 依賴 Obsidian 處於運行狀態。Skill 明確寫了 requires Obsidian to be open，CLI 是和已打開的實例通信，不是直接讀寫 vault 目錄。
• 默認作用於最近聚焦的 vault。多 vault 環境下不寫 vault=<name> 容易操作錯對象。
• file= 走 wikilink 解析規則，同名筆記或同名附件場景下行爲需要自己確認，要求精確命中時用 path=。
• 命令列表以 obsidian help 和官方文檔爲準，Skill 只覆蓋常用命令，不保證列出全部。
• 寫類命令有副作用（會改 vault 裏的文件），跑批量前建議先在小範圍驗證，並確認加上了 silent，避免彈出窗口打斷流程。

結尾¶

這個 Skill 的價值不在發明新能力，而在把 Obsidian 官方 CLI 的參數約定和插件調試流程固化下來，讓 Agent 不再靠猜。命令本身是穩定的，會變動的是命令全集，所以遇到沒見過的子命令時回 obsidian help 查。

SkillHub 地址：https://www.skillhub.cn/skills/user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a （接口地址 https://api.skillhub.cn/user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a ）。上游倉庫：https://github.com/kepano/obsidian-skills ，其中本 Skill 在 skills/obsidian-cli/SKILL.md。

截至抓取時，SkillHub 頁面顯示評分 100000，下載 1468，安裝 0。評分和下載數會變動，以頁面實時數據爲準。