Obsidian Skill for AI Coding Agents

An Agent Skill for reading, writing, searching, and mutating Obsidian vault files via the official CLI. Works with Claude Code, and any agent that supports the Agent Skills standard.

No direct file I/O — all operations go through Obsidian's CLI so the app stays in sync.

What's Included

File	Purpose
SKILL.md	Skill instructions — native CLI commands, Dataview queries, mutation patterns
scripts/obsidian_cli.py	Low-level Python wrapper around the CLI binary
scripts/obsidian_tasks.py	Task mutations: mark done, cancel, rewrite, set priority
scripts/obsidian_notes.py	Note mutations: insert before/after marker, frontmatter set/append, replace
config.example.yaml	Template config for your Obsidian binary path and vault name

Prerequisites

• Obsidian desktop app (includes the CLI)
• Obsidian must be running — the CLI connects to the app via IPC
• Python 3.10+
• pyyaml (pip install pyyaml)
• Optional: Dataview plugin for structured queries

Installation

Claude Code (project skill)

# Clone into your project's skills directory
git clone https://github.com/wernerbatt/obsidian-skill .claude/skills/obsidian

# Copy and edit the config
cp .claude/skills/obsidian/config.example.yaml config.yaml
# Edit config.yaml with your obsidian_bin path and vault_name

Claude Code (global skill)

# Clone into your global skills directory
git clone https://github.com/wernerbatt/obsidian-skill ~/.claude/skills/obsidian

# Put config.yaml in the project where you'll use it
cp ~/.claude/skills/obsidian/config.example.yaml config.yaml

Other agents

Copy the SKILL.md and scripts/ folder into wherever your agent discovers skills. The config search order is:

1. $OBSIDIAN_SKILL_CONFIG environment variable
2. config.yaml in the current working directory
3. config.yaml in the skill root directory
4. config.yaml in the nearest parent git root

Quick Start

Once installed and configured, just talk to your agent:

• "Read my daily note"
• "Search my vault for kitchen renovation"
• "Mark the groceries task done"
• "Add a task to today's daily note"
• "List all tasks tagged @quick"

The skill teaches the agent the CLI commands, script wrappers, and Dataview query patterns needed to operate on your vault.

Script Usage

Scripts can also be called directly from the command line:

# List incomplete tasks
python3 scripts/obsidian_tasks.py list --status todo --exclude-lowest

# Mark a task done
python3 scripts/obsidian_tasks.py done --path 'Daily/2026-04-04.md' --match 'Buy milk @quick'

# Cancel a task
python3 scripts/obsidian_tasks.py cancel --path 'Daily/2026-04-04.md' --match 'Old task'

# Insert text before a marker
python3 scripts/obsidian_notes.py insert-before --path 'Notes/My Note.md' --marker 'Section Two' --content '## New Section'

# Update frontmatter
python3 scripts/obsidian_notes.py fm-set --path 'Notes/My Note.md' --field last --value 2026-04-04

# Append to frontmatter list
python3 scripts/obsidian_notes.py fm-append --path 'Notes/My Note.md' --field related --value '"[[Other Note]]"'

All mutation commands support --dry-run to preview changes without writing.

How It Works

The Obsidian CLI binary ships with the desktop app and communicates with the running instance via IPC. This skill wraps it in three layers:

1. Native CLI — read, search, tasks, append, create, eval
2. Python wrappers — handle escaping, error handling, and common patterns
3. SKILL.md instructions — teach the agent when to use what, with examples

The eval command gives access to the full Obsidian API (including Dataview), enabling structured queries and atomic file mutations via app.vault.process().

Task Format

Uses the Obsidian Tasks emoji format:

- [ ] Task description @context ⏳ 2026-03-25 📅 2026-03-30 🔼
- [x] Completed task @context ✅ 2026-03-28
- [x] Cancelled task @context ❌ 2026-03-28

Priority: 🔺 highest · ⏫ high · 🔼 medium · (none) normal · 🔽 low · ⏬ lowest/someday

License

MIT