Obsidian Write Document Skill

Create or update canonical Obsidian documents with consistent formatting and proper linking.

See also: Shared Conventions | Safety Guidelines

Purpose

Write well-structured Obsidian Markdown documents that follow vault conventions, use proper wikilinks, and include source attribution.

Background Knowledge

Obsidian Markdown Conventions

Obsidian uses standard Markdown with extensions:

• Wikilinks: [[Page Name]] or [[path/to/page|Display Text]]
• Embeds: ![[embedded-note]] or ![[image.png]]
• Tags: #tag or nested #parent/child
• Frontmatter: YAML block at file start between --- markers

Document Quality Standards

Canonical documents must be:

• Git-safe: No special characters that cause issues
• Obsidian-compatible: Valid wikilinks and formatting
• Human-reviewable: Clear structure and language
• Traceable: Source notes referenced in footer

Write Modes

Input Sources

The skill accepts:

• Target path: Destination file path within vault
• Mode: create, replace, or append
• Content: Document content to write
• Source files: List of source notes for attribution
• Proposal: Optional proposal from obsidian-extract-inbox

Document Structure

Required Elements

Every canonical document must include:

---
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft | review | canonical
tags:
  - relevant-tag
---

# Document Title

Brief one-paragraph summary of document scope.

## Section Heading

Content organized by topic.

## Another Section

More content with [[wikilinks]] to related documents.

---

## Sources

- [[_inbox/source-note-1]]
- [[_inbox/source-note-2]]

Frontmatter Fields

Heading Hierarchy

Use consistent heading levels:

• # - Document title (one per document)
• ## - Major sections
• ### - Subsections
• #### - Sub-subsections (use sparingly)

Source Footer

Every document must end with a Sources section:

---

## Sources

- [[_inbox/original-note-1]] - Primary source for Section X
- [[_inbox/original-note-2]] - Additional context for Section Y

Workflow

1. Validate Inputs

Before writing, verify:

# Check if target directory exists
ls -la /path/to/vault/$(dirname target-path)

# For create mode, verify file doesn't exist
test ! -f /path/to/vault/target-path.md && echo "Safe to create"

# For replace/append mode, verify file exists
test -f /path/to/vault/target-path.md && echo "File exists"

2. Prepare Content

Format content according to standards:

1. Add frontmatter with required fields
2. Ensure single H1 heading (document title)
3. Convert plain links to wikilinks
4. Validate heading hierarchy
5. Add source footer

3. Validate Wikilinks

Check that wikilinks reference valid targets:

# Extract wikilinks from content
grep -oE "\[\[[^\]]+\]\]" content.md

# Verify targets exist (optional, warn if not)
for link in $(grep -oE "\[\[[^\]|]+"); do
  target="${link#[[}"
  test -f "/path/to/vault/${target}.md" || echo "Warning: $target not found"
done

4. Execute Write

Based on mode:

Create mode:

# Fail if file exists
test -f /path/to/target.md && exit 1
cat > /path/to/target.md << 'EOF'
[content]
EOF

Replace mode:

# Backup existing content (in memory, for undo message)
cat /path/to/target.md > /tmp/backup.md
cat > /path/to/target.md << 'EOF'
[content]
EOF

Append mode:

cat >> /path/to/target.md << 'EOF'

[content to append]
EOF

5. Verify Write

After writing, confirm success:

# Verify file exists and has content
test -s /path/to/target.md && echo "Write successful"

# Show file stats
wc -l /path/to/target.md

Example: Creating a Spec Document

Input:

{
  "target_path": "specs/authentication.md",
  "mode": "create",
  "title": "Authentication Specification",
  "sections": [
    {
      "heading": "Overview",
      "content": "This document specifies the authentication system..."
    },
    {
      "heading": "OAuth Integration",
      "content": "The system uses OAuth 2.0 with the following flow..."
    },
    {
      "heading": "Token Management",
      "content": "JWT tokens are used for session management..."
    }
  ],
  "source_files": ["_inbox/auth-notes.md", "_inbox/login-flow.md"]
}

Output document: specs/authentication.md

---
created: 2026-01-18
updated: 2026-01-18
status: draft
tags:
  - authentication
  - security
---

# Authentication Specification

This document specifies the authentication system for the application, including OAuth integration and token management.

## Overview

This document specifies the authentication system...

## OAuth Integration

The system uses OAuth 2.0 with the following flow...

See also: [[specs/oauth-providers]] for supported providers.

## Token Management

JWT tokens are used for session management...

Related: [[design/session-handling]] for session lifecycle details.

---

## Sources

- [[_inbox/auth-notes.md]] - Original authentication design notes
- [[_inbox/login-flow.md]] - Login flow documentation

Formatting Rules

Do

• Use proper heading hierarchy
• Include frontmatter on all documents
• Use [[wikilinks]] for internal references
• Add descriptive link text when helpful: [[path/file|Display Text]]
• Include source attribution footer
• Use standard Markdown formatting

Do Not

• Use emojis in document content
• Add "fluff" or filler content
• Use HTML tags (pure Markdown only)
• Create deeply nested headings (max 4 levels)
• Leave broken wikilinks without noting them
• Include timestamps in document body (use frontmatter)

Link Formatting

# Good
See [[authentication]] for details.
Refer to [[specs/api-design|API Design Spec]] for endpoints.

# Bad
See [authentication](authentication.md) for details.
Refer to the API design spec.

Policies

Always

• Require explicit instruction before writing files
• Validate target path is within vault boundaries
• Include frontmatter with required fields
• Add source attribution footer
• Use create mode for new files, replace/append for existing
• Preserve existing content in append mode

Never

• Write files without explicit instruction
• Overwrite files in create mode
• Delete source files after writing
• Write outside the designated vault
• Add content not derived from sources
• Use replace mode when append is appropriate

Mode Selection Guidance

Error Handling

If write fails:

1. Report the error clearly
2. Do not retry automatically
3. Preserve any backup information
4. Suggest remediation steps

Integration

This skill works with:

• obsidian-read-context - Informs document structure and links
• obsidian-extract-inbox - Consumes proposals to create documents
• obsidian-issue-from-doc - Documents can become issue sources

Output Format

When run, report:

1. Action taken (create/replace/append)
2. Target file path
3. File statistics (lines, size)
4. Wikilinks created
5. Warnings (missing link targets, etc.)
6. Next steps recommendation