Obsidian Vault

Obsidian Vault Skill

You are working inside an Obsidian vault. Your job is to create and edit notes that render correctly, stay plugin-compatible, and follow the vault's established conventions consistently across sessions.

How This Skill Works

This skill contains the core conventions and safe editing rules needed for every note interaction. For detailed syntax and plugin-specific rules, it points to reference files in references/ that you load when needed — not upfront.

Reference files (read on demand — always read BEFORE acting, not after):

Obsidian core syntax

• references/syntax.md — Full Obsidian Flavored Markdown syntax: block

references, embeds, Mermaid diagrams, inline comments, footnotes, LaTeX math, advanced link patterns. Read before working with any of these constructs.

• references/properties.md — Full YAML property type reference: reserved

keys, type rules, edge cases, common schemas. Read before creating or repairing frontmatter, or when designing a property schema.

Core plugins

• references/core-plugins.md — Core Obsidian plugin conventions: Properties

(type inference), Daily Notes, Templates, Graph, Backlinks, Slides, Sync. Read before working with any core plugin feature — especially property type consistency or Daily Notes templates.

• references/bases.md — Bases database views: .base file YAML format,

filter functions (and their gotchas), formulas, property type requirements, Bases vs Dataview comparison. Read before creating or editing .base files or writing notes that feed into a Bases view.

• references/canvas.md — Canvas JSON format: node types, sizing/spacing

rules, edge labels, group containment, Enhanced Canvas plugin. Read before creating or editing .canvas files.

Community plugins

• references/dataview.md — Dataview queries, inline fields, DataviewJS,

implicit fields, cross-plugin interactions. Read before writing any Dataview query or inline field.

• references/tasks.md — Tasks plugin emoji format, custom statuses, dates,

priority, recurrence, dependencies, query blocks. Read before writing or editing tasks with emoji metadata.

• references/kanban.md — Kanban board markdown structure, card syntax, lane

management, settings block, safe editing rules. Read before editing any Kanban board file.

• references/meta-bind.md — Meta Bind INPUT/VIEW/BUTTON syntax, property

binding, action types, JavaScript support. Read before writing Meta Bind interactive elements.

• references/templater.md — Templater syntax, common functions, folder

templates, JavaScript in templates, core Templates vs Templater. Read before creating or editing template files.

Vault access tools

• references/vault-tools.md — Tool tiers for interacting with vaults

(direct file ops, Obsidian CLI, MCP servers), environment detection, and a decision matrix for which tool to use when. Read when choosing between tools for vault operations, or when working in a new environment.

These files contain the detailed rules that prevent silent rendering errors and plugin-incompatible output. Reading them after you've already written something means you'll need to redo it.

---

Guiding Principles

1. Render safety first. Never write Markdown that Obsidian core or

installed plugins will misparse or silently corrupt.

1. Minimum viable change. When editing an existing note, change only what

was asked. Do not reorder sections, alter heading hierarchy, or modify frontmatter keys unless explicitly requested.

1. Match the vault's link convention. Do not assume wikilinks or markdown

links. Detect the convention from existing notes and .obsidian/app.json (useMarkdownLinks setting). If the convention is unclear, ask the user. Once established, be consistent — never mix conventions within a vault. See "Convention Detection" below for the full process.

1. Keep metadata stable. Preserve existing frontmatter keys and their

types. Add new keys only at the end of the frontmatter block. Check for vault-wide type consistency before adding a property name that might already exist elsewhere.

1. Ask before restructuring. If a request implies renaming notes,

splitting files, or changing folder structure, confirm before acting — these operations can break links vault-wide.

1. One convention per vault. If the vault uses Tasks plugin emoji syntax,

don't introduce plain checkboxes. If it uses Dataview inline fields, don't add YAML-only properties. Read existing notes before writing new ones.

1. Detect, confirm, and persist conventions. When you notice a convention

in the vault — link style, frontmatter schema, task format, tag placement, date format — check whether it's intentional and persist the finding. See "Convention Detection" below.

1. Look things up — don't guess and iterate. When you encounter

unfamiliar Obsidian syntax, a plugin feature you're unsure about, or a convention that could go multiple ways, use WebSearch to check official docs and community forums before writing anything. Each reference file links to its plugin's official documentation — start there.

Trigger: If you've tried something and it didn't work, or you're about to write syntax you haven't seen confirmed in the vault or in these reference files, that's the signal to search — not to try another guess. Two failed attempts without searching is too many.

What to search: The Obsidian docs site (help.obsidian.md), the plugin's own docs (linked at the top of each reference file), the Obsidian forum (forum.obsidian.md), Reddit (r/ObsidianMD), and GitHub issues for the relevant plugin. Community plugins especially have undocumented behaviors and version-specific quirks that only surface in forum threads, Reddit posts, and GitHub issues.

Why this matters: Plugin settings change default behavior, and vaults diverge from defaults frequently. Guessing leads to circular trial-and-error that wastes time and produces incorrect output. A single WebSearch call is faster than three wrong attempts.

---

Convention Detection and Persistence

Obsidian vaults are highly customizable. Two power users' vaults can look completely different — different link styles, frontmatter schemas, task formats, plugin configurations, and organizational patterns. An agent that assumes defaults will break things.

On First Use in a New Vault

When this skill activates in a vault for the first time (no prior convention record exists), detect and confirm these conventions before writing anything:

1. Link convention — understand the approach, not just the syntax:

• Check .obsidian/app.json for two settings:
• useMarkdownLinks (true = markdown links, false/absent = wikilinks)
• newLinkFormat ("shortest" = bare name, "relative" = relative path,

"absolute" = full path from vault root). Default is "shortest".

• Read 3-5 existing notes to confirm actual usage matches the settings. Look

for patterns beyond syntax: Do links use aliases consistently? Are paths included even when shortest is the setting? Is there a display-name convention (e.g., [[folder/Note|Note]] for cleaner reading view)?

• Check frontmatter for link properties (related:, parent:, etc.) — are

wikilinks quoted? Are they using aliases?

• Look for bidirectional related: linking — when note A lists note B in

related:, does note B reciprocate? If this is a convention, persist it and follow it on all new links.

• If mixed styles exist, ask the user which convention to follow going

forward and whether to migrate existing links

• Persist the full picture: link type, path format, alias convention,

bidirectional linking expectation

2. Frontmatter schema:

• Read 3-5 representative notes to identify common property names and types
• Note which properties are used vault-wide vs folder-specific
• Identify any property schemas tied to Dataview queries, Bases views, or

Meta Bind inputs

• Persist the schema pattern

3. Task format:

• Check .obsidian/plugins/obsidian-tasks-plugin/data.json for taskFormat

(e.g., tasksPluginEmoji)

• Check for custom statuses in the same config
• Check if auto-set dates are enabled (setCreatedDate, setDoneDate,

setCancelledDate)

• Look at existing tasks in the vault to confirm format in use
• Persist relevant settings

4. Tag convention — understand the user's taxonomy priorities:

• Are tags primarily in frontmatter, inline (#tag), or both?
• Nested tags (#project/active) or flat (#project, #active)? Is there

a hierarchy that reflects the user's mental model (e.g., #project/active vs #status/active suggest different organizational philosophies)?

• Casing: lowercase-hyphenated, camelCase, or mixed?
• How heavily does the user rely on tags vs folders for organization? Some

vaults use folders as the primary axis and tags sparingly for cross-cutting concerns; others use tags as the primary taxonomy with a flat folder structure. Understanding this shapes how you tag new notes.

• Numeric-only tags are invalid — Obsidian rejects purely numeric tags

(e.g., 2025) even when YAML-quoted. If you find numeric-ish conventions, check how the vault handles them (likely a separate property like year:).

• Persist the pattern and the rationale behind it

5. Date format:

• What date format appears in frontmatter? (Usually ISO 8601, but check)
• Daily note filename format (from .obsidian/daily-notes.json)
• Persist if non-standard

6. Template usage:

• Is Templater installed? What's the templates folder?
• Are folder templates configured?
• Is trigger_on_file_creation enabled?
• Persist if relevant to file creation

7. Kanban usage:

• Are there Kanban board files? What lanes/structure do they use?
• Are board cards using Tasks plugin emoji syntax?
• Is the board used for workflow state (lane position = status) instead of

custom task statuses?

• Persist the pattern

8. Daily notes — detect the interaction model:

• Is the Daily Notes core plugin enabled? Check .obsidian/core-plugins.json.
• Where do daily notes live? Check the Daily Notes settings for folder and

date format.

• Sample 2-3 existing daily notes to understand the structure: Is there a

template? What sections exist? Are sections auto-managed by a plugin?

• Check for plugin-managed sections. Community plugins like

obsidian-list-modified automatically maintain sections in daily notes (e.g., "Files Created", "Files Modified"). If such a plugin is active, agents must not write to those sections — or to the daily note at all, depending on the plugin's scope.

• If daily notes are NOT plugin-managed, ask the user how they'd like agents

to interact with them: append to a specific section? Leave them alone? Update a specific template section?

• If daily notes ARE plugin-managed but the user wants template improvements,

discuss what sections or content they'd like added or refined in the template.

• Persist the interaction model: which sections are off-limits, what agents

can add, and the template path if relevant.

9. Hub and index notes — detect navigational patterns:

• Some vaults use hub notes, Maps of Content (MOCs), or index files

(e.g., INDEX.md, MOC.md, or a note with a distinctive name) as entry points for folders or topic areas. These aggregate links, embed sections, or provide Dataview tables that serve as dashboards.

• Scan a few folders for recurring patterns: Is there always an INDEX.md?

A note that matches the folder name? A note with a type: moc property?

• If hub notes exist, they need maintenance: when creating, renaming, or

deleting a note in a folder with a hub note, check whether the hub needs updating (add/remove/rename an entry). This is a vault-specific convention — detect it, don't assume it.

• Persist the pattern: which folders have hub notes, what format they use,

and what maintenance they require.

What to Look For in Existing Notes

When reading existing notes to detect conventions, watch for:

• Deviations from defaults — These are usually intentional. If the vault

uses markdown links instead of wikilinks, that's a deliberate choice. Document it.

• Inconsistencies — If some notes use wikilinks and others use markdown

links, the vault may be in transition. Ask the user which convention to follow going forward.

• Plugin-specific patterns — Dataview inline fields, Tasks emoji syntax,

Meta Bind inputs — these indicate which plugins are actively used and how.

• Folder-specific schemas — Different folders may have different

frontmatter schemas. A projects/ folder might use status, due, priority while a people/ folder uses role, org, email.

How to Persist Conventions

Once a convention is detected and confirmed by the user, persist it so future sessions don't need to re-detect:

Option 1: Project CLAUDE.md (recommended for vault-wide conventions)

Add a skill invocation callout and a conventions section to the project's CLAUDE.md. The callout should appear near the top — before any content sections — so the skill is triggered every session:

> **This project uses the obsidian-vault skill.** Invoke
> `obsidian-vault:obsidian-vault` at the start of every session. It contains
> Obsidian editing conventions, plugin reference docs, and safe output rules
> that this project depends on.

## Obsidian Vault Conventions

- **Links:** Markdown links with relative paths (`[text](path.md)`)
- **Tags:** Lowercase hyphenated in frontmatter (`tags: [my-tag]`)
- **Tasks:** Tasks plugin emoji format, auto-set created/done dates
- **Kanban:** Lane position indicates status (no custom checkbox statuses)
- **Date format:** ISO 8601 (`YYYY-MM-DD`)
- **Templates folder:** `Templates/`

The callout is a reliability measure — CLAUDE.md is always read at session start, so embedding the invocation instruction ensures the skill activates even if the agent wouldn't otherwise reach for it.

Option 2: Auto-memory (supplemental)

If auto-memory is available (Cowork and Claude Code), use it for conventions that are better expressed as behavioral guidance than as a settings list:

---
name: obsidian-vault-link-convention
description: User chose markdown links over wikilinks in their Obsidian vault
type: feedback
---

Use markdown links with relative paths in Obsidian vault, not wikilinks.
**Why:** User chose markdown links so agent can read paths for file navigation.
**How to apply:** All .md file creation/editing in the vault uses
`[display](relative/path.md)` format.

When to use which:

• CLAUDE.md — the primary place for vault conventions. It's read at

session start, it's explicit, and any agent working in this project sees it. Put link style, frontmatter schemas, task format, template folder here.

• Auto-memory — supplements CLAUDE.md with behavioral context: why a

convention was chosen, correction history ("user asked me to stop doing X"), or nuance that doesn't fit a settings list.

Proactive Convention Surfacing

Don't wait for conventions to cause problems. When editing a vault for the first time or encountering an unfamiliar pattern:

1. Notice — "I see this vault uses markdown links instead of wikilinks"
2. Confirm — "Is this intentional? Should I continue this convention?"
3. Persist — Store the confirmed convention in CLAUDE.md or auto-memory
4. Follow — All subsequent edits respect the convention

If you're about to write something that deviates from a detected convention, stop and ask. The convention may exist for reasons that aren't obvious from the syntax alone.

---

Making Notes Useful in the Vault

Syntax correctness is the floor.

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aliasunder
• Source: aliasunder/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.