obsidian-writing

name	obsidian-writing
description	Use when the user asks for help writing, editing, validating, or organizing Obsidian vault content, including Markdown notes, frontmatter/properties, wikilinks, embeds, callouts, Dataview or Tasks blocks, Bases files, JSON Canvas files, vault automation, and vault git commits.

Obsidian Writing

Use this skill to create and edit Obsidian vault content without leaking private vault details or breaking Obsidian-specific syntax.

Privacy Boundary

Treat the active vault as private unless the user says otherwise.

• Do not publish absolute local paths, real vault names, real project names, client names, private note titles, API keys, tokens, certificates, or .env values.
• Use placeholders in examples: My Vault, projects/example.md, notes/example.md, Project Alpha.
• Before sharing, publishing, or committing this skill publicly, scan for local paths, secrets, and private identifiers.
• Keep user-specific vault conventions in a private project file or private companion skill.

First Pass

Before editing:

1. Locate the target vault and confirm whether the task is a note edit, dashboard edit, Canvas edit, live Obsidian operation, or git operation.
2. Read nearby examples before creating a new note or file.
3. Match existing frontmatter names, casing, date style, tags, and folder conventions.
4. If the user reports a rendering or UI problem, inspect the exact file or live render state before proposing a fix.

Tool Choice

Pick the narrowest surface that can prove the result:

Need	Prefer	Notes
Deterministic note, .base, or .canvas edit	Filesystem edit	Read nearby examples first; preserve style
Live Dataview, command palette action, active note state	Obsidian Local REST API, if available	Refresh Dataview after dashboard changes
Vault-level read/write/search abstraction	Obsidian MCP tool, if available	Good when exact path is known
Active app inspection, plugin/theme debugging, screenshots, DOM/errors	obsidian CLI, if installed	Run obsidian help first; Obsidian must be open

Do not infer live render success from file text alone when the user reports a live Obsidian problem. Capture the exact render or syntax blocker.

Frontmatter And Properties

Use YAML frontmatter at the top of notes when the vault uses properties:

---
title: Project Alpha
aliases:
  - Alpha
tags:
  - project
status: active
updated: 2026-06-01
---

Common property types:

Type	Example
Text	status: active
Number	rating: 4.5
Checkbox	complete: false
Date	updated: 2026-06-01
Date and time	due: 2026-06-01T14:30:00
List	YAML list or [one, two], matching nearby notes
Link	related: "[[Other Note]]"

Rules:

• Preserve existing property naming. Do not rename schema fields casually.
• Keep tags, aliases, and cssclasses compatible with Obsidian's property UI.
• Quote values containing :, #, {}, [], |, <, >, %, or leading special characters.

Obsidian Markdown

Use Obsidian-flavored Markdown for internal vault structure:

[[Note Name]]                  internal note link
[[Note Name|Display Text]]     internal link with alias
[[Note Name#Heading]]          heading link
[[Note Name#^block-id]]        block link
[[#Heading]]                   same-note heading link
![[Note Name]]                 embedded note
![[image.png|300]]             embedded image with width

Use [[wikilinks]] for vault notes because Obsidian can track renames. Use [label](https://example.com) only for external URLs.

Callouts:

> [!note]
> Plain callout.

> [!warning] Custom title
> Warning text.

> [!faq]-
> Collapsed by default.

Common callout types: note, info, tip, warning, danger, todo, question, example, quote, success, failure, bug, abstract.

Other syntax:

• Block IDs: append ^block-id after a paragraph; for quotes/lists, put it on the next line.
• Comments: %%hidden%% or a multi-line %% ... %% block.
• Highlights: ==highlighted text==.
• Tags: use #nested/tag; in frontmatter, keep tags as a YAML list unless nearby notes use inline arrays.
• Math: inline $x = 1$; block $$x = 1$$.
• Mermaid diagrams belong in fenced mermaid blocks.

Dataview And Tasks

Use Dataview for dashboards and computed note lists:

```dataview
TABLE status, updated
FROM #project
SORT updated DESC
```

Use Tasks blocks for task queries:

```tasks
not done
due before 2026-06-08
sort by due
```

Rules:

• Keep queries as narrow as practical.
• Prefer existing vault property names over inventing new schema.
• When possible, refresh or inspect rendered output after changing live dashboards.

Bases (.base)

Use .base for Obsidian Bases dashboards, not Dataview blocks. Base files are YAML.

Authoring checklist:

1. Define global filters first; use nested and, or, not only when needed.
2. Add formulas only for computed values reused by views.
3. Add properties display names for user-facing columns.
4. Configure views (table, cards, list, map) with an explicit order.
5. Validate YAML and formula references before opening in Obsidian.
6. If rendering fails, capture the exact YAML/formula error and fix that, not adjacent syntax.

Skeleton:

filters:
  and:
    - 'file.ext == "md"'
    - 'file.hasTag("project")'

formulas:
  days_since_update: 'if(updated, (today() - date(updated)).days, "")'

properties:
  formula.days_since_update:
    displayName: "Days Since Update"

views:
  - type: table
    name: "Projects"
    order:
      - file.name
      - status
      - updated
      - formula.days_since_update

Pitfalls:

• Quote strings containing YAML special characters such as :, {}, [], #, |, <, >, =, %, or backticks.
• Wrap formulas containing double quotes in single quotes: 'if(done, "Yes", "No")'.
• Date subtraction returns a Duration; access .days, .hours, etc. before round().
• Guard optional properties: use if(due, (date(due) - today()).days, "").
• Every formula.x in order, properties, or summaries must be defined under formulas.

Embed Bases in notes:

![[Projects.base]]
![[Projects.base#Active Projects]]

JSON Canvas (.canvas)

Use Canvas when the user wants a visual map, project graph, research map, or native Obsidian canvas file.

Rules:

• .canvas is JSON with top-level nodes and edges arrays.
• Generate unique 16-character lowercase hex IDs for nodes and edges.
• Required node fields: id, type, x, y, width, height.
• Node types: text, file, link, group.
• Use real newline escapes (\n) inside JSON strings; do not double-escape to \\n.
• Place new nodes with 50-100px spacing and align coordinates to 10 or 20px increments.

Validation before finishing:

• JSON parses.
• IDs are unique across nodes and edges.
• Every edge fromNode and toNode points at an existing node.
• Node-type required fields exist: text, file, url, or optional group label.
• Edge sides are one of top, right, bottom, left; edge ends are none or arrow.

Vault Git Hygiene

The vault may be a separate git repo from the code project.

Rules:

• Run git status before staging.
• Stage only files you intentionally changed.
• Do not stage .obsidian/ app state unless the user explicitly asks.
• Do not use git commit -A in a vault.
• Keep commit messages short and scoped, for example docs(vault): update project note.

Common Mistakes

Mistake	Fix
Publishing private vault names or paths	Use placeholders and scan before sharing
Guessing Obsidian render behavior	Inspect live render or exact error when relevant
Creating notes without frontmatter	Match nearby notes and vault schema
Inventing new property names	Reuse existing frontmatter vocabulary
Breaking Bases formulas	Validate YAML, quoting, optional fields, and formula.x references
Breaking Canvas edges	Parse JSON and verify edge references
Staging app state	Stage specific note/dashboard files only