home / skills / kriscard / kriscard-claude-plugins / obsidian

obsidian skill

safe

/plugins/obsidian-second-brain/skills/obsidian

This skill enables efficient Obsidian vault management by executing CLI operations for reading, creating, appending, searching, and listing notes.

npx playbooks add skill kriscard/kriscard-claude-plugins --skill obsidian

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

10.0 KB

---
name: obsidian
description: >-
  Performs all Obsidian vault operations — reading notes, creating files, appending
  content, searching, and listing files — using CLI-first approach with MCP
  fallback. Make sure to use this skill whenever the user mentions obsidian, vault,
  notes, daily note, or any vault file operation. If the user mentions Obsidian in
  any context, use this skill.
---

# Obsidian Operations Skill

This skill defines how to interact with Obsidian vaults. **Always prefer CLI when available, fall back to MCP with user confirmation.**

## Quick Reference

| Operation | CLI Command | MCP Fallback |
|-----------|------------|--------------|
| Read file | `obsidian read path="..."` | `mcp__mcp-obsidian__obsidian_get_file_contents` |
| Create file | `obsidian create path="..." content="..." silent` | `mcp__mcp-obsidian__obsidian_append_content` |
| Append | `obsidian append path="..." content="..." silent` | `mcp__mcp-obsidian__obsidian_append_content` |
| Search | `obsidian search query="..." format=json` | `mcp__mcp-obsidian__obsidian_simple_search` |
| List files | `obsidian files folder="..." format=json` | `mcp__mcp-obsidian__obsidian_list_files_in_dir` |
| Daily note | `obsidian daily:read` | `mcp__mcp-obsidian__obsidian_get_periodic_note` |

## Detection Flow

```
1. Check CLI: Run detection command (see below)
2. If CLI_AVAILABLE: Use CLI commands via Bash
3. If CLI_UNAVAILABLE: Ask user to confirm MCP usage, then use MCP tools
```

### CLI Detection Pattern

```bash
obsidian vault &>/dev/null && echo "CLI_AVAILABLE" || echo "CLI_UNAVAILABLE"
```

## Using obsidian-utils.sh

The shared utility script handles detection and all operations. Located at:
```
${CLAUDE_PLUGIN_ROOT}/scripts/obsidian-utils.sh
```

### Script Commands

| Operation | Command | Example |
|-----------|---------|---------|
| Check status | `./obsidian-utils.sh status` | Shows CLI availability |
| Read file | `./obsidian-utils.sh read "path.md"` | Read by exact path |
| Read by name | `./obsidian-utils.sh read-file "Recipe"` | Wikilink-style resolution |
| List files | `./obsidian-utils.sh list "folder/" json` | List with format |
| Create file | `./obsidian-utils.sh create "path.md" "content"` | Create note |
| Create from template | `./obsidian-utils.sh create-template "path.md" "Template"` | Use template |
| Append | `./obsidian-utils.sh append "path.md" "content"` | Append to note |
| Prepend | `./obsidian-utils.sh prepend "path.md" "content"` | Prepend after frontmatter |
| Search | `./obsidian-utils.sh search "query" json` | Search vault |
| Delete | `./obsidian-utils.sh delete "path.md"` | Delete note (trash) |
| Move | `./obsidian-utils.sh move "old.md" "new.md"` | Move/rename |
| Daily note | `./obsidian-utils.sh daily read` | Read today's daily |
| Daily append | `./obsidian-utils.sh daily append "content"` | Append to daily |
| Tasks | `./obsidian-utils.sh tasks all` | List all tasks |
| Tags | `./obsidian-utils.sh tags` | List tags with counts |
| Backlinks | `./obsidian-utils.sh backlinks "path.md"` | List backlinks |
| Unresolved | `./obsidian-utils.sh unresolved` | Find broken links |
| Orphans | `./obsidian-utils.sh orphans` | Find orphan files |
| Outline | `./obsidian-utils.sh outline "path.md"` | Show headings |
| Properties | `./obsidian-utils.sh properties "path.md"` | List frontmatter |
| Set property | `./obsidian-utils.sh property-set "path.md" "key" "value"` | Set frontmatter |
| Templates | `./obsidian-utils.sh templates` | List templates |
| Template read | `./obsidian-utils.sh template-read "Name"` | Get resolved template |

## CLI Commands Reference

### File Targeting

Two ways to target files:

| Parameter | Behavior | Example |
|-----------|----------|---------|
| `file=<name>` | Wikilink-style resolution (no path/ext needed) | `file=Recipe` finds `Recipes/Recipe.md` |
| `path=<path>` | Exact path from vault root | `path="3 - Resources/TIL/til-2026-02-16.md"` |

### File Operations

```bash
# Read file content
"obsidian" read path="2 - Areas/Daily Ops/2026-02-14.md"
"obsidian" read file="Recipe"  # wikilink resolution

# List files in folder (json for parsing)
"obsidian" files folder="0 - Inbox/" format=json

# Create new file
"obsidian" create path="3 - Resources/TIL/til-2026-02-14.md" content="# TIL..." silent

# Create from template
"obsidian" create path="note.md" template="Daily Notes" silent

# Append to file (silent = don't open)
"obsidian" append path="note.md" content="\n## New Section" silent

# Append inline (no newline added)
"obsidian" append path="note.md" content=" - item" silent inline

# Prepend after frontmatter
"obsidian" prepend path="note.md" content="# Header" silent

# Move/rename file
"obsidian" move path="old.md" to="folder/new.md"

# Delete file (to trash)
"obsidian" delete path="note.md"

# Delete permanently
"obsidian" delete path="note.md" permanent

# Search vault
"obsidian" search query="meeting notes" format=json limit=20
```

### Daily Notes

```bash
# Read today's daily note
"obsidian" daily:read

# Append to daily note
"obsidian" daily:append content="- [ ] Buy groceries" silent

# Prepend to daily note
"obsidian" daily:prepend content="# Morning Notes" silent

# Open daily note (just get path)
"obsidian" daily silent
```

### Tasks

```bash
# List all tasks
"obsidian" tasks all

# List tasks from daily note
"obsidian" tasks daily

# List incomplete tasks
"obsidian" tasks todo

# List completed tasks
"obsidian" tasks done

# Toggle a task
"obsidian" task path="note.md" line=8 toggle

# Mark task done
"obsidian" task path="note.md" line=8 done
```

### Tags

```bash
# List all tags with counts
"obsidian" tags all counts

# Get info about specific tag
"obsidian" tag name="project" verbose
```

### Links & Graph

```bash
# List backlinks to a file
"obsidian" backlinks path="note.md" counts

# List outgoing links
"obsidian" links path="note.md"

# Find broken (unresolved) links
"obsidian" unresolved verbose counts

# Find orphan files (no incoming links)
"obsidian" orphans

# Find dead-end files (no outgoing links)
"obsidian" deadends
```

### Properties (Frontmatter)

```bash
# List properties of a file
"obsidian" properties path="note.md" format=yaml

# Set a property
"obsidian" property:set path="note.md" name="status" value="complete"

# Set property with type
"obsidian" property:set path="note.md" name="priority" value="5" type=number

# Read a property value
"obsidian" property:read path="note.md" name="status"

# Remove a property
"obsidian" property:remove path="note.md" name="draft"
```

### Templates

```bash
# List available templates
"obsidian" templates

# Read template (with variables resolved)
"obsidian" template:read name="Daily Notes" resolve

# Read template raw
"obsidian" template:read name="Daily Notes"
```

### Outline & Structure

```bash
# Show headings tree
"obsidian" outline path="note.md" format=tree

# Show headings as markdown
"obsidian" outline path="note.md" format=md
```

### Vault Info

```bash
# Full vault info
"obsidian" vault

# Specific info
"obsidian" vault info=files    # file count
"obsidian" vault info=size     # vault size
```

### CLI Flags

| Flag | Effect |
|------|--------|
| `silent` | Don't open file after operation |
| `overwrite` | Replace existing file |
| `inline` | Append/prepend without adding newline |
| `permanent` | Delete permanently (skip trash) |
| `resolve` | Resolve template variables |
| `verbose` | Include extra details |
| `counts` | Include occurrence counts |
| `total` | Return count only |

### Output Formats

| Format | Use for |
|--------|---------|
| `format=json` | Parsing in code |
| `format=text` | Human readable |
| `format=yaml` | Properties/frontmatter |
| `format=tree` | Outline hierarchy |
| `format=md` | Markdown output |

### Multiline Content

Use `\n` for newlines and `\t` for tabs:

```bash
"obsidian" create path="note.md" content="# Title\n\nBody text\n\n- Item 1\n- Item 2" silent
```

## MCP Tools Reference

When CLI unavailable, use these MCP tools (with user confirmation):

| Operation | MCP Tool |
|-----------|----------|
| Read file | `mcp__mcp-obsidian__obsidian_get_file_contents` |
| Read multiple | `mcp__mcp-obsidian__obsidian_batch_get_file_contents` |
| List files | `mcp__mcp-obsidian__obsidian_list_files_in_dir` |
| Create/Append | `mcp__mcp-obsidian__obsidian_append_content` |
| Patch content | `mcp__mcp-obsidian__obsidian_patch_content` |
| Search | `mcp__mcp-obsidian__obsidian_simple_search` |
| Complex search | `mcp__mcp-obsidian__obsidian_complex_search` |
| Delete | `mcp__mcp-obsidian__obsidian_delete_file` |
| Daily note | `mcp__mcp-obsidian__obsidian_get_periodic_note` |
| Recent changes | `mcp__mcp-obsidian__obsidian_get_recent_changes` |

## MCP Fallback Confirmation

**Always confirm before using MCP.** Example interaction:

```
You: Obsidian CLI isn't available (Obsidian may not be running or CLI not enabled).
     May I use Obsidian MCP to read your vault instead?

User: Yes, go ahead

You: [Uses MCP tools]
```

## Vault Structure

Default vault: `/Users/kriscard/obsidian-vault-kriscard`

Key paths:
- `0 - Inbox/` - Incoming notes
- `1 - Projects/` - Active projects
- `2 - Areas/` - Ongoing responsibilities
- `3 - Resources/` - Reference material
- `4 - Archives/` - Completed/inactive
- `Templates/` - Note templates

## Best Practices

1. **Use `silent` flag** - Always add `silent` for non-interactive operations
2. **Use `format=json`** - For parsing output programmatically
3. **Prefer `file=`** - When you know the name but not the path
4. **Use `path=`** - When you know the exact path
5. **Batch operations** - Use parallel calls when checking multiple files
6. **Error handling** - If CLI fails mid-operation, fall back to MCP
7. **Templates** - Use `template=` parameter when creating from templates
8. **Confirmation** - Never delete without explicit user confirmation

## CLI Requirements

Obsidian CLI requires:
- Obsidian v1.12+ (early access)
- Catalyst license
- CLI enabled: Settings → General → Command line interface
- Obsidian must be running

If any requirement isn't met, CLI commands will fail and MCP fallback is needed.

Overview

This skill handles Obsidian vault operations with a CLI-first approach and an explicit MCP fallback. It covers reading, creating, appending, searching, listing files, daily notes, tasks, tags, links, templates, and vault metadata. Use it whenever you need reliable, scriptable access to an Obsidian vault.

How this skill works

The skill first detects if the Obsidian CLI is available and running; if so, it runs obsidian commands or the shared obsidian-utils.sh script for precise operations. If the CLI is unavailable, it asks the user for permission and then uses MCP tools to perform the same actions. All operations support flags like silent, format=json, inline, overwrite, and permanent to control behavior and output.

When to use it

Reading note contents or resolving wikilink-style names
Creating notes, templates, or appending/prepending content
Searching the vault or listing files/folders programmatically
Working with daily/periodic notes and automated task handling
Inspecting tags, backlinks, unresolved links, or vault metadata

Best practices

Prefer CLI commands when available; they are faster and preserve local context
Always add silent for non-interactive operations to avoid opening the app
Use format=json for machine parsing and file= for wikilink-style resolution when path is unknown
Confirm with the user before using MCP fallback and before destructive actions (delete/permanent)
Batch operations where possible for efficiency and use template= to create consistent notes

Example use cases

Read a note by name, falling back to MCP only after confirmation
Create a TIL note from a template and append a short note to today's daily note silently
Search the vault for meeting notes and return results as JSON for further processing
List files in a project folder, then update frontmatter properties across multiple files
Find unresolved links and generate a report of orphan files for cleanup

FAQ

What happens if the CLI check fails?

The skill notifies you CLI is unavailable and asks for permission to use MCP tools before proceeding.

When should I use file= vs path=?

Use file= for wikilink-style resolution when you know the note name but not the exact path; use path= when you know the exact vault-relative path.