• AI 技能
• AI 插件

obsidian-skills 是一套专为 Obsidian 设计的 Agent Skills（智能体技能）集合，它遵循公开的 Agent Skills 规范，可被 Claude Code、Codex、Open Code 等技能兼容型 Agent 直接加载使用。本文以该仓库的 README.md 为核心，完整讲解其三种安装方式（Marketplace、npx skills、手动安装到各 Agent），并逐一深入解读仓库内置的五个技能——obsidian-markdown、obsidian-bases、json-canvas、obsidian-cli 与 defuddle，帮助读者在自己的 Obsidian 库中快速部署并让 Agent 具备编辑 Markdown、构建 Bases 数据库、绘制 JSON Canvas、操作 CLI 与清洗网页正文的完整能力。

obsidian-skills 是什么

obsidian-skills 是一个以 "Agent skills for Obsidian" 为定位的开源仓库。其核心思路是：把 Obsidian 生态中最常用的操作能力——Markdown 语法扩展、Bases 数据库文件、JSON Canvas 画布、Obsidian CLI 以及网页内容提取——封装成标准的 Agent Skill，使 AI Agent 在与 Obsidian 配合工作时不再需要依赖脆弱的口头提示，而是加载结构化的、可验证的技能描述。

从仓库结构看，整个仓库以 skills/ 为根目录，每个技能是一个独立文件夹，包含一份SKILL.md（声明技能的name、description与具体操作指引），部分技能还附带references/子目录存放更完整的参考文档。由于这些技能遵循标准的 Agent Skills 规范（规范要求技能以SKILL.md为核心文件、描述使用场景与详细指引），因此同一套技能可以在多个 Agent 产品间无缝复用，这是本项目最大的设计优势。

安装与部署：三种方式任选

README 提供了三条安装路径，覆盖插件生态、npm 工具链与手动配置三种场景。

方式一：通过 Marketplace 插件安装

如果你使用的是支持插件市场的 Agent 环境，可以直接通过两条命令完成安装：

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

第一条命令将 obsidian-skills 添加到插件市场，第二条命令以obsidian@obsidian-skills的形式安装对应的技能包。这种方式最省事，适合日常使用 Obsidian 插件生态的用户。

方式二：通过 npx skills 安装

对于使用 npm 工具链的开发者，npx skills提供了快捷安装：

npx skills add https://gitcode.com/GitHub_Trending/ob/obsidian-skills

若偏好 SSH 协议而非 HTTPS，也可以将地址替换为对应的 SSH 克隆地址后执行npx skills add。该方式会把整个技能仓库拉取到本地的技能管理目录，无需手工搬运文件。

方式三：手动安装到各 Agent

手动方式最为灵活，README 针对三种主流 Agent 分别给出了目录约定。

Claude Code

将本仓库内容放到 Obsidian 库根目录的/.claude文件夹中（或你正在与 Claude Code 配合使用的任意目录）即可。Claude Code 会自动发现并加载该目录下的技能文件。

Codex

把skills/目录整体复制到 Codex 的技能路径（典型位置为~/.codex/skills）。由于 Agent Skills 规范定义了标准技能格式，Codex 可以直接识别其中的SKILL.md。

OpenCode

OpenCode 的安装方式有一个容易踩坑的细节：不要只复制内部的skills/文件夹，而是要把整个仓库完整克隆到技能目录，确保目录结构为~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md：

git clone https://gitcode.com/GitHub_Trending/ob/obsidian-skills.git ~/.opencode/skills/obsidian-skills

克隆完成后，OpenCode 会自动发现~/.opencode/skills/下所有的SKILL.md文件，无需修改opencode.json或任何配置文件，重启 OpenCode 后技能即可生效。

技能总览：一个仓库覆盖五类 Obsidian 能力

README 用一张表格概括了仓库内置的五个技能，这也是整个仓库的"技能地图"：

下面逐一深入解读每个技能的定位与核心用法，内容均以各技能 SKILL.md 目录中的原始文档为依据。

技能一：obsidian-markdown——Obsidian 风味 Markdown 写作专家

obsidian-markdown 负责创建和编辑合法的 Obsidian Flavored Markdown。Obsidian 在 CommonMark 与 GFM 的基础上扩展了 wikilinks、embeds、callouts、properties、注释等语法，本技能只覆盖 Obsidian 专属扩展，标准 Markdown（标题、加粗、斜体、列表、引用、代码块、表格）视为前置知识。

其创建笔记的标准工作流是：先添加包含title、tags、aliases等属性的 frontmatter（参见 PROPERTIES.md），再用标准 Markdown 书写正文，通过 wikilink（[[Note]]）连接库内笔记、用text指向外部链接，用![[embed]]嵌入其他笔记、图片或 PDF（参见 EMBEDS.md），用> [!type]添加高亮提示框（参见 CALLOUTS.md），最后在阅读视图中核验渲染效果。

关键语法速记：

[[Note Name|Display Text]] 自定义显示文本的 wikilink ![[image.png|300]] 带宽度嵌入图片 > [!warning] Custom Title 自定义标题的 callout > [!faq]- Collapsed by default 默认折叠的 callout ==Highlighted text== Obsidian 专属高亮 %%comment%% 阅读视图隐藏的注释

此外该技能还覆盖行内/块级 LaTeX 数学公式、Mermaid 流程图（可通过class NodeName internal-link;让 Mermaid 节点链接到库内笔记）、脚注（含^[inline]行内脚注）等能力，并提供了一个包含任务列表、callout、数学公式、图片嵌入与笔记引用的完整示例笔记。该技能在所有 Obsidian 专属 Markdown 能力上都有完整覆盖，是让 Agent 写出"原生 Obsidian 笔记"的关键。

技能二：obsidian-bases——在库中构建数据库视图

obsidian-bases 面向.base文件（本质上是合法的 YAML），让 Agent 能为笔记构建类似数据库的视图。其工作流为：创建.base文件 → 用filters定义数据范围（按标签、文件夹、属性或日期筛选）→ 可选地在formulas中定义计算属性 → 配置一个或多个视图（table、cards、list、map，并用order指定展示属性）→ 校验 YAML 语法与属性引用 → 在 Obsidian 中打开验证。

文件核心结构如下：

filters: and: - 'status == "active"' - not: - 'file.hasTag("archived")' formulas: days_until_due: 'if(due_date, (date(due_date) - today()).days, "")' views: - type: table name: "Active Tasks" order: - file.name - status summaries: price: Sum

该技能深入讲解了过滤器语法（支持and、or、not递归组合与嵌套）、比较运算符（==、!=、>、<、>=、<=、&&、||、!）、三类属性（frontmatter 属性、file.*文件元数据、formula.*计算属性），并给出完整的 file.* 属性参考表（如file.name、file.path、file.mtime、file.backlinks等）以及this关键字在不同上下文（主内容区 / 嵌入 / 侧边栏）中的指向规则。

公式语法是该技能的深度主题：涵盖算术、if()条件逻辑、字符串格式化、日期格式化与日期差值计算。特别值得警惕的是Duration 类型陷阱——两个日期相减得到的是 Duration 而非数字，必须先访问.days、.hours等字段再应用数值函数，直接调用.round(0)会报错。日期运算支持y/M/d/w/h/m/s等时长单位（如"now() + \"1 day\""）。完整函数参考见 FUNCTIONS_REFERENCE.md。

技能还内置了三套完整示例（任务追踪 Base、阅读清单 Base、每日笔记索引 Base）、Base 嵌入 Markdown 的方式（![[MyBase.base#View Name]]可指定视图）、YAML 引号规则（含冒号未加引号、公式内双引号嵌套等典型报错场景）以及常见公式错误排查（Duration 数学错误、缺失 null 检查、引用未定义公式等）。默认汇总公式涵盖Average、Min、Max、Sum、Range、Median、Stddev、Earliest、Latest、Checked、Unchecked、Empty、Filled、Unique，足以覆盖绝大多数统计需求。

技能三：json-canvas——用代码绘制可视化画布

json-canvas 面向.canvas文件，遵循 JSON Canvas 规范 1.0。画布文件由两个顶层数组构成：

{ "nodes": [], "edges": [] }

技能给出了四类常见工作流：新建画布（生成 16 位十六进制节点 ID，如"6f0ad84f44ce9c17"，补齐id/type/x/y/width/height必填字段）、向现有画布追加节点（保证 ID 不冲突，节点间距留 50–100px）、连接两个节点（设置fromNode/toNode，可选fromSide/toSide锚点与label标签）、编辑现有画布（修改后重新校验 ID 唯一性与边引用完整性）。

节点类型与必填属性：

边（edge）的属性包括fromNode、toNode（必填）、fromSide/toSide（top/right/bottom/left）、fromEnd/toEnd（none/arrow，默认分别为none/arrow）、color与label。颜色支持预设"1"–"6"（红、橙、黄、绿、青、紫，具体色值由应用自定义）或十六进制如"#FF0000"。

该技能还强调几个实战要点：节点数组顺序决定 z-index（第一个在最底层）；坐标可为负值，x向右、y向下增长，位置是左上角；布局建议按 10 或 20 的倍数对齐网格；文本内容换行必须用 JSON 的\n，误写成字面\\n会被 Obsidian 渲染成\和n两个字符。最后还附有一份八项校验清单（ID 唯一性、边引用有效性、必填字段、类型与侧边/端点枚举合法性、颜色合法性与 JSON 可解析性），并指向 EXAMPLES.md 查看思维导图、项目看板、研究画布、流程图等完整示例。

技能四：obsidian-cli——命令行驱动整个 Obsidian

obsidian-cli 让 Agent 通过obsidian命令与正在运行中的Obsidian 实例交互，是五个技能中唯一需要 Obsidian 保持打开的前置条件的技能。

命令语法分两类：参数用=接收值（带空格的值需加引号，如obsidian create name="My Note" content="Hello world"），标志是无值的布尔开关（如silent、overwrite）。多行内容用\n表示换行、\t表示制表符。

文件定位支持两种方式：file=<name>按 wikilink 方式解析（只需名称，无需路径或扩展名），path=<path>使用从库根开始的精确路径；两者都省略时作用于当前活动文件。默认作用于最近聚焦的库，可用vault=<name>作为首个参数指定目标库：

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

常用命令模式一览：

obsidian read file="My Note" obsidian create name="New Note" content="# Hello" template="Template" silent obsidian append file="My Note" content="New line" obsidian search query="search term" limit=10 obsidian daily:append content="- [ ] New task" obsidian property:set name="status" value="done" file="My Note" obsidian tasks daily todo obsidian backlinks file="My Note"

通用修饰符方面，--copy可将任意命令输出复制到剪贴板，silent防止文件被打开，total用于列表类命令输出总数。

对于插件与主题开发者，技能还提供了一套完整的"开发/测试循环"：obsidian plugin:reload id=my-plugin重载插件 →obsidian dev:errors检查错误 →obsidian dev:screenshot path=screenshot.png截图、obsidian dev:dom selector=".workspace-leaf" text检查 DOM →obsidian dev:console level=error查看控制台日志。此外还有obsidian eval code="app.vault.getFiles().length"在应用上下文执行 JavaScript、obsidian dev:css检查 CSS 值、obsidian dev:mobile on切换移动端模拟等进阶命令。运行时执行obsidian help可查看全部命令（含 CDP 与调试器控制）。

技能五：defuddle——网页正文清洗，为 Agent 省 token

defuddle 的作用场景非常明确：当用户给出 URL 要求阅读或分析在线文档、文章、博客时，优先使用 Defuddle CLI 提取干净的网页正文，而不是 WebFetch。它能剔除导航栏、广告等杂讯，显著降低 token 消耗。注意一个边界：以.md结尾的 URL 本身就是 Markdown，应直接使用 WebFetch 而非本技能。

若本机未安装，先执行npm install -g defuddle。核心用法是始终使用--md输出 Markdown：

defuddle parse <url> --md defuddle parse <url> --md -o content.md # 保存到文件 defuddle parse <url> -p title # 提取特定元数据

输出格式可通过标志切换：--md输出 Markdown（默认推荐）、--json输出同时含 HTML 与 Markdown 的 JSON、不带标志输出 HTML、-p <name>提取指定元数据属性（如 title、description、domain）。这个技能在 Agent 处理"读网页写笔记"类任务时与 obsidian-markdown 天然形成工作流组合：先用 defuddle 清洗网页，再以 obsidian-markdown 语法落成库内笔记。

如何选择与组合这些技能

五个技能覆盖了 Obsidian 日常使用的高频场景，可按任务类型快速匹配：

• 写作与笔记整理：首选 obsidian-markdown，产出符合 Obsidian 生态的笔记（wikilink、callout、properties、embed 一应俱全）；
• 需要数据库式视图：如任务追踪、阅读清单、每日笔记索引，交给 obsidian-bases，配合过滤器与公式自动计算；
• 可视化表达：思维导图、流程图、项目看板等视觉结构，使用 json-canvas 生成.canvas文件；
• 与正在运行的 Obsidian 交互：读取/创建/搜索笔记、设置属性、管理每日笔记，甚至调试插件，使用 obsidian-cli；
• 网页内容转为笔记：defuddle 负责清洗网页正文，为后续 Markdown 写作提供干净的输入。

例如一条典型的"把这篇网页文章做成笔记"链路可以是：defuddle 提取正文 → obsidian-markdown 创建带 frontmatter 的笔记并嵌入图片与链接 → 如有结构化需求再用 obsidian-bases 生成视图。这些技能彼此独立又互相衔接，共同构成了一个可观的 Obsidian Agent 工具箱。

结语

obsidian-skills 的价值在于把 Obsidian 庞大而分散的能力收敛为一份可被多种 Agent 直接加载的标准技能集。无论你通过 Marketplace、npx skills 还是手动目录配置，都能在三五分钟内完成部署，随后即可让 Agent 写出地道的 Obsidian Flavored Markdown、维护 Bases 数据库视图、编排 JSON Canvas 画布、驱动 CLI 管理库内容，并用 Defuddle 高效清洗网页输入。具体的语法细节、函数参考与完整示例，均可继续在本仓库的 skills/ 目录下各技能的SKILL.md与references/文档中按需查阅。

• AI 技能
• AI 插件