Obsidian Writer

Obsidian Writer

Role

Knowledge-base writer for the shared atmosphere-vault Obsidian vault. Applies Atmosphere frontmatter standards and directory conventions so every note lands in the right place with the right metadata — consistent enough to be searched, linked, and understood later.

When to Use

Invoke for any of these document types, whether the user names the type or not:

• ADR — Architecture Decision Record (Architecture/ADRs/)
• Runbook — Operational procedure or on-call guide (Development/Runbooks/)
• Plan — Feature or project planning document (Claude Plans/)
• API doc — Endpoint reference, SDK documentation (APIs/)
• Guide / how-to — Developer setup, walkthrough, tutorial (Development/)
• Session output — Claude Code session artifact (Claude Outputs/)
• Methodology — Process, workflow, team practice (Methodology/)

Workflow

Step 1 — Identify doc type and target directory

Use the quick-reference table below. When ambiguous, ask the user which type fits best.

Step 2 — Sync, then search for existing notes

Pull the remote first so the search sees every note that has already been pushed, then check whether a relevant note already exists to avoid duplicates:

.claude/skills/obsidian-writer/vault-sync.sh pull
obsidian search query="<keywords from the topic>" limit=5

If pull exits non-zero, stop and report what it printed instead of reading or writing the vault. Either a conflict it could not auto-resolve moved the unpushed local commits to a vault-sync/backup-<ts> branch (main now matches origin, so those notes stay missing until that branch is merged by hand), or the rebase did not run and nothing was changed (retry).

If a match is found, read it first (obsidian read file="<name>") and decide whether to update the existing note or create a new one.

Step 3 — Compose content

Read references/vault-structure.md for the complete frontmatter field table.

Start every note with YAML frontmatter, then a level-1 heading matching the filename:

---
date: YYYY-MM-DD
tags: [atmosphere, <type-tag>]
status: <value>        # only for ADR and Plan
service: <name>        # only for Runbook and API doc
severity: <P0–P3>      # only for Runbook
---

# Note Title

Use [[wikilinks]] to link related vault notes — never absolute file paths.

Step 4 — Write to the live vault

Obsidian must be running and the atmosphere-vault must be the focused vault.

# Create a new note
obsidian create name="<Note Title>" path="<Directory/Filename.md>"

# Append a section to an existing note
obsidian append file="<Note Title>" content="## New Section\n<content>"

Step 5 — Verify and link

After writing, read the note back to confirm content landed correctly:

obsidian read file="<Note Title>"

Then update any related notes with a [[wikilink]] to the new document.

Step 6 — Publish

Commit and push only the notes you wrote or edited, through the sync script (paths are relative to the vault — never the whole tree):

.claude/skills/obsidian-writer/vault-sync.sh push -m "docs(adr): <what>" \
  "Architecture/ADRs/ADR-0042 Adopt Virtual Threads.md"

Exit 0 means published: after the sync and push, origin/main holds each of your notes exactly as committed. Your notes are the files under the paths that the push's commit changed, and those the vault holds differently from the origin/main it forked from (an earlier unpushed commit, such as the timer's, changed them). Every other file under the paths (a directory's other notes, a note the timer already pushed) was already on origin/main as the vault holds it, and must still be there or have changed since only by edits made on top of that version. The output lists those under "already on origin/main … then changed there by later edits" without failing the push: someone edited or deleted the note after it was published, so re-read it before you report it. Any other exit means not published, and the output names each file origin/main does not hold as committed, and why. Most often someone edited the same note at the same time and the remote's side won or was merged in, whether over your push or over a timer push that got there first; the vault then holds origin's version, so re-read those notes and redo your change if it is gone. A backup branch, a rebase that did not run and a push still rejected are named as such. Never report a note as published on a non-zero exit.

The vault's history uses docs(adr), docs(plan) and docs(claude-output) prefixes for these commits; the timers' commits are vault: auto-save.

Quick Reference

Frontmatter Standards

ADR — required: date, status, tags: [atmosphere, adr]

• Status values: proposed → accepted → deprecated / superseded
• Filename convention: ADR-NNNN Short Title.md (zero-padded, four digits)

Runbook — required: date, severity, service, tags: [atmosphere, runbook, sre]

• Severity values: P0 (critical), P1 (high), P2 (medium), P3 (low)

Plan — required: date, status, tags: [atmosphere, plan]

• Status values: draft, active, completed

API doc — required: date, service, tags: [atmosphere, api]

Session output — required: date, tags: [atmosphere, claude-output]

Guide / how-to — required: date, tags: [atmosphere, guide, <domain>]

• Replace <domain> with the relevant area (e.g., runtime, spring, quarkus)