前言¶
管理 Obsidian vault 时，很多动作是重复的：建一篇笔记、往日记里追加一行任务、按状态改属性、查某篇笔记的反向链接。这些动作都能在图形界面里点出来，但点一遍和敲一条命令的成本不一样，批量做的时候差距更大。插件和主题开发更是如此：改完代码要重载、看报错、截图、查 DOM，来回在编辑器和 Obsidian 之间切换。
这个 Skill 把这类操作统一到命令行。它不自己造一套接口，而是调用 Obsidian 自带的 obsidian CLI，并把参数写法、文件定位规则、插件调试流程写成 Agent 能直接照做的说明。
这是什么¶
一句话定位：把 Obsidian 官方 CLI 的操作方式整理成 Agent Skill，让 Agent 能读写和管理 vault 内容，也能开发调试插件与主题。
出品方：kepano（Obsidian 官方团队）维护的开源仓库 kepano/obsidian-skills，本 Skill 是仓库里的 obsidian-cli，版本 1.0.0。SkillHub 上发布者是 user_2bd73b3a，坐标 @user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a，分类 knowledge-management，来源 community，无需 API Key。
解决什么问题：Agent 想要操作 vault 时，默认只能读写文件，不知道 obsidian 这个命令存在、不知道参数怎么写、不知道哪些操作需要 Obsidian 处于运行状态。
核心能力¶
分两类，都来自 Skill 的 description 与 SKILL.md 正文。
vault 内容操作：
- 读取、创建、追加笔记
- 搜索 vault 内容
- 管理任务（todo / done，按日记维度）
- 读写笔记属性（properties）
- 列标签并按使用次数排序
- 查反向链接
- 读写每日笔记
插件与主题开发：
- 重载插件以加载改动
- 运行 JavaScript（在应用上下文里 eval）
- 捕获运行期错误
- 截图
- 检查 DOM 与 CSS 值
- 切换移动端模拟
- CDP 与 debugger 相关控制
命令约定¶
这部分是动手前必须知道的，否则参数会写错。
参数用 = 传值，带空格的值要加引号：
obsidian create name="My Note" content="Hello world"
开关（flag）不带值：
obsidian create name="My Note" silent overwrite
多行内容用 \n 表示换行，\t 表示制表符。
文件定位有两种方式：file=<name> 按 wikilink 规则解析，只写名字，不用路径和扩展名；path=<path> 写从 vault 根目录起的精确路径，例如 folder/note.md。两条都不给时，命令作用于当前活动文件。
vault 定位：默认作用于最近聚焦的那个 vault，用 vault=<name> 作为第一个参数可指定：
obsidian vault="My Vault" search query="test"
常用修饰：任意命令加 --copy 把输出复制到剪贴板；加 silent 防止文件被打开；列表类命令加 total 只拿计数。
完整命令列表以 obsidian help 为准，它会随版本更新，官方文档在 https://help.obsidian.md/cli 。
安装与启用¶
这个 Skill 遵循通用 Agent Skills 规范，Claude Code、Codex、Open Code 都能加载，但安装路径不一样。
Claude Code¶
三种方式，任选一种。
走 Claude Code 插件市场：
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills
走 npx skills：
npx skills add git@github.com:kepano/obsidian-skills.git
偏好 https 的话用：
npx skills add https://github.com/kepano/obsidian-skills
手动安装：把仓库内容放进 Obsidian vault（或你正在配合 Claude Code 使用的目录）下的 .claude 文件夹。参考 Claude 官方 Agent Skills 文档。
Codex¶
把仓库里的 skills/ 目录复制到 Codex 的 skills 路径，通常是 ~/.codex/skills。规范格式见 https://agentskills.io/specification 。
OpenCode¶
这里有个坑：必须整仓克隆，不能只复制内层 skills/ 文件夹，否则目录结构不对。
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills
目标是 ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md。OpenCode 会自动发现 ~/.opencode/skills/ 下所有 SKILL.md，不需要改 opencode.json 或任何配置文件，重启后生效。
Cursor¶
仓库 README 未给出 Cursor 的安装路径或配置方式，这里不做推测。按 Agent Skills 规范，把 SKILL.md 放到 Cursor 能识别的 skills 目录是常规做法，但具体路径需要自己查证。
典型用法¶
下面这些命令可以直接在 shell 里跑，也适合直接交给 Agent 执行。
读一篇笔记：
obsidian read file="My Note"
按模板新建笔记，不打开窗口：
obsidian create name="New Note" content="# Hello" template="Template" silent
往已有笔记追加内容：
obsidian append file="My Note" content="New line"
搜索 vault，只取前 10 条：
obsidian search query="search term" limit=10
每日笔记读写：
obsidian daily:read
obsidian daily:append content="- [ ] New task"
属性与任务：
obsidian property:set name="status" value="done" file="My Note"
obsidian tasks daily todo
obsidian tags sort=count counts
obsidian backlinks file="My Note"
插件与主题调试流程¶
改完插件或主题代码后，按这个顺序走，能少绕路。
第一步，重载插件让改动生效：
obsidian plugin:reload id=my-plugin
第二步，查运行期错误。有报错就修完回到第一步：
obsidian dev:errors
第三步，视觉确认。截图或直接看 DOM：
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text
第四步，翻控制台输出，排查 warning 和异常日志：
obsidian dev:console level=error
另外几个开发期常用命令：在应用上下文里跑 JavaScript：
obsidian eval code="app.vault.getFiles().length"
查某个元素的 CSS 值：
obsidian dev:css selector=".workspace-leaf" prop=background-color
开启移动端模拟：
obsidian dev:mobile on
更多开发命令（含 CDP 和 debugger 控制）用 obsidian help 查看。
适用场景与注意¶
适合这几类人：
- vault 里笔记、任务、属性数量已经多到手动点不划算，希望用脚本或 Agent 批量处理的人
- 需要在 CI 或本地脚本里对 vault 做检索、统计、批量改写的人
- 正在写 Obsidian 插件或主题，想要一条可复现的重载—查错—验证流程的人
几个限制和坑：
- 依赖 Obsidian 处于运行状态。Skill 明确写了 requires Obsidian to be open，CLI 是和已打开的实例通信，不是直接读写 vault 目录。
- 默认作用于最近聚焦的 vault。多 vault 环境下不写
vault=<name>容易操作错对象。 file=走 wikilink 解析规则，同名笔记或同名附件场景下行为需要自己确认，要求精确命中时用path=。- 命令列表以
obsidian help和官方文档为准，Skill 只覆盖常用命令，不保证列出全部。 - 写类命令有副作用（会改 vault 里的文件），跑批量前建议先在小范围验证，并确认加上了
silent，避免弹出窗口打断流程。
结尾¶
这个 Skill 的价值不在发明新能力，而在把 Obsidian 官方 CLI 的参数约定和插件调试流程固化下来，让 Agent 不再靠猜。命令本身是稳定的，会变动的是命令全集，所以遇到没见过的子命令时回 obsidian help 查。
SkillHub 地址：https://www.skillhub.cn/skills/user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a （接口地址 https://api.skillhub.cn/user_2bd73b3a/obsidian-cli-kepano-user-2bd73b3a ）。上游仓库：https://github.com/kepano/obsidian-skills ，其中本 Skill 在 skills/obsidian-cli/SKILL.md。
截至抓取时，SkillHub 页面显示评分 100000，下载 1468，安装 0。评分和下载数会变动，以页面实时数据为准。
