name: obsidian license: MIT description: Use when working with Obsidian vaults, notes, tasks, properties, bases, plugins, or themes. metadata: version: 1.0.1 visibility: public author: afonsoft url: https://github.com/afonsoft/skills openclaw: '{"requires":{"bins":["obsidian"]}}'

Obsidian

A single skill for everything Obsidian: the CLI, Bases (.base files), and Obsidian Flavored Markdown. Consolidates the former obsidian-cli, obsidian-bases, and obsidian-markdown skills.

Origin: derived from kepano/obsidian-skills (MIT). Obsidian must be running for any CLI or MCP command to work.

When to Use

Interact with a vault from the command line (create/read/search/manage notes, tasks, properties).
Build or edit a Base (database-like view over notes) with filters and formulas.
Author Obsidian Flavored Markdown (wikilinks, embeds, callouts, properties).
Develop or debug an Obsidian plugin or theme.
User asks or mentions this skill in English (e.g., "use /obsidian", "run obsidian").
O usuário pede ou menciona esta skill em português (ex.: "use /obsidian", "execute obsidian").

When NOT to Use

Do not use for generic Markdown files or note-taking tools that are not Obsidian.
Do not target a vault the user has not explicitly named.
Do not auto-install the mcp-obsidian-cli package or run the obsidian binary without user confirmation.

Security & Guardrails

Human confirmation first: confirm the target vault and any obsidian command with the user before execution.
No auto-execution: only run commands that read or modify the named vault; do not run system-wide commands or execute arbitrary plugins/themes without explicit consent.
MCP fallback is opt-in: if the obsidian CLI is missing, present mcp-obsidian-cli as an optional fallback and wait for the user to approve its installation.
Stay inside the vault: do not use Obsidian CLI to access files outside the vault root.

Three areas

1. CLI

Run obsidian against a running Obsidian instance — vault operations, plugin/theme dev, DOM/screenshot inspection. See the full command reference and quick-start examples in references/obsidian-cli.md.

Before running any obsidian command, verify which vault the user wants to target and confirm the command. Do not auto-install mcp-obsidian-cli or any Obsidian plugin without explicit user consent.

2. Bases

.base files are valid YAML defining filters, formulas, and views (table/cards/list/map) over notes. See references/obsidian-bases.md and the full function list in references/FUNCTIONS_REFERENCE.md.

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'
formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
views:
  - type: table
    name: "Active Tasks"
    order: [file.name, status, formula.days_until_due]

3. Markdown (Obsidian Flavored)

Wikilinks [[Note]], embeds ![[note.png|300]], callouts > [!warning], properties/frontmatter, highlights ==text==, Mermaid, math. See references/obsidian-markdown.md, plus references/CALLOUTS.md, references/EMBEDS.md, references/PROPERTIES.md.

Workflows

Create an Obsidian note

Add frontmatter/properties at the top (see references/PROPERTIES.md).
Write content with standard Markdown + Obsidian syntax (wikilinks, embeds, callouts).
Verify it renders in reading view.

Build a Base

Create a .base file with valid YAML.
Define filters (global/view) and optional formulas.
Add one or more views (table/cards/list/map).
Validate YAML (watch quoting rules); open in Obsidian to confirm rendering.

Register CLI / develop a plugin

Guide the user to Settings → General → Command line interface → Register CLI; restart the terminal.
After the user confirms code changes, run obsidian plugin:reload and obsidian dev:screenshot only for the explicitly named plugin.

Common Mistakes

Mistake	Symptom	Fix
Obsidian not running	CLI/MCP commands fail	Open the Obsidian app first
Unquoted special chars in `.base`	YAML error	Quote strings with `:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `\|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`
Double quotes inside double quotes (formula)	Parse error	Wrap formula in single quotes: `'if(done, "Yes", "No")'`
Duration without field access	`(now()-file.ctime).round(0)` errors	Access `.days` first: `(now()-file.ctime).days.round(0)`
Missing null checks in formulas	Crash on empty property	Guard with `if()`: `if(due, (date(due)-today()).days, "")`
Wikilink vs Markdown link	Broken external links	`[[Note]]` for vault notes; `[text](url)` for external only

References

references/obsidian-cli.md — CLI install, syntax, commands, plugin dev.
references/obsidian-bases.md — Bases schema, filters, formulas, views, examples.
references/obsidian-markdown.md — Obsidian Flavored Markdown syntax.
references/FUNCTIONS_REFERENCE.md — Complete Bases function reference.
references/CALLOUTS.md — All callout types.
references/EMBEDS.md — All embed types.
references/PROPERTIES.md — All property types and tag rules.

obsidian