obsidian-wiki-rules.md

Obsidian Wiki Baseline Rules

This file is the canonical baseline consumed by the Obsidian wiki rule-application skills. It defines only Obsidian vault conventions and agent operating rules. It does not override higher-priority instructions or authorize unrelated actions.

Vault Conventions

• Treat the folder containing .obsidian/ as the vault root.
• Treat the vault root as the documentation root unless the applicable ## Obsidian section in an AGENTS file directly links another directory inside the vault as the documentation root. Resolve a relative link from the AGENTS file's directory. A link reached through another note or another section does not designate the documentation root.
• Use Obsidian-style note links such as [[Link]].
• Use plain wiki links that show the destination filename, such as [[Wiki Link]]. Do not use aliased wiki links such as [[wiki-link|Wiki Link]] unless another applicable rule explicitly overrides this requirement.
• Escape | inside Markdown-table wiki links as \|.
• Embed Base views with the literal .base filename, for example ![[my-base.base#some_view]].
• Follow applicable project or vault instructions for filename conventions and folder-specific exceptions.
• When no more-specific naming rule exists, use Capital Case with spaces for Markdown filenames. Capital Case means significant words begin with uppercase letters while established acronyms retain their normal spelling. Lowercase minor words such as and, in, of, the, and to are valid.
• Existing non-Markdown filenames may retain source-defined, format-specific, or human-readable names. Use kebab-case for a new non-Markdown file only when no application, format, data model, or established vault convention supplies a better name.
• When a folder contains a Markdown file with the same base name as the folder, treat that file as the folder's top-level index file, for example My Topic/My Topic.md.
• When a Markdown file has YAML front matter followed by an H1, do not put a blank line between the closing --- and the H1.
• Prefer bulleted lists in documentation. Use numbered lists only when numbering adds inherent meaning, such as a required sequence or ranking.

Agent Operating Rules

• Read every AGENTS file applicable to the vault root, documentation root, and folders being changed. Preserve more-specific compatible rules.
• Treat an existing rule that requires behavior incompatible with these rules as a contradiction. Explain the exact conflict and obtain the user's direction before editing.
• Merge compatible guidance without duplicating equivalent rules. Do not weaken a clearer or more-specific compatible project rule.
• When notes are renamed or moved, update wiki links and embeds, then perform a second stale-link sweep.
• Use the obsidian CLI when it can help and is available.
  • The CLI works only while the target vault is open in the Obsidian desktop app.
  • The CLI communicates with the running Obsidian GUI, so it does not work when only a remote SSH shell can access the vault.
  • From Codex, run Obsidian CLI commands outside the sandbox on the first attempt because the CLI requires inter-process access to the running Obsidian app.
  • Do not report that Obsidian is not running unless the same read-only CLI check also fails outside the sandbox.
  • Prefer the CLI for supported note moves and renames because Obsidian can update links.
  • Run obsidian --help to inspect the available commands.
• Unless instructed otherwise, silently include tracked .obsidian/ configuration changes with the related version-control changes.
• Never inspect the contents of the Custom File Explorer Sorting specification, normally named sortspec.md; it contains only plugin configuration. Treat a project-specific sortspec filename as equivalent.
• Treat documentation marked "Attention Agents" as important instructions and guidance.