obsidian

Obsidian

一个涵盖 Obsidian 所有功能的技能：CLI、Bases（.base 文件）和 Obsidian Flavored Markdown。整合了原先的 obsidian-cli、obsidian-bases 和 obsidian-markdown 技能。

来源： 源自 kepano/obsidian-skills（MIT）。必须先运行 Obsidian，CLI 或 MCP 命令才能正常工作。

适用场景

• 通过命令行与库交互（创建／读取／搜索／管理笔记、任务和属性）。

• 使用筛选器和公式构建或编辑 Base（类似数据库的笔记视图）。

• 编写 Obsidian Flavored Markdown（维基链接、嵌入内容、标注框、属性）。

• 开发或调试 Obsidian 插件或主题。

• 用户用英语请求或提及此技能（例如，“use /obsidian”、“run obsidian”）。

• 用户用葡萄牙语请求或提及此技能（例如，“use /obsidian”、“execute obsidian”）。

不适用场景

• 不要将其用于通用 Markdown 文件或非 Obsidian 笔记工具。
• 不要针对用户未明确指定的库。
• 未经用户确认，不要自动安装 mcp-obsidian-cli 包或运行 obsidian 二进制文件。

安全与防护措施

• 先取得用户确认：执行前，先确认目标库以及要运行的任何 obsidian 命令。
• 禁止自动执行：仅运行读取或修改指定库的命令；不要运行系统范围的命令，也不要在未经明确许可的情况下执行任意插件／主题。
• MCP 回退需用户选择：如果缺少 obsidian CLI，应将 mcp-obsidian-cli 作为可选回退方案，并等待用户批准安装。
• 仅限库内操作：不要使用 Obsidian CLI 访问库根目录以外的文件。

三个领域

1. CLI

针对正在运行的 Obsidian 实例运行 obsidian，执行库操作、插件／主题开发、DOM／截图检查。 请参阅 references/obsidian-cli.md 中的完整命令参考和快速入门示例。

运行任何 obsidian 命令前，请确认用户要操作的库并确认命令。未经用户明确许可，不要自动安装 mcp-obsidian-cli 或任何 Obsidian 插件。

2. Bases

.base 文件是有效的 YAML，用于定义笔记的筛选器、公式和视图（表格／卡片／列表／地图）。 请参阅 references/obsidian-bases.md 和 references/FUNCTIONS_REFERENCE.md 中的完整函数列表。

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'
formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
views:
  - type: table
    name: "Active Tasks"
    order: [file.name, status, formula.days_until_due]

3. Markdown（Obsidian Flavored）

维基链接 [[Note]]、嵌入内容 ![[note.png|300]]、标注框 > [!warning]、属性／前置元数据、高亮 ==text==、Mermaid、数学公式。 请参阅 references/obsidian-markdown.md，以及 references/CALLOUTS.md、references/EMBEDS.md、references/PROPERTIES.md。

工作流

创建 Obsidian 笔记

1. 在顶部添加前置元数据／属性（参见 references/PROPERTIES.md）。
2. 使用标准 Markdown 和 Obsidian 语法（维基链接、嵌入内容、标注框）编写内容。
3. 在阅读视图中确认渲染效果。

构建 Base

1. 创建包含有效 YAML 的 .base 文件。
2. 定义 filters（全局／视图级）和可选的 formulas。
3. 添加一个或多个 views（table／cards／list／map）。
4. 验证 YAML（注意引号规则）；在 Obsidian 中打开并确认渲染效果。

注册 CLI／开发插件

1. 引导用户前往 Settings → General → Command line interface → Register CLI；然后重启终端。
2. 用户确认代码更改后，仅针对明确指定的插件运行 obsidian plugin:reload 和 obsidian dev:screenshot。

常见错误

错误	症状	修复方法
Obsidian 未运行	CLI/MCP 命令失败	先打开 Obsidian 应用
.base 中的特殊字符未加引号	YAML 错误	为包含 :、{、}、[、]、,、&、*、#、?、|、-、<、>、=、!、%、@ 的字符串加引号
公式中在双引号内使用双引号	解析错误	用单引号包住公式：'if(done, "Yes", "No")'
时长未访问字段	(now()-file.ctime).round(0) 报错	先访问 .days：(now()-file.ctime).days.round(0)
公式中缺少空值检查	属性为空时崩溃	使用 if() 进行保护：if(due, (date(due)-today()).days, "")
混淆 Wikilink 和 Markdown 链接	外部链接失效	Vault 笔记使用 [[Note]]；仅外部链接使用 [text](url)

参考资料

• references/obsidian-cli.md — CLI 安装、语法、命令、插件开发。
• references/obsidian-bases.md — Bases 架构、筛选器、公式、视图、示例。
• references/obsidian-markdown.md — Obsidian Flavored Markdown 语法。
• references/FUNCTIONS_REFERENCE.md — 完整的 Bases 函数参考。
• references/CALLOUTS.md — 所有 Callout 类型。
• references/EMBEDS.md — 所有嵌入类型。
• references/PROPERTIES.md — 所有属性类型和标签规则。