obsidian-skills 是 Obsidian 團隊成員 Steph Ango 於 2026 年 1 月開源的代理技能庫，目前累積 49,807 星與 3,526 次分支。它包含六個遵循 Agent Skills 規範的技能，讓 Claude Code、Codex 與 OpenCode 等工具直接操作 Obsidian 筆記庫的 Markdown、Bases 資料庫、JSON Canvas 畫布與命令列介面，全部以 MIT 授權釋出。
這批技能的價值不在於新增功能，而在於把一個封閉的筆記應用，轉換成代理可以程式化操作的資料層。過去代理只能處理使用者貼上的片段文字，現在則能依檔名、標籤、屬性與雙向連結定位內容，再以 Obsidian 專有語法寫回檔案。專案自今年 1 月 2 日建立至今約十個月，最近一次提交為 9 月 15 日，程式碼主要由 Markdown 指令文件與 JSON 設定構成，沒有編譯產物。
obsidian-skills 是什麼？
obsidian-skills 是 Obsidian 團隊成員開源的代理技能庫，內含六個技能，可讓 AI 代理直接讀寫筆記庫的筆記與資料庫，採開放授權。
專案的定位是規格層而非應用層。每個技能都是一個獨立目錄，內含 SKILL.md 與參考文件，描述該技能的觸發條件、操作流程與驗證方式。代理在收到相關請求時載入對應技能，之後便依文件指示呼叫檔案系統或命令列工具。由於 Agent Skills 規範已由多個代理工具共同採用，同一份技能文件可以在不同執行環境中重用，不需要為每個代理各寫一套整合。
作者身份是這個專案受到關注的原因之一。Steph Ango 在 GitHub 上的帳號為 kepano，個人檔案標示所屬公司為 Obsidian，公開儲存庫共 39 個，追蹤者 9,378 人。他長期維護 Obsidian 的官方主題與周邊工具，這次把內部使用的技能文件整批公開，等同把官方工作流程的外部介面交付社群。
obsidian-skills 包含哪六大技能？
六個技能涵蓋 Obsidian 風格 Markdown、Bases 資料庫、JSON Canvas 畫布、命令列操作、網頁擷取與模板渲染，各自獨立安裝。
obsidian-markdown 負責 Obsidian 風格的 Markdown，包括雙向連結、嵌入、標註區塊、屬性與註解等非標準擴充。標準 Markdown 的標題、粗體、列表與程式碼區塊被視為代理的既有能力，技能文件只補充 Obsidian 專有的語法差異，並在流程中要求代理建立檔案後回到閱讀視圖確認渲染結果。
obsidian-bases 對應今年推出的 Bases 功能，以 YAML 描述篩選條件、計算公式與檢視設定，可產生表格、卡片、清單與地圖四種視圖。技能文件明確列出驗證步驟，要求代理在寫入後確認 YAML 語法正確、被引用的屬性與公式存在，並提醒未加引號的字串若含特殊字元會導致解析失敗。
json-canvas 處理 .canvas 檔案的節點與連線結構。文件要求代理為每個節點產生不重複的十六字元十六進位識別碼，節點之間保留五十至一百像素間距以避免重疊，寫入後再驗證所有連線端點都能對應到實際節點。
obsidian-cli 是六者之中權限最深的一個。它透過命令列工具與執行中的 Obsidian 實例通訊，可讀取、建立、附加、搜尋筆記，操作每日筆記、任務、屬性與標籤，並能重新載入外掛、執行 JavaScript、擷取錯誤訊息、截圖與檢查 DOM。這意味著代理不只看得到檔案內容，也能觸發應用內部的執行時行為。
defuddle 與 knap 屬於輔助角色。前者把網頁轉為乾淨的 Markdown，移除導覽列與廣告干擾；後者以 JSON 或 CSV 資料渲染 Markdown 模板，適合批次產生筆記。兩者都由同一作者維護，Defuddle 本身已累積 9,739 星，Knap 則置於 Obsidian 官方組織之下，規模較小。
如何安裝 obsidian-skills 到 Claude Code、Codex 或 OpenCode？
安裝方式有三種：外掛市集指令、npx 安裝，或手動複製技能目錄到代理的技能路徑；Claude Code 放筆記庫的 .claude 資料夾。
外掛市集路徑最短，兩行指令即可完成加入與安裝，適合已在 Claude Code 中使用外掛機制的使用者。npx skills 路徑則由技能命令列工具處理，支援全域安裝與非互動選項，對應不同代理的目錄慣例。手動方式最為明確，但各代理的位置不同，需要逐一對照。
Claude Code 的作法是把儲存庫內容放進筆記庫根目錄的 .claude 資料夾，讓技能與筆記庫處於同一工作目錄，代理便能在正確的脈絡下操作。Codex 使用 ~/.codex/skills，OpenCode 使用 ~/.opencode/skills，兩者都屬於使用者層級的共享路徑。
文件特別提醒 OpenCode 使用者不要只複製內層的 skills/ 目錄，而要把整個儲存庫複製成 ~/.opencode/skills/obsidian-skills/skills/<技能名>/SKILL.md 的層級結構。原因是 OpenCode 會自動掃描該路徑下的所有技能文件，目錄層級一旦被壓平，技能便無法被發現。相對於其他代理需要調整設定檔，OpenCode 只要目錄正確、重新啟動即生效。
Obsidian Flavored Markdown 技能解決什麼問題？
通用代理只熟悉標準 Markdown，容易寫錯雙向連結、嵌入與標註區塊。此技能補上 Obsidian 專有語法，並要求寫入後驗證渲染結果。
Obsidian 在 CommonMark 與 GFM 之上擴充了多種語法，包括以雙方括號表示的內部連結、加上驚嘆號的嵌入語法、以箭頭與方括號構成的標註區塊，以及置於檔案頂端的屬性區塊。這些結構在一般 Markdown 編輯器中只會被視為純文字，但在 Obsidian 中具有實際的索引與導覽意義。
技能文件對連結型態給出明確判準：筆記庫內部使用雙向連結，因為 Obsidian 會在檔案更名時自動追蹤並更新；外部網址才使用標準 Markdown 連結。這個區分看似細節，實際上決定了筆記庫在長期維護中是否會產生大量失效連結。
區塊識別碼的規則同樣被寫進文件。段落可在結尾附加識別碼，列表與引用區塊則需把識別碼獨立成行，否則連結會指向錯誤位置。這類規則難以從通用訓練資料中推得，必須以文件形式明確交付。
Bases 與 JSON Canvas 技能帶來什麼能力？
Bases 技能讓代理以 YAML 建立可篩選的資料庫視圖；JSON Canvas 技能讓代理產生節點與連線的畫布。兩者把筆記庫升級為結構化資料。
Bases 的設計把篩選邏輯寫成表達式，支援以 and、or、not 遞迴組合條件，並可依標籤、資料夾、屬性值或日期範圍限定範圍。計算公式集中在 formulas 區塊定義，再於各視圖中引用，顯示名稱則由 properties 段落統一映射。這種分層讓同一份資料可以產生多種檢視，而不必複製內容。
技能文件對常見錯誤的提示相當具體：未加引號的字串若含有 YAML 特殊字元會導致解析失敗、引號不匹配會使公式失效、引用未定義的公式會讓整份檔案無法載入。這些都是代理在自動生成設定時最容易踩到的問題。
JSON Canvas 遵循 1.0 版規格，檔案由節點與連線兩個頂層陣列構成。節點需具備識別碼、類型、座標、寬度與高度，連線則以來源與目標節點識別碼串接。技能文件的流程要求代理在每次新增節點時重新檢查識別碼唯一性與座標間距，並在寫入後解析 JSON 確認結構完整。
Defuddle 與 Knap 在流程中扮演什麼角色？
Defuddle 把網頁轉為乾淨 Markdown，降低代理讀取的雜訊；Knap 以資料檔渲染模板，適合批次產生筆記。兩者負責輸入清洗與輸出量產。
Defuddle 的定位是取代代理內建的網頁抓取。技能文件直接建議優先使用它處理一般網頁，理由是它會移除導覽、廣告與版面雜訊，只保留主要內容，因而顯著降低上下文長度。命令列支援 Markdown 輸出、存檔與單一 metadata 欄位查詢，代理可先取標題與描述判斷相關性，再決定是否抓取全文。
Knap 處理反向的動作。它以模板搭配資料檔產生 Markdown，支援變數、過濾器與條件邏輯，並要求 Node.js 20 以上環境。技能文件建議代理先透過命令列的離線參考查詢語法與過濾器清單，再組合模板，避免憑記憶寫出錯誤語法。
兩者串接後形成一條完整的知識輸入管線：網頁經 Defuddle 轉為結構化文字，再由 Knap 套入固定格式寫成筆記，最後由 Obsidian 的連結與屬性建立索引。這條管線的每一段都有對應技能，代理不需要自行發明格式。
obsidian-skills 的數據表現如何？
截至 2026 年 10 月 20 日，專案累積 49,807 星、3,526 次分支、74 個待處理議題，採 MIT 授權，最近一次提交為 9 月 15 日，提交總數 49 次。
星數與提交數的比例值得注意。49 次提交對應近五萬星，平均每次提交換來約一千個星標，反映社群的關注主要集中在意義層面而非程式碼規模。專案本身沒有主要程式語言，語言統計為空，內容以 Markdown 與 JSON 為主，這也是它能被多種代理共用的原因。
分支數 3,526 相對於星數約為百分之七，屬於中等偏高的比例，通常表示使用者不只收藏，也有實際取用與改寫的意圖。74 個待處理議題相對於提交量則偏高，說明維護節奏偏慢，最近一次提交已是九月中的事，外掛版本停在 1.0.1。
Obsidian 為何投入代理技能生態？
代理已成知識工作的主要入口，筆記庫若不能被直接操作，內容就會外流。Obsidian 以開源技能接軌代理生態，既保住資料主權，也擴大場景。
這個專案的戰略意義大於技術意義。Obsidian 的核心主張是資料以純文字檔案儲存在使用者本機，不依賴廠商伺服器；這個主張在代理時代反而成為優勢，因為代理需要的是可讀寫的檔案，而非封閉的雲端 API。把操作技能開源，等於宣告任何代理都能成為 Obsidian 的用戶端。
時間點同樣關鍵。Agent Skills 規範在過去一年成為多個代理工具的共同標準，涵蓋 Claude Code、Codex 與 OpenCode。當技能文件可以在不同代理之間通用，應用程式要爭取的不是獨家整合，而是成為代理預設會造訪的資料來源。Obsidian 選擇在規範成形期就把六個核心能力補齊，屬於低成本、高曝光的布局。
與同類專案的差別在於授權與邊界。多數代理整合方案由第三方開發，透過非官方 API 或瀏覽器自動化操作應用，穩定性取決於對方是否改版。obsidian-skills 由官方團隊成員維護，直接對接命令列與檔案格式，並以 MIT 授權允許任意修改與再散布，降低了生態依賴的風險。
obsidian-skills 值得安裝嗎？
值得，前提是筆記庫已具備一致的目錄與屬性習慣。若筆記雜亂無結構，代理寫入的連結與屬性反而會放大混亂；建議先整理命名與標籤規則，再啟用技能，效益最明顯。
適用場景集中在三類。第一類是內容研究，使用者要求代理閱讀網頁、整理摘要並寫成帶有出處連結的筆記，Defuddle 與 markdown 技能正好覆蓋。第二類是資料維護，例如依屬性批次更新專案狀態、依日期重建每日筆記索引，Bases 與 CLI 技能可完成。第三類是視覺化整理，把會議記錄或研究架構轉成畫布，由 JSON Canvas 技能負責。
限制也需要說明。技能文件是行為指引，不是執行沙箱，代理的實際權限取決於執行環境。obsidian-cli 能重新載入外掛與執行 JavaScript，若代理在未經確認的情況下操作，風險由使用者承擔。建議在初次使用時限制代理只能寫入特定資料夾，確認行為符合預期後再放寬。
維護節奏是另一個觀察點。專案自九月後沒有新提交，外掛版本停在 1.0.1，待處理議題累積至 74 個。對於長期依賴此流程的使用者，需要評估官方後續更新頻率，或考慮自行分支維護，MIT 授權對此沒有設限。
出處連結有哪些？
專案原始碼與技能文件位於 GitHub 的 kepano/obsidian-skills，採 MIT 授權；輔助工具 Defuddle 與 Knap 另有獨立儲存庫。
專案原始碼與完整技能文件可於 github.com/kepano/obsidian-skills 取得。Defuddle 位於 github.com/kepano/defuddle，Knap 位於 github.com/obsidianmd/knap。Agent Skills 規範文件見 agentskills.io/specification，Obsidian 命令列說明見官方文件 help.obsidian.md/cli。
總結：obsidian-skills 適合哪些使用者？
最適合已用 Obsidian 管理知識、同時使用 Claude Code 或 Codex 的工作者。六個技能補上筆記庫與代理之間的介面，讓既有內容可被程式化處理。
obsidian-skills 的意義在於把一個以人為中心的筆記工具，改造為代理也能參與的資料層。六個技能各自對應一種檔案格式或操作介面，組合起來覆蓋從網頁擷取、模板渲染、筆記撰寫、資料庫檢視到畫布整理的完整路徑。近五萬星與三千多次分支說明這個需求真實存在，而 MIT 授權則讓它具備被長期分支維護的可能。
對於正在評估代理工作流程的團隊，這個專案提供了一個可參照的樣板：技能文件如何描述觸發條件、如何要求驗證、如何界定權限邊界，都有具體示範。至於是否立即導入，取決於筆記庫本身的結構化程度；資料越整齊，代理能發揮的效益越大。
