1. 项目概述与核心价值如果你和我一样日常重度依赖 Obsidian 来管理知识、项目和思考那你一定遇到过这样的场景想快速在某个文件夹里新建一个符合特定模板的笔记或者批量处理一批笔记的元数据又或者想把一个复杂的项目想法用 JSON Canvas 画出来。这些操作本身不复杂但频繁地在 Obsidian 界面、文件管理器和命令行之间切换效率就被割裂了。更别提当你尝试用一些 AI 助手比如 Claude Code、Cursor 的 Codex 模式来辅助你处理 Obsidian 库时它们往往对 Obsidian 特有的语法如双链[[ ]]、Callouts、Dataview 查询一知半解生成的代码或内容格式总是不对味。这正是kepano/obsidian-skills这个项目要解决的问题。它本质上是一套“技能包”专门用来“教”那些支持 Agent Skills 规范的 AI 代理或命令行工具让它们能真正理解并操作你的 Obsidian 知识库。简单来说它让 AI 助手从一个普通的文本生成器变成了一个懂你 Obsidian 工作流的“数字管家”。这套技能包覆盖了从最基础的 Markdown 编辑、到高级的 Obsidian Bases 视图构建、再到 JSON Canvas 文件创建甚至直接通过 Obsidian CLI 管理插件和主题。对于任何希望将自动化、AI 辅助与 Obsidian 深度结合的用户这都是一套不可或缺的工具。它的核心价值在于标准化和互操作性。所有技能都遵循统一的 Agent Skills 规范 这意味着你学会一次就能在多个兼容此规范的工具如 Claude Code, Codex CLI, OpenCode上使用。你不用再为每个工具单独编写复杂的提示词或脚本去描述 Obsidian 的语法规则。这套技能包已经帮你定义好了“语言”让 AI 能直接用这种“语言”与你对话并操作你的知识库。2. 核心技能包深度解析obsidian-skills项目目前包含了五个核心技能每个都针对 Obsidian 生态中的一个关键环节。理解每个技能的能力边界和适用场景是高效利用它们的前提。2.1 obsidian-markdown让 AI 精通 Obsidian 语法这是最基础也是最常用的技能。普通的 AI 模型虽然能写 Markdown但对 Obsidian 的“风味” Markdown 往往支持不佳。这个技能详细定义了 Obsidian 的所有特有语法内部链接与双链[[笔记名]]、[[笔记名#标题]]、[[笔记名|别名]]。AI 能正确生成这些链接并理解它们指向的是你库中的其他笔记。嵌入内容![[图片.png]]、![[音频.mp3]]、![[笔记名]]。AI 知道如何嵌入媒体或其他笔记。Callouts [!info]、 [!warning]等。AI 能生成结构化的提示块而不仅仅是普通的引用块。Frontmatter 属性YAML 格式的元数据。AI 能按照你定义的模板正确生成或修改笔记的tags、aliases、date等属性。Dataview 查询虽然不直接执行查询但 AI 能生成正确的 Dataview JS 或内联查询语法方便你粘贴使用。实操心得这个技能最大的价值在于“格式保真”。以前让 AI 帮你写笔记你总得事后手动调整链接格式、添加 Callouts。现在你可以直接下指令“在‘项目日志’文件夹下创建一篇名为‘2024-Q2复盘’的笔记使用 [!summary]开头总结并链接到已有的‘年度目标’和‘Q1复盘’笔记标签为#project/review。” AI 能一次性生成格式完全正确的笔记草稿。2.2 obsidian-bases构建动态数据视图Obsidian Bases 是 Obsidian 推出的一个革命性功能它允许你用类似数据库的视图表格、看板、日历等来组织和筛选笔记。但 Bases 的语法.base文件有其特定结构。这个技能让 AI 能够创建和编辑.base文件理解 Bases 文件的 JSON 结构。定义视图指导 AI 如何配置表格视图的列、看板视图的分组依据、日历视图的日期字段等。编写过滤器使用 Obsidian 的过滤语法如file.tags includes #active或date this week让 AI 帮你构建复杂的数据筛选条件。添加公式列和汇总虽然高级公式需要手动调试但 AI 可以帮你搭建基础框架。注意事项Bases 技能依赖于你对库中笔记属性Frontmatter的良好规划。在让 AI 操作 Bases 前确保你的笔记有清晰、一致的属性结构如status、priority、due-date。否则AI 生成的过滤器可能无法生效。2.3 json-canvas可视化构思与规划JSON Canvas 是 Obsidian Canvas 功能背后的文件格式。这个技能让 AI 能够直接生成.canvas文件你可以直接拖入 Obsidian 的 Canvas 中打开。AI 可以创建节点定义文本节点、文件节点链接到笔记、链接节点。建立连接在节点之间创建有向或无向的连接线并可以设置标签。分组管理将相关节点放入一个组内并移动整个组。设置样式初步定义节点的颜色、位置等但精细排版仍需在 Canvas 界面中手动调整。这个技能非常适合用于项目规划、头脑风暴。你可以对 AI 说“为我创建一个关于‘个人博客重构’的 Canvas。中心节点是主题周围创建‘内容规划’、‘技术选型’、‘发布流程’、‘待办事项’四个子节点组并将‘技术选型’与已有的‘Hugo研究’笔记链接起来。” AI 生成的.canvas文件就是一个可立即使用的可视化蓝图。2.4 obsidian-cli自动化库管理Obsidian 官方提供了一个命令行工具obsidian。这个技能封装了其常用命令让 AI 可以通过命令行与你的 Obsidian 实例交互尤其适合开发者或高级用户插件与主题开发运行obsidian plugin dev启动插件热重载开发模式。库管理获取当前打开的库信息。调试运行obsidian open在指定路径打开 Obsidian或使用--debug标志。重要提示使用此技能前你必须确保系统已全局安装 Obsidian CLI。通常安装 Obsidian 时会自动配置如果没有需要手动将其添加到系统 PATH。AI 只是调用这些命令它无法替你完成环境配置。2.5 defuddle为 AI 准备干净的输入这是一个非常实用的“预处理”技能。它并非直接操作 Obsidian而是调用 Defuddle 工具来清理网页内容。当你让 AI 基于某个网页内容为你总结或生成笔记时直接粘贴的 HTML 往往包含大量导航栏、广告、侧边栏等无用信息这会浪费宝贵的 AI 模型上下文窗口Tokens。Defuddle 技能能指示 AI 先调用 Defuddle 工具处理网页 URL提取出干净的、只有核心正文的 Markdown然后再基于这个干净的内容进行后续操作。这能显著提升 AI 处理网页信息的质量和效率并节省成本。3. 安装与配置全攻略根据你主要使用的 AI 代理或工具安装方式有所不同。以下是针对不同工具的详细步骤和避坑指南。3.1 为 Claude Code 安装技能Claude Code 是 Anthropic 为 Claude 模型提供的代码编辑器集成环境。它会在你的项目根目录下寻找一个.claude文件夹来加载技能。操作步骤打开你的 Obsidian 库所在的根目录即包含.obsidian配置文件夹的目录。在该根目录下创建名为.claude的文件夹如果不存在。将obsidian-skills项目仓库中的所有内容而不仅仅是skills/子目录克隆或复制到这个.claude文件夹中。# 假设你的库根目录是 ~/Documents/MyVault cd ~/Documents/MyVault git clone https://github.com/kepano/obsidian-skills.git .claude/obsidian-skills正确的目录结构应该是~/Documents/MyVault/.claude/obsidian-skills/skills/obsidian-markdown/SKILL.md重启你的 Claude Code 编辑器或重新加载项目。技能应该会自动被发现。常见问题技能没生效首先检查.claude文件夹是否直接在库根目录下而不是在某个子文件夹里。其次确认克隆的是整个仓库保证了完整的skills/skill-name/SKILL.md结构。Claude Code 是通过这个固定的路径结构来识别技能的。3.2 为 Codex CLI 安装技能Codex CLI 通常指 Cursor 编辑器或其他集成 OpenAI Codex 的 CLI 工具所使用的技能系统。它通常将技能存放在用户主目录的特定路径下。操作步骤确定你的 Codex CLI 技能目录。通常是~/.codex/skills但最好查阅你所使用工具的具体文档。将obsidian-skills项目中skills/目录下的每个技能子文件夹分别复制到你的技能目录中。# 进入项目目录 git clone https://github.com/kepano/obsidian-skills.git cd obsidian-skills/skills # 复制每个技能到 Codex 技能目录 cp -r obsidian-markdown obsidian-bases json-canvas obsidian-cli defuddle ~/.codex/skills/重启你的 Codex CLI 或相关编辑器。部分工具可能需要刷新技能列表的命令。3.3 为 OpenCode 安装技能OpenCode 是一个开源的、兼容 Agent Skills 规范的开发环境。它的技能发现机制非常直接。操作步骤OpenCode 的技能目录通常是~/.opencode/skills/。你需要将整个obsidian-skills仓库克隆到这个目录下而不是只复制skills/文件夹。git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills完成克隆后目录结构应为~/.opencode/skills/obsidian-skills/skills/obsidian-markdown/SKILL.md。无需任何配置。OpenCode 会自动扫描~/.opencode/skills/目录下所有子文件夹中的SKILL.md文件。重启 OpenCode技能即可用。踩坑记录这里最容易出错的就是复制错误的目录层级。OpenCode 要求技能仓库的顶层目录在skills/下然后里面再包含skills/skill-name/。如果你只复制了内层的skills/文件夹内容OpenCode 将无法正确识别技能文件。3.4 通用安装方法npx skills对于任何支持npx skills命令的环境通常意味着已安装 Node.js 和agent-smith/skillsCLI 工具这是最快捷的安装方式。操作步骤打开终端。运行以下命令npx skills add gitgithub.com:kepano/obsidian-skills.git或者使用 HTTPS 地址npx skills add https://github.com/kepano/obsidian-skills.git该命令会自动处理克隆和放置技能到正确的、工具约定的全局技能目录中。根据提示可能需要重启你的 AI 代理工具。这个方法省去了手动寻找目录的麻烦但前提是你使用的工具生态已经集成了npx skills这个管理工具。4. 实战应用构建自动化笔记工作流安装好技能后关键在于如何将它们融入日常的工作流。下面我通过几个具体的复合场景展示如何组合使用这些技能。4.1 场景一从网页研究到结构化笔记假设你正在研究“零知识证明”看到一篇不错的博客文章你想将其核心内容转化为一篇带有双链、标签和问题 Callout 的 Obsidian 笔记。传统低效流程复制网页全文 - 粘贴到 Obsidian - 手动删除垃圾内容。阅读文章 - 手动提取关键概念 - 创建新笔记并建立链接。手动格式化添加 [!question]。使用 Skills 的高效流程 你可以对集成了技能的 AI 助手如 Claude Code下达一个复合指令 “使用 defuddle 技能清理这个文章链接https://example.com/zkp-blog的内容。然后使用 obsidian-markdown 技能在我的‘Inbox’文件夹中创建一篇名为‘零知识证明初探’的笔记。要求1. 开头用 [!info]摘要 defuddle 提取的核心观点。2. 在正文中将出现的‘ZKP’、‘区块链’、‘隐私’三个关键词分别链接到库中已有的同名笔记如果不存在则创建空链接。3. 在笔记末尾添加一个 [!question]部分提出三个关于 ZKP 应用场景的开放性问题。4. 为笔记添加标签#crypto/research和#inbox。”AI 的执行逻辑首先调用defuddle技能获取干净的 Markdown 内容。接着调用obsidian-markdown技能按照你指定的 Obsidian 语法规则生成一篇格式完美的笔记草稿。你只需要进行最后的审阅和微调。4.2 场景二用 AI 维护项目看板Bases假设你用一个名为“项目看板”的 Base 文件来管理你的任务Base 通过statustodo,doing,done和priorityhigh,medium,low属性来筛选笔记。日常维护指令 “使用 obsidian-bases 技能帮我更新‘项目看板.base’文件。我需要添加一个新的看板视图按priority属性分组并且只显示status不是done的任务。把这个新视图命名为‘按优先级待办’。”AI 能做什么 它会理解 Bases 的 JSON 结构在你的.base文件中添加一个新的视图配置其中包含正确的分组groupBy: “priority”和过滤filter: “status ! done”逻辑。你无需手动编写 JSON。4.3 场景三快速绘制项目关系图Canvas在启动一个新项目时快速绘制一张关系图有助于理清思路。指令示例 “使用 json-canvas 技能创建一个关于‘家庭服务器搭建’的 Canvas。中心节点是‘家庭服务器’创建‘硬件’、‘软件’、‘网络’、‘维护’四个文本节点作为主要分支。在‘软件’节点下再创建‘Docker’、‘媒体服务’、‘备份工具’三个子节点。将‘媒体服务’节点与库中已有的‘Jellyfin配置’笔记文件关联起来。”结果 AI 会生成一个.canvas文件你只需在 Obsidian 中打开它一个初步的项目脑图就呈现在眼前你可以在此基础上进行拖拽和细化。5. 问题排查与进阶技巧即使按照指南操作你也可能会遇到一些问题。以下是一些常见问题的排查思路和进阶使用技巧。5.1 技能未被识别或加载失败问题现象可能原因解决方案AI 助手完全不知道这些技能技能未安装到正确的目录对照上文第 3 节严格检查目录路径和结构。特别是注意Claude Code 需要整个仓库放在.claude下而OpenCode 需要克隆整个仓库到其skills/目录下。技能列表中有但调用时出错技能文件SKILL.md格式错误或损坏尝试重新克隆仓库。确保网络通畅下载的文件完整。仅部分技能可用技能依赖未满足如obsidian-cli需要本地已安装 CLI确认你的系统环境是否满足技能要求。例如在终端输入obsidian --version检查 CLI 是否可用。对于defuddle可能需要全局安装defuddle-cli(npm install -g defuddle-cli)。npx skills 命令不存在Node.js 环境或特定 CLI 工具未安装安装 Node.js并确认你所用的 AI 代理工具是否支持并通过npx skills管理技能。5.2 提升指令效果的技巧在上下文中提供库结构在让 AI 操作双链时最好能提供一些上下文。例如先让 AI 列出Projects/目录下的文件或者告诉它“请链接到关于‘区块链’的笔记它可能在‘Concepts’文件夹下”。更智能的做法是结合文件读取技能让 AI 先了解你的库。分步复杂操作对于非常复杂的请求如“重构我的整个笔记标签系统”不要指望一条指令完成。将其拆解“第一步使用 obsidian-markdown 技能扫描所有包含#old-tag的笔记。第二步为每一篇笔记建议新的标签#new-taxonomy/subtag。第三步在我确认后批量替换。” 你可以通过多次对话逐步完成。结合使用技能与原生能力AI 代理除了技能还有基础的代码编写、文件读写能力。你可以组合使用。例如“先写一个 Python 脚本找出过去一周修改过的所有 Markdown 文件。然后对每一个文件使用 obsidian-markdown 技能在文件末尾添加一个 [!updated]的 Callout并注明日期。”自定义与扩展obsidian-skills的技能文件SKILL.md是开源的 Markdown 文件。如果你有特殊的 Obsidian 插件语法或自定义格式完全可以复制一份技能文件在此基础上进行修改和增强创建属于你自己的“私有技能”。5.3 安全与隐私考量权限控制这些技能本质上赋予了 AI 读写你指定目录文件的能力。请仅在你信任的、本地的 AI 代理工具中使用它们。避免在不可信的云端 AI 服务上配置指向你本地重要笔记库的技能。操作前备份在进行批量修改如重命名大量标签、修改 Frontmatter之前建议先对库进行备份或者先让 AI 在单篇笔记上执行操作确认无误后再推广。理解 AI 的局限技能提供了“语法能力”但 AI 可能缺乏你库中的“领域知识”。它知道如何创建指向[[年度目标]]的链接但它不知道你的“年度目标”笔记具体是什么内容。关键的逻辑判断和内容审核仍需你亲自把关。我个人深度使用这套技能组合已超过三个月它彻底改变了我与 Obsidian 的交互方式。最大的体会是它把 AI 从一个需要我不断纠正格式的“实习生”变成了一个能严格执行我工作流标准的“熟练助手”。那种无需切换上下文、用自然语言描述需求就能得到格式完美产出的流畅感一旦习惯就再也回不去了。尤其是处理重复性的笔记整理和初始化工作效率提升是数量级的。如果你也生活在 Obsidian 里并且不排斥命令行和 AI那么投入一点时间配置obsidian-skills绝对是值得的。