kao-obsidian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Vault — Editing, CLI & Organization Guide

Obsidian Vault — 编辑、CLI与组织指南

Overview

概述

This skill covers working with Obsidian vaults through two complementary approaches:

Direct file editing — Creating and modifying
```
.md
```
files that follow Obsidian Flavored Markdown conventions (wikilinks, callouts, properties, embeds, etc.)
Obsidian CLI (v1.12+) — Using the official command-line interface to interact with a running Obsidian instance for operations like search, file management, link analysis, tagging, and more.

For the full markdown syntax reference, read

references/markdown-syntax.md

. For the complete CLI command reference, read

references/cli-commands.md

. For Obsidian terminology, read

references/glossary.md

本技能涵盖两种互补的Obsidian vault操作方式：

直接文件编辑 — 创建并修改遵循Obsidian风味Markdown规范（wikilinks、提示框、属性、嵌入等）的
```
.md
```
文件
Obsidian CLI（v1.12+） — 使用官方命令行界面与运行中的Obsidian实例交互，执行搜索、文件管理、链接分析、标签设置等操作

完整的Markdown语法参考请阅读

references/markdown-syntax.md

。完整的CLI命令参考请阅读

references/cli-commands.md

。 Obsidian术语说明请阅读

references/glossary.md

。

Critical Rules

核心规则

Use wikilinks for internal links —
```
[[Note Name]]
```
, not
```
[Note Name](Note%20Name.md)
```
. Obsidian's link updater works with wikilinks. Use standard markdown links only for external URLs.
Properties go in YAML frontmatter — Fenced by
```
---
```
at the very top of the file. Use lowercase keys. Three special properties:
```
tags
```
,
```
aliases
```
,
```
cssclasses
```
.
File and folder names — Use lowercase-with-hyphens for folders (
```
daily-notes/
```
,
```
project-plans/
```
). Note titles can use natural casing (
```
Meeting Notes 2026-03-16.md
```
). Avoid special characters:
```
# ^ [] | \
```
.
Don't fabricate block IDs — Block IDs (
```
^my-block-id
```
) should only be added when the user specifically wants to reference a block. Don't scatter them preemptively.
Preserve existing content — When editing notes, preserve existing frontmatter fields, block IDs, and wikilinks you don't need to change. Obsidian users build interconnected graphs; breaking links breaks their knowledge base.
CLI requires a running Obsidian instance — The CLI is a remote control for the desktop app, not a standalone tool. If Obsidian isn't running, it will auto-launch. All CLI commands follow the pattern:
```
obsidian <command> [param=value] [flags]
```
.
Respect the vault's organization system — Before creating files, check the existing folder structure to understand the organizational philosophy in use. Don't impose a different structure on an existing vault.

内部链接使用wikilinks — 使用
```
[[笔记名称]]
```
，而非
```
[笔记名称](Note%20Name.md)
```
。Obsidian的链接更新工具仅支持wikilinks。仅在链接外部URL时使用标准Markdown链接。
属性置于YAML前置区域 — 在文件最顶部用
```
---
```
包裹。使用小写键名。三个特殊属性：
```
tags
```
、
```
aliases
```
、
```
cssclasses
```
。
文件与文件夹命名 — 文件夹使用小写连字符格式（
```
daily-notes/
```
、
```
project-plans/
```
）。笔记标题可使用自然大小写（
```
Meeting Notes 2026-03-16.md
```
）。避免使用特殊字符：
```
# ^ [] | \
```
。
不要随意添加块ID — 块ID（
```
^my-block-id
```
）仅在用户明确需要引用某块内容时添加，不要预先随意散布。
保留现有内容 — 编辑笔记时，保留无需修改的现有前置属性字段、块ID和wikilinks。Obsidian用户构建的是互联知识图谱，破坏链接会损坏他们的知识库。
CLI需要运行中的Obsidian实例 — CLI是桌面应用的远程控制工具，而非独立工具。如果Obsidian未运行，它会自动启动。所有CLI命令遵循以下格式：
```
obsidian <command> [param=value] [flags]
```
。
尊重vault的组织体系 — 创建文件前，检查现有文件夹结构以了解当前使用的组织理念。不要在已有vault中强加不同的结构。

Obsidian Flavored Markdown — Quick Reference

Obsidian风味Markdown — 速查参考

Obsidian Markdown is a superset of CommonMark + GFM with these extensions:

Feature	Syntax
Wikilink	`[[Note Name]]`
Wikilink with alias	`[[Note Name\|Display Text]]`
Link to heading	`[[Note#Heading]]`
Link to block	`[[Note#^block-id]]`
Embed note	`![[Note Name]]`
Embed image	`![[image.png]]` or `![[image.png\|300]]` for width
Embed PDF page	`![[doc.pdf#page=3]]`
Embed heading	`![[Note#Heading]]`
Highlight	`==highlighted text==`
Callout	`> [!note] Title` (see below)
Comment	`%%hidden text%%`
Block ID	`Paragraph text ^my-id`
Tag	`#tag` or `#nested/tag`
Inline math	$E = mc^2$
Block math	`$$\int_0^\infty$$`
Footnote	`Text[^1]` with `[^1]: Definition`
Task	`- [ ] unchecked` / `- [x] checked`

For the full syntax reference with examples, read

references/markdown-syntax.md

Obsidian Markdown是CommonMark + GFM的超集，包含以下扩展：

功能	语法
Wikilink	`[[笔记名称]]`
带别名的Wikilink	`[[笔记名称\|显示文本]]`
链接到标题	`[[笔记#标题]]`
链接到块	`[[笔记#^block-id]]`
嵌入笔记	`![[笔记名称]]`
嵌入图片	`![[image.png]]` 或指定宽度的 `![[image.png\|300]]`
嵌入PDF页面	`![[doc.pdf#page=3]]`
嵌入标题	`![[笔记#标题]]`
高亮文本	`==高亮文本==`
提示框	`> [!note] 标题` （见下文）
注释	`%%隐藏文本%%`
块ID	`段落文本 ^my-id`
标签	`#tag` 或 `#nested/tag`
行内公式	$E = mc^2$
块级公式	`$$\int_0^\infty$$`
脚注	`文本[^1]` 搭配 `[^1]: 定义`
任务	`- [ ] 未完成` / `- [x] 已完成`

带示例的完整语法参考请阅读

references/markdown-syntax.md

。

Callout Types

提示框类型

13 built-in types:

note

abstract

info

todo

tip

success

question

warning

failure

danger

bug

example

quote

markdown

> [!warning] Watch out
> This is a warning callout.

> [!tip]+ Expandable (open by default)
> Content here.

> [!faq]- Collapsed by default
> Content here.

13种内置类型：

note

、

abstract

、

info

、

todo

、

tip

、

success

、

question

、

warning

、

failure

、

danger

、

bug

、

example

、

quote

。

markdown

> [!warning] 注意
> 这是一个警告提示框。

> [!tip]+ 默认展开
> 内容区域。

> [!faq]- 默认折叠
> 内容区域。

Properties (YAML Frontmatter)

属性（YAML前置区域）

yaml

---
title: My Note Title
date: 2026-03-16
tags:
  - project
  - active
aliases:
  - My Note
  - MN
cssclasses:
  - wide-page
status: draft
priority: 1
reviewed: false
due: 2026-04-01T10:00:00
related:
  - "[[Other Note]]"
---

Supported property types: Text, Number, Checkbox (true/false), Date (YYYY-MM-DD), Date & Time (ISO 8601), List (YAML array), Links (wikilinks as quoted strings in YAML).

yaml

---
title: 我的笔记标题
date: 2026-03-16
tags:
  - project
  - active
aliases:
  - 我的笔记
  - MN
cssclasses:
  - wide-page
status: draft
priority: 1
reviewed: false
due: 2026-04-01T10:00:00
related:
  - "[[其他笔记]]"
---

支持的属性类型：文本、数字、复选框（true/false）、日期（YYYY-MM-DD）、日期时间（ISO 8601）、列表（YAML数组）、链接（YAML中作为字符串引用的wikilinks）。

Obsidian CLI — Essential Commands

Obsidian CLI — 核心命令

The CLI has 100+ commands. Here are the most commonly used ones for AI agent workflows. For the full reference, read

references/cli-commands.md

CLI包含100+命令。以下是AI Agent工作流中最常用的命令。完整参考请阅读

references/cli-commands.md

。

File Operations

文件操作

bash

undefined

bash

undefined

Read a note

读取笔记

obsidian read file="path/to/note.md"

Create a note with content

创建带内容的笔记

obsidian create name="Projects/new-project" content="# New Project\n\nDescription here."

obsidian create name="Projects/new-project" content="# 新项目\n\n项目描述。"

Create from template

从模板创建

obsidian create name="Meeting Notes" template="meeting-template"

Append content to end of file

向文件末尾追加内容

obsidian append file="path/to/note.md" content="- New bullet point"

obsidian append file="path/to/note.md" content="- 新列表项"

Prepend content after frontmatter

向前置区域后插入内容

obsidian prepend file="path/to/note.md" content="## Added Section"

obsidian prepend file="path/to/note.md" content="## 新增章节"

Move file (auto-updates wikilinks!)

移动文件（自动更新wikilinks！）

obsidian move file="old/path/note.md" to="new/path/"

Delete to trash

删除到回收站

obsidian delete file="path/to/note.md"

List files

列出文件

obsidian files sort=modified limit=10 obsidian files format=json

undefined

obsidian files sort=modified limit=10 obsidian files format=json

undefined

Search & Discovery

搜索与发现

bash

undefined

bash

undefined

Full-text search

全文搜索

obsidian search query="meeting notes"

Search with context (grep-style)

带上下文的搜索（类似grep）

obsidian search:context query="TODO" limit=10

Find unresolved (broken) links

查找未解析（失效）链接

obsidian unresolved

Find orphan notes (no incoming links)

查找孤立笔记（无入站链接）

obsidian orphans

Find dead-end notes (no outgoing links)

查找死胡同笔记（无出站链接）

obsidian deadends

Show backlinks to a note

显示某笔记的反向链接

obsidian backlinks file="Projects/alpha.md"

Show outgoing links

显示出站链接

obsidian links file="Projects/alpha.md"

undefined

obsidian links file="Projects/alpha.md"

undefined

Tags & Properties

标签与属性

bash

undefined

bash

undefined

List all tags with counts

列出所有标签及数量

obsidian tags counts

Find files with a specific tag

查找带指定标签的文件

obsidian tag tag="#project"

Read properties

读取属性

obsidian properties file="note.md" obsidian property:read file="note.md" name="status"

Set a property

设置属性

obsidian property:set file="note.md" name="status" value="complete"

Remove a property

删除属性

obsidian property:remove file="note.md" name="priority"

undefined

obsidian property:remove file="note.md" name="priority"

undefined

Daily Notes

每日笔记

bash

obsidian daily                                    # Open today's daily note
obsidian daily:read                               # Read today's content
obsidian daily:append content="- [ ] New task"    # Add to end
obsidian daily:prepend content="## Morning"       # Add after frontmatter
obsidian daily:path                               # Get file path

bash

obsidian daily                                    # 打开今日的每日笔记
obsidian daily:read                               # 读取今日笔记内容
obsidian daily:append content="- [ ] 新任务"    # 追加到末尾
obsidian daily:prepend content="## 晨间记录"       # 插入到前置区域后
obsidian daily:path                               # 获取文件路径

Tasks

任务

bash

obsidian tasks              # List all tasks
obsidian tasks daily        # Tasks from today's daily note

bash

obsidian tasks              # 列出所有任务
obsidian tasks daily        # 今日每日笔记中的任务

Vault Structure

Vault结构

bash

obsidian vault              # Vault info
obsidian folders            # Folder tree
obsidian files total        # File count
obsidian outline file="note.md"  # Show headings
obsidian wordcount file="note.md"

bash

obsidian vault              # Vault信息
obsidian folders            # 文件夹树
obsidian files total        # 文件数量
obsidian outline file="note.md"  # 显示标题结构
obsidian wordcount file="note.md"

Output Formats

输出格式

Most GET commands accept

format=

parameter:

json

csv

tsv

md

paths

text

tree

yaml

bash

obsidian files format=json | jq '.[].path'
obsidian tags format=yaml
obsidian search query="TODO" format=json

大多数GET命令支持

format=

参数：

json

、

csv

、

tsv

、

md

、

paths

、

text

、

tree

、

yaml

。

bash

obsidian files format=json | jq '.[].path'
obsidian tags format=yaml
obsidian search query="TODO" format=json

Clipboard

剪贴板

Add

--copy

to any command to copy output to clipboard:

bash

obsidian files sort=modified limit=5 --copy
obsidian read file="note.md" --copy

在任何命令后添加

--copy

可将输出复制到剪贴板：

bash

obsidian files sort=modified limit=5 --copy
obsidian read file="note.md" --copy

Multi-Vault

多Vault

Specify vault as the first parameter when working with multiple vaults:

bash

obsidian vault="Work" daily
obsidian vault="Personal" search query="recipe"

处理多个Vault时，将Vault名称作为第一个参数：

bash

obsidian vault="Work" daily
obsidian vault="Personal" search query="recipe"

Vault Organization

Vault组织

When working with an Obsidian vault, first assess which organizational philosophy is in use by examining the folder structure, existing MOCs/index notes, and tag patterns. If the vault is clearly using a system, follow it consistently.

处理Obsidian vault时，首先通过检查文件夹结构、现有MOC/索引笔记和标签模式，评估当前使用的组织理念。如果vault明确使用某一体系，请始终遵循该体系。

Detecting the Organization System

识别组织体系

Check these signals:

PARA: Folders named
```
Projects/
```
,
```
Areas/
```
,
```
Resources/
```
,
```
Archive/
```
(or close variations)
MOC: Index/hub notes with titles like "MOC - Topic" or "Index - Topic", heavy use of wikilinks as navigation
Flat + Tags: Few or no folders, heavy tag usage in frontmatter and inline, tag hierarchies like
```
#project/active
```
Johnny Decimal: Numbered folders like
```
10-19 Finance/
```
,
```
11 Budgets/
```
,
```
12 Invoices/
```

检查以下特征：

PARA：文件夹命名为
```
Projects/
```
、
```
Areas/
```
、
```
Resources/
```
、
```
Archive/
```
（或类似变体）
MOC：标题为“MOC - 主题”或“Index - 主题”的索引/枢纽笔记，大量使用wikilinks作为导航
扁平化+标签：很少或没有文件夹，前置区域和行内大量使用标签，标签层级如
```
#project/active
```
Johnny Decimal：编号文件夹如
```
10-19 Finance/
```
、
```
11 Budgets/
```
、
```
12 Invoices/
```

If the vault is empty or the user asks for a structure

如果vault为空或用户询问结构

Ask the user which organization system they prefer. Present these options:

1. PARA (default recommendation for new vaults)

vault/
├── 1-Projects/        # Active projects with deadlines
├── 2-Areas/           # Ongoing responsibilities (health, finance, career)
├── 3-Resources/       # Reference material by topic
├── 4-Archive/         # Completed/inactive items
├── templates/         # Note templates
├── daily-notes/       # Daily journal entries
└── attachments/       # Images, PDFs, files

2. Maps of Content (MOC)

vault/
├── +Index.md          # Master index linking to all MOCs
├── MOCs/              # Hub notes that link to topic clusters
├── notes/             # All atomic notes (flat or lightly categorized)
├── templates/
├── daily-notes/
└── attachments/

3. Flat + Tags

vault/
├── notes/             # All notes in one folder
├── templates/
├── daily-notes/
└── attachments/

Organization is entirely through

tags

in frontmatter and inline

#tags

. Use tag hierarchies:

#project/active

#area/health

#type/meeting

4. Johnny Decimal

vault/
├── 00-09 System/
│   ├── 00 Index/
│   └── 01 Templates/
├── 10-19 Work/
│   ├── 10 Projects/
│   ├── 11 Meetings/
│   └── 12 Reports/
├── 20-29 Personal/
│   ├── 20 Health/
│   └── 21 Finance/
├── daily-notes/
└── attachments/

询问用户偏好的组织体系，提供以下选项：

1. PARA（新vault默认推荐）

vault/
├── 1-Projects/        # 带截止日期的活跃项目
├── 2-Areas/           # 持续负责事项（健康、财务、职业）
├── 3-Resources/       # 按主题分类的参考资料
├── 4-Archive/         # 已完成/停用项目
├── templates/         # 笔记模板
├── daily-notes/       # 每日日志
└── attachments/       # 图片、PDF等附件

2. 内容地图（MOC）

vault/
├── +Index.md          # 链接所有MOC的主索引
├── MOCs/              # 链接主题集群的枢纽笔记
├── notes/             # 所有原子笔记（扁平化或轻度分类）
├── templates/
├── daily-notes/
└── attachments/

3. 扁平化+标签

vault/
├── notes/             # 所有笔记存于一个文件夹
├── templates/
├── daily-notes/
└── attachments/

完全通过前置区域的

tags

和行内

#tags

进行组织。使用标签层级：

#project/active

、

#area/health

、

#type/meeting

。

4. Johnny Decimal

vault/
├── 00-09 System/
│   ├── 00 Index/
│   └── 01 Templates/
├── 10-19 Work/
│   ├── 10 Projects/
│   ├── 11 Meetings/
│   └── 12 Reports/
├── 20-29 Personal/
│   ├── 20 Health/
│   └── 21 Finance/
├── daily-notes/
└── attachments/

Organization Best Practices (Apply Regardless of System)

组织最佳实践（适用于所有体系）

One note, one idea — Atomic notes are easier to link and reuse than monolithic pages.
Link generously — Use
```
[[wikilinks]]
```
whenever you mention a concept that has (or could have) its own note. This builds the knowledge graph.
Use templates for recurring notes — Daily notes, meeting notes, project briefs should have templates for consistency.
Keep attachments in one place — Configure Obsidian to save attachments to an
```
attachments/
```
folder (Settings > Files & links > Default location for new attachments).
Frontmatter on every note — At minimum include
```
tags
```
and
```
date
```
. For project notes, add
```
status
```
,
```
priority
```
,
```
due
```
.
Regular maintenance — Periodically check
```
obsidian orphans
```
and
```
obsidian unresolved
```
to find disconnected notes and broken links.
Archive, don't delete — Move completed projects/outdated notes to archive rather than deleting them.

一笔记一主题 — 原子笔记比冗长笔记更易于链接和复用。
大量使用链接 — 每当提及已有（或可能有）独立笔记的概念时，使用
```
[[wikilinks]]
```
。这有助于构建知识图谱。
为重复笔记使用模板 — 每日笔记、会议笔记、项目简报应使用模板以保持一致性。
附件集中存放 — 配置Obsidian将附件保存到
```
attachments/
```
文件夹（设置 > 文件与链接 > 新附件的默认位置）。
所有笔记添加前置区域 — 至少包含
```
tags
```
和
```
date
```
。项目笔记需添加
```
status
```
、
```
priority
```
、
```
due
```
。
定期维护 — 定期运行
```
obsidian orphans
```
和
```
obsidian unresolved
```
查找孤立笔记和失效链接。
归档而非删除 — 将已完成项目/过时笔记移至归档文件夹，而非删除。

Implementing Organization with CLI

使用CLI实现组织

When reorganizing a vault, use the CLI's

move

command because it automatically updates all wikilinks:

bash

undefined

重组vault时，使用CLI的

move

命令，因为它会自动更新所有wikilinks：

bash

undefined

Move completed project to archive

将已完成项目移至归档

obsidian move file="1-Projects/website-redesign.md" to="4-Archive/"

Bulk move with tag filtering

按标签筛选批量移动

obsidian tag tag="#archived" format=paths | while read note; do obsidian move file="$note" to="4-Archive/" done

Find orphans and review them

查找孤立笔记并检查

obsidian orphans format=paths

undefined

obsidian orphans format=paths

undefined

Common Agent Workflows

常见Agent工作流

Creating a New Note

创建新笔记

Check existing vault structure to determine where the note belongs
Use appropriate template if one exists (
```
obsidian templates
```
to list them)
Add proper frontmatter with at minimum
```
tags
```
and
```
date
```
Use wikilinks to connect to related notes

Create the note:

obsidian create name="path/note-title" content="..."

检查现有vault结构以确定笔记存放位置
如果存在合适模板则使用（
```
obsidian templates
```
列出所有模板）
添加至少包含
```
tags
```
和
```
date
```
的前置属性
使用wikilinks链接到相关笔记

创建笔记：

obsidian create name="path/note-title" content="..."

Reorganizing Notes

重组笔记

Assess current structure:
```
obsidian folders
```
and
```
obsidian files
```

Identify problems:

obsidian orphans

obsidian unresolved

obsidian deadends

Use
```
obsidian move
```
for relocating files (preserves links)
Update index/MOC notes if the vault uses them
Verify links:
```
obsidian unresolved
```

评估当前结构：
```
obsidian folders
```
和
```
obsidian files
```

识别问题：

obsidian orphans

、

obsidian unresolved

、

obsidian deadends

使用
```
obsidian move
```
移动文件（保留链接）
如果vault使用索引/MOC笔记，更新相关内容
验证链接：
```
obsidian unresolved
```

Daily Note Workflow

每日笔记工作流

bash

undefined

bash

undefined

Start the day

开启新的一天

obsidian daily obsidian daily:read

Add tasks throughout the day

全天添加任务

obsidian daily:append content="- [ ] Review PR #42" obsidian daily:append content="- [ ] Update project status"

obsidian daily:append content="- [ ] 审核PR #42" obsidian daily:append content="- [ ] 更新项目状态"

Review tasks

查看任务

obsidian tasks daily

undefined

obsidian tasks daily

undefined

Knowledge Capture

知识捕获

Create atomic notes for individual concepts
Add proper frontmatter and tags
Link to related notes with wikilinks
If using MOC system, update the relevant MOC note
If using PARA, place in the correct area/project folder

为单个概念创建原子笔记
添加合适的前置属性和标签
使用wikilinks链接到相关笔记
如果使用MOC体系，更新相关MOC笔记
如果使用PARA体系，放入对应的领域/项目文件夹