/ 目錄 / 演練場 / obsidian-plugin-skill
● 社群 gapmiss ⚡ 即開即用

obsidian-plugin-skill

作者 gapmiss · gapmiss/obsidian-plugin-skill

一個教導 Claude 如何建構 Obsidian 外掛的 Agent Skill — 涵蓋 Plugin API、manifest.json 及發布流程。

obsidian-plugin-skill 將 Obsidian Plugin API 的結構載入 Claude 的工作記憶:包括 manifest.json + versions.json、main.ts 外掛骨架、設定頁籤、指令、工具列圖示、編輯器擴充,以及官方社群商店所要求的透過 GitHub tag 發布的流程。適合想在一個下午內快速原型開發外掛的使用者。

為什麼要用

核心特性

即時演示

實際使用效果

obsidian-plugin-skill.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-plugin-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/gapmiss/obsidian-plugin-skill",
        "~/.claude/skills/obsidian-plugin-skill"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "obsidian-plugin-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/gapmiss/obsidian-plugin-skill",
        "~/.claude/skills/obsidian-plugin-skill"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "obsidian-plugin-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/gapmiss/obsidian-plugin-skill",
        "~/.claude/skills/obsidian-plugin-skill"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "obsidian-plugin-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/gapmiss/obsidian-plugin-skill",
        "~/.claude/skills/obsidian-plugin-skill"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "obsidian-plugin-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/gapmiss/obsidian-plugin-skill",
        "~/.claude/skills/obsidian-plugin-skill"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "obsidian-plugin-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/gapmiss/obsidian-plugin-skill",
          "~/.claude/skills/obsidian-plugin-skill"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add obsidian-plugin-skill -- git clone https://github.com/gapmiss/obsidian-plugin-skill ~/.claude/skills/obsidian-plugin-skill

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: obsidian-plugin-skill

如何建構並發布你的第一個 Obsidian 外掛

👤 想解決自身需求的 Obsidian 進階使用者 ⏱ ~120 min intermediate

何時使用: 你有明確的工作流程改善需求,並希望在一天內完成一個外掛。

前置條件
  • Node 18+ — nvm install 18
  • 用於測試的本地保存庫 — 建立一個專門用於開發的新 Obsidian 保存庫
  • 已複製 Skill — git clone https://github.com/gapmiss/obsidian-plugin-skill ~/.claude/skills/obsidian-plugin-skill
步驟
  1. 建立外掛鷹架
    Scaffold an Obsidian plugin called 'smart-outline' with a command and a settings tab.✓ 已複製
    → 包含 manifest、main.ts 及建置設定的資料夾
  2. 新增功能
    Implement: on command, open a modal showing the outline of the active note.✓ 已複製
    → 可從目前 MarkdownView 讀取內容的運作中強制回應視窗
  3. 側載並測試
    Install into the dev vault's plugins folder and reload Obsidian.✓ 已複製
    → 外掛出現且指令可正常運作
  4. 準備發布
    Create versions.json and tag a v0.1.0 release.✓ 已複製
    → GitHub 發布版本附帶 main.js + manifest.json

結果: 一個可運作、可安裝的外掛,並可提交至社群商店。

注意事項
  • 忘記 versions.json — 社群商店會拒絕審核 — Skill 會提醒;請務必與 manifest.json 保持同步
  • 引用了不屬於 API 的 Obsidian 內部實作 — 僅使用公開 API;將內部實作視為隨時可能變動的不穩定介面
搭配使用: filesystem · github

為現有外掛新增完整的設定頁籤

👤 正在改善使用者體驗的現有外掛作者 ⏱ ~30 min intermediate

何時使用: 你的外掛功能已增長,需要提供使用者可自訂的選項。

步驟
  1. 規劃設定項目
    Based on my plugin's README, what settings should be user-configurable?✓ 已複製
    → 附有說明的簡短清單
  2. 實作 PluginSettingTab
    Add a PluginSettingTab with those controls.✓ 已複製
    → 在 Obsidian 中顯示設定介面

結果: 一個使用者實際能夠操作的設定頁籤。

注意事項
  • 設定項目過多 — 果斷刪減 — 沒人使用的設定只是累贅

組合

與其他 MCP 搭配,撬動十倍槓桿

obsidian-plugin-skill + filesystem

讀取現有外掛並加以擴充

Read my-plugin/, add a new command that exports the active note as PDF.✓ 已複製
obsidian-plugin-skill + github

自動化打標籤與建立發布版本

Tag v0.2.0 and publish release with the built assets.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
plugin-scaffolding plugin intent 建立新外掛時 0
feature-authoring feature spec + API surface 開發每個功能時 0
settings-tab options 改善使用者體驗時 0
release-flow version bump 發布前 0

成本與限制

運行它的成本

API 配額
none
每次呼叫 Token 數
5–20k per plugin
費用
free
提示
逐一功能開發,而非一次將完整的外掛規格丟給 Claude

安全

權限、密鑰、影響範圍

憑證儲存: 用於發布的 GitHub 金鑰(若需自動化)
資料出站: none at skill layer

故障排查

常見錯誤與修復

Obsidian doesn't load the plugin

確認 manifest.json 是有效的 JSON 且位於正確的保存庫路徑;透過 Ctrl+R 重新載入。

驗證: cat .obsidian/plugins/my-plugin/manifest.json | jq .
Build produces no main.js

執行 esbuild 指令;檢查 tsconfig 的目標設定。

驗證: ls main.js

替代方案

obsidian-plugin-skill 對比其他方案

替代方案何時用它替代權衡
logseq你使用的是 Logseq 而非 Obsidian外掛 API 不同

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills