obsidian-sync

Purpose

Sync markdown reports, plans, and documentation generated in the workspace to an Obsidian vault using the Obsidian MCP server. Acts as the “last mile” helper that takes output produced by other skills (planners, analyzers, reporters) and persists it in the user’s knowledge base.

When to Use This Skill

• User explicitly asks to sync, save, move, or store files to Obsidian
• User says “guardar en obsidian”, “sincronizar a obsidian”, or similar in Spanish
• User asks to create a report/plan AND save it to Obsidian (this skill handles the Obsidian part after creation)
• User wants to browse their vault to choose where to place documents
• User asks to move an entire folder (e.g., .agents/plan/) to their Obsidian vault
• After another skill finishes generating documents, user wants them in Obsidian

When NOT to Use

• User wants to read or search notes already in Obsidian (use MCP tools directly)
• User wants to edit an existing Obsidian note in-place (use MCP tools directly)
• Files are not markdown or text-based (this skill is for .md content)

Critical Rules

RULE 1 – ALWAYS LOAD MCP TOOLS FIRST

Before calling ANY Obsidian MCP tool, you MUST use ToolSearch to load them:

ToolSearch query: "+obsidian write"    # For writing notes
ToolSearch query: "+obsidian list"     # For listing directories
ToolSearch query: "+obsidian read"     # For reading notes

Never call mcp__obsidian__* tools without loading them first via ToolSearch. They are deferred tools and will fail if not loaded.

RULE 2 – ALWAYS ASK WHERE TO SAVE

Never assume the destination folder. Always:

1. List the vault’s root directories
2. Let the user pick or specify the destination
3. If the user already specified a path (e.g., “save to work/my-project/plans”), confirm it exists or offer to create it

RULE 3 – PRESERVE CONTENT INTEGRITY

• Read the source file completely before writing to Obsidian
• Never modify the document content (headings, tables, code blocks, etc.)
• Only ADD frontmatter metadata if the file doesn’t already have it
• If the file already has frontmatter, merge Obsidian-specific fields without overwriting existing ones

RULE 4 – GENERATE MEANINGFUL FRONTMATTER

Every note written to Obsidian MUST include frontmatter with at minimum:

---
title: "Document Title"
date: "YYYY-MM-DD"
project: "{project-name}"
type: "{document-type}"
tags: [relevant, tags, here]
---

Infer these values from:

• title: First H1 heading in the document, or filename
• date: File modification date, or today’s date
• project: Current working directory name or git repo name
• type: Infer from content (e.g., “technical-debt”, “strategic-analysis”, “sprint-plan”, “code-review”, “architecture”)
• tags: Infer from project name, document type, and key topics

RULE 5 – REPORT RESULTS

After syncing, always report:

• How many files were synced
• The exact Obsidian paths where they were saved
• Any files that were skipped and why

Workflow

Step 1: Identify What to Sync

Determine the source files from the user’s request:

Discovery commands:

# Find all markdown files in a directory
Glob pattern: ".agents/plan/**/*.md"

# Find recently created reports
Glob pattern: ".agents/**/*.md"

# Find specific file
Glob pattern: "**/{filename}.md"

Step 2: Load Obsidian MCP Tools

Always load the required tools before using them:

ToolSearch query: "+obsidian list"     # Loads mcp__obsidian__list_directory
ToolSearch query: "+obsidian write"    # Loads mcp__obsidian__write_note

Load both in parallel if possible. Only load read or search if you need to check existing content.

Step 3: Browse Vault and Present Options

List the vault structure and present folder options to the user:

mcp__obsidian__list_directory(path: "/")           # Root level
mcp__obsidian__list_directory(path: "/work")        # One level deeper if needed

Build a folder tree and present it using AskUserQuestion:

AskUserQuestion:
  question: "Where should I save the documents in your Obsidian vault?"
  header: "Vault folder"
  options:
    - label: "work/project-name/plans"
      description: "Inside your project's plans folder"
    - label: "work/project-name/"
      description: "At the project root in your vault"
    - label: "Create new folder"
      description: "I'll create a new folder path for you"

Important behaviors:

• If the user already specified a destination (e.g., “save to work/agent-sync-sdk/plans”), skip the question and use that path directly
• If a project folder already exists in the vault, suggest it as the first (recommended) option
• Always include “Create new folder” as an option
• If user picks “Create new folder” or “Other”, ask for the desired path

Step 4: Read Source Files

For each file to sync:

1. Read the full content using the Read tool
2. Check if frontmatter already exists (starts with ---)
3. Extract the first H1 heading for the title
4. Determine the project name from cwd or git

Step 5: Write to Obsidian

For each file, call mcp__obsidian__write_note with:

mcp__obsidian__write_note(
  path: "{vault-destination}/{filename}.md",
  content: "{file-content-without-frontmatter}",
  frontmatter: {
    "title": "Document Title",
    "date": "2026-02-10",
    "project": "agent-sync-sdk",
    "type": "strategic-analysis",
    "source": ".agents/plan/2026-02-10/00-strategic-analysis.md",
    "tags": ["agent-sync-sdk", "strategy", "plan"]
  }
)

Frontmatter generation logic:

Type inference:

Step 6: Report Results

After all files are written, report a summary:

Synced to Obsidian:
- work/agent-sync-sdk/plans/00-strategic-analysis.md
- work/agent-sync-sdk/plans/01-technical-debt.md
- work/agent-sync-sdk/plans/02-growth-vision.md

3 files synced successfully to vault folder: work/agent-sync-sdk/plans/

Batch Sync Pattern

When syncing an entire folder, process files efficiently:

1. Glob all .md files in the source directory
2. Read all files in parallel (multiple Read calls in one message)
3. Load MCP tools once (ToolSearch)
4. List vault directory once to build options
5. Ask user once for destination (not per file)
6. Write all files in sequence (Obsidian MCP may not support parallel writes safely)
7. Report all results at the end

Integration with Other Skills

This skill is designed to be the output handler for other skills:

Composition pattern: When the user says “create a plan and save it to obsidian”:

1. The planner skill runs first and produces documents locally
2. This skill then picks up those documents and syncs them to the vault
3. The user only needs one instruction; the skills compose naturally

Configuration Options

By Sync Scope

By Destination Logic

Best Practices

Before Sync

• Verify the source files exist and are readable
• Check that the Obsidian MCP server is connected (ToolSearch will fail if not)
• If syncing output from another skill, ensure that skill has completed

During Sync

• Never modify document content — only add/merge frontmatter
• Use the mcp__obsidian__write_note with mode: "overwrite" for clean writes
• If a note already exists at the destination, warn the user before overwriting
• Process files sequentially to avoid MCP race conditions

After Sync

• Always report the full list of synced paths
• If any files failed, report which ones and why
• Suggest the user check the notes in Obsidian for visual verification

Limitations

• Obsidian MCP required: The Obsidian REST API MCP server must be configured and running
• Markdown only: This skill handles .md files. Binary assets, images, and non-text files are not synced
• No bidirectional sync: This skill writes TO Obsidian, it does not pull changes back from Obsidian
• No conflict resolution: If a note exists at the destination, it will be overwritten (with user confirmation)
• Single vault: Operates on the vault connected to the MCP server; cannot switch between multiple vaults

Troubleshooting

Example: Full Sync Flow

User says: “sincroniza los reportes de .agents/plan/2026-02-10/ a obsidian”

Step 1 – Discover files:

Glob(".agents/plan/2026-02-10/**/*.md")
# Found: 00-strategic-analysis.md, 01-technical-debt.md, 02-growth-vision.md

Step 2 – Load MCP tools:

ToolSearch("+obsidian list")
ToolSearch("+obsidian write")

Step 3 – Browse vault:

mcp__obsidian__list_directory(path: "/")
# Found: work/
mcp__obsidian__list_directory(path: "/work")
# Found: agent-sync-sdk/, bmtz/, wdt/

Step 4 – Ask user:

AskUserQuestion:
  "Where should I save the 3 reports in your Obsidian vault?"
  options:
    - "work/agent-sync-sdk/plans (Recommended)"  # Project folder exists
    - "work/agent-sync-sdk/"                       # Project root
    - "Create new folder"

Step 5 – Read & Write:

# Read all 3 files in parallel
Read(".agents/plan/2026-02-10/00-strategic-analysis.md")
Read(".agents/plan/2026-02-10/01-technical-debt.md")
Read(".agents/plan/2026-02-10/02-growth-vision.md")

# Write each to Obsidian with generated frontmatter
mcp__obsidian__write_note(
  path: "work/agent-sync-sdk/plans/00-strategic-analysis.md",
  content: "...",
  frontmatter: { title: "Analisis Estrategico...", date: "2026-02-10", project: "agent-sync-sdk", type: "strategic-analysis", tags: [...] }
)
# ... repeat for each file

Step 6 – Report:

Synced 3 files to Obsidian:
  - work/agent-sync-sdk/plans/00-strategic-analysis.md
  - work/agent-sync-sdk/plans/01-technical-debt.md
  - work/agent-sync-sdk/plans/02-growth-vision.md