obsidian-reader by synapsync/synapse

Purpose

Act as the agent's primary knowledge retrieval layer over an Obsidian vault. This skill reads, searches, interprets, and reasons about markdown notes stored in Obsidian, turning the vault into a living memory that informs decisions, provides project context, and surfaces relevant knowledge on demand.

This is the read complement to obsidian-sync (which writes). Together they form a bidirectional knowledge bridge between the agent workspace and the user's Obsidian vault.

When to Use This Skill

User asks to read, consult, or check notes in Obsidian
User asks "what do my notes say about X?" or "check my plans in obsidian"
User needs project context that lives in Obsidian (plans, decisions, architecture docs)
User asks to summarize recent reports or plans stored in the vault
User asks to search for specific topics, decisions, or information across the vault
User wants to use Obsidian notes as context for a current task or decision
Another skill or agent needs knowledge that resides in the vault (multi-agent context)
User asks "what was the status of X?" referencing previously synced documents
User says "lee de obsidian", "busca en mis notas", "consulta obsidian"

When NOT to Use

User wants to write to Obsidian (use obsidian-sync instead)
User wants to edit an existing note in-place (use MCP tools directly)
The information is already in the current workspace (use Read/Grep/Glob directly)
User asks about files that are clearly local to the project, not in the vault

Critical Rules

RULE 1 - MCP FIRST, FILESYSTEM FALLBACK

Always attempt to use Obsidian MCP tools first. They provide the most reliable access to the vault with proper path resolution and plugin support.

# Step 1: Try to load MCP tools
ToolSearch query: "+obsidian read"
ToolSearch query: "+obsidian search"
ToolSearch query: "+obsidian list"

If ToolSearch returns no results or tools fail with connection errors, switch to filesystem fallback mode (see Fallback Strategy section).

RULE 2 - NEVER FABRICATE CONTENT

Only report information that exists verbatim in the notes. When reasoning over content:

Quote relevant passages with the source note path
Clearly distinguish between "the note says X" and "based on the notes, I interpret X"
If information is not found, say so explicitly rather than guessing

RULE 3 - RESPECT VAULT STRUCTURE

Obsidian vaults have semantic meaning in their structure:

Folders = categories/projects/topics
Tags (in frontmatter or inline #tag) = cross-cutting classification
Wikilinks ([[note-name]]) = relationships between concepts
Frontmatter = structured metadata (date, type, project, status)
Folder hierarchy = scope and context

Read and interpret all of these, not just the body text.

RULE 4 - PRIORITIZE BY RELEVANCE

When retrieving information, rank by:

Active/current over historical (check date frontmatter, prefer recent)
Directly referenced over tangentially related
Plans and decisions over raw notes (check type frontmatter)
Tagged/structured over unstructured notes
Notes with more backlinks often represent key concepts

RULE 5 - STRUCTURED OUTPUT FOR COMPOSABILITY

When another skill or agent requests knowledge, return structured summaries:

Source note path
Key findings
Relevant quotes
Confidence level (exact match vs. inferred)
Related notes that may contain additional context

Capabilities

Reading

Read individual notes by path
Read all notes in a folder (recursive)
Read notes matching a pattern (glob)
Parse and extract frontmatter metadata
Extract inline tags (#tag)
Detect and follow wikilinks ([[note]])

Searching

Full-text search across the vault
Filter by frontmatter fields (project, type, date, tags)
Filter by folder/path
Search by tag combinations
Find notes linking to a specific note (backlinks)

Reasoning

Summarize content from multiple notes
Correlate information across documents
Answer questions using vault content as source
Identify the most recent/relevant version of a topic
Build a context snapshot for the current task

Discovery

Map vault structure (folder tree)
List projects and their documents
Identify recently modified notes
Surface notes related to the current working directory/project

Workflow

Step 0: Detect Access Mode

Before any vault operation, determine the access strategy:

# Attempt MCP connection
ToolSearch query: "+obsidian read"

Result	Mode	Behavior
Tools loaded successfully	MCP Mode	Use `mcp__obsidian__*` tools for all operations
ToolSearch returns no obsidian tools	Fallback Mode	Ask user for vault path, use Read/Glob/Grep
Tools load but fail on call	Fallback Mode	Warn user MCP may be disconnected, switch to filesystem

If entering Fallback Mode, inform the user:

The Obsidian MCP server doesn't appear to be connected. I can still read your vault
directly from the filesystem. What is the path to your Obsidian vault?
(e.g., ~/Documents/MyVault or ~/obsidian-vault)

Step 1: Understand the Request

Parse the user's intent into one of these operations:

User Intent	Operation	Example
Read specific note	`READ_NOTE`	"lee la nota de arquitectura del proyecto X"
Read a folder	`READ_FOLDER`	"lee todos los planes en work/agent-sync-sdk/"
Search by topic	`SEARCH_TEXT`	"busca decisiones sobre la base de datos"
Search by tag	`SEARCH_TAG`	"encuentra notas con tag #strategy"
Search by metadata	`SEARCH_META`	"dame los reportes de febrero 2026"
Get project context	`PROJECT_CONTEXT`	"dame el contexto del proyecto agent-sync-sdk"
Answer a question	`REASON`	"segun mis notas, cual es el estado del proyecto?"
Explore structure	`DISCOVER`	"que tengo en mi vault?"

Step 2: Execute the Operation

READ_NOTE - Read a Specific Note

MCP Mode:

mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/00-strategic-analysis.md")

Fallback Mode:

Read(file_path: "/path/to/vault/work/agent-sync-sdk/plans/00-strategic-analysis.md")

After reading:

Parse frontmatter (title, date, project, type, tags)
Extract wikilinks ([[referenced-note]])
Extract inline tags (#tag-name)
Present a structured summary + full content if requested

READ_FOLDER - Read All Notes in a Directory

MCP Mode:

mcp__obsidian__list_directory(path: "work/agent-sync-sdk/plans")
# Then read each .md file found
mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/00-strategic-analysis.md")
mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/01-technical-debt.md")
# ... etc

Fallback Mode:

Glob(pattern: "/path/to/vault/work/agent-sync-sdk/plans/**/*.md")
# Then Read each file

After reading all notes:

Sort by date (frontmatter date field or filename)
Build a table of contents with title + type + date
Summarize each note in 1-2 sentences
Identify relationships between notes (shared tags, wikilinks)

SEARCH_TEXT - Full-Text Search

MCP Mode:

mcp__obsidian__search_notes(query: "race condition LockFileManager")

Fallback Mode:

Grep(pattern: "race condition", path: "/path/to/vault", type: "md")
# Then Read matching files for context

Present results as:

Found N notes matching "query":

1. **work/agent-sync-sdk/plans/01-technical-debt.md**
   > "El LockFileManager realiza operaciones read-modify-write sin mutex..."
   Type: technical-debt | Date: 2026-02-10

2. **work/agent-sync-sdk/plans/00-strategic-analysis.md**
   > "Condicion de carrera en el LockFileManager (P0)..."
   Type: strategic-analysis | Date: 2026-02-10

SEARCH_TAG - Search by Tag

MCP Mode:

mcp__obsidian__search_notes(query: "tag:#strategy")
# or
mcp__obsidian__manage_tags(action: "list")  # List all tags first

Fallback Mode:

# Search in frontmatter
Grep(pattern: "tags:.*strategy", path: "/path/to/vault", type: "md")
# Search inline tags
Grep(pattern: "#strategy", path: "/path/to/vault", type: "md")

SEARCH_META - Search by Metadata

Filter notes by frontmatter fields:

# Find all notes for a specific project
Grep(pattern: "project: agent-sync-sdk", path: "/path/to/vault", type: "md")

# Find all notes of a specific type
Grep(pattern: "type: technical-debt", path: "/path/to/vault", type: "md")

# Find all notes from a date range
Grep(pattern: "date: \"2026-02", path: "/path/to/vault", type: "md")

PROJECT_CONTEXT - Build Project Context

This is the most powerful operation -- it assembles a comprehensive context snapshot for a project:

Locate project folder in vault:

mcp__obsidian__list_directory(path: "work")
# Find folder matching project name

Read all notes in the project folder (recursive)
Sort and classify by type:
- Plans & roadmaps (type: plan, strategic-analysis)
- Technical debt & issues (type: technical-debt)
- Architecture docs (type: architecture)
- Sprint plans (type: sprint-plan)
- Reports & analysis (type: analysis, growth-vision)

Build a context summary:

## Project Context: agent-sync-sdk
Last updated: 2026-02-10

### Active Plans
- 00-strategic-analysis.md: Roadmap Q1-Q4 2026, 32 action items
- Key priority: Transition from "motor" to "producto usable" in 4-6 weeks

### Known Issues
- 01-technical-debt.md: 18 findings (5 critical, 8 medium, 5 low)
- Top P0: Race condition in LockFileManager

### Vision
- 02-growth-vision.md: Maturity score 3.0/5
- Target: npm + CLI + registry in 3 months

### Key Decisions
- [extracted from notes where type includes "decision" or content discusses trade-offs]

### Related Notes
- [any notes in other folders that link to this project]

Present to user or pass to requesting agent/skill

REASON - Answer Questions Using Vault

When the user asks a question that requires reasoning over vault content:

Identify relevant notes using SEARCH_TEXT + SEARCH_TAG + SEARCH_META
Read the top N most relevant notes (aim for 3-7, max 10)
Extract relevant passages that address the question

Synthesize an answer citing sources:

Based on your Obsidian notes:

[Answer to the question with reasoning]

Sources:
- work/agent-sync-sdk/plans/00-strategic-analysis.md (Section 5.1)
- work/agent-sync-sdk/plans/01-technical-debt.md (Section 3.1)

Note: [Any caveats about completeness or recency of information]

DISCOVER - Explore Vault Structure

Map the vault and present an overview:

mcp__obsidian__list_directory(path: "/")
# Recursively list first 2 levels
mcp__obsidian__list_directory(path: "/work")
mcp__obsidian__list_directory(path: "/work/agent-sync-sdk")
# ... for each subfolder

Also use vault stats if available:

mcp__obsidian__get_vault_stats(recentCount: 10)

Present as:

Your Obsidian Vault:

work/
  agent-sync-sdk/
    plans/          (3 notes - last updated 2026-02-10)
  bmtz/
    ...
  wdt/
    ...

Stats: X total notes, Y folders
Recently modified: [list of 5-10 most recent]

Step 3: Present Results

Always structure output clearly:

For single notes:

Show frontmatter metadata as a header table
Present content (full or summarized based on length)
List outgoing links and tags

For multiple notes:

Table of contents first (title, type, date, path)
Then individual summaries
Highlight connections between notes

For questions/reasoning:

Direct answer first
Supporting evidence with source citations
Caveats about information completeness
Suggestions for where to find more information

Fallback Strategy (No MCP)

When the Obsidian MCP server is not available, the skill operates in filesystem mode:

Vault Discovery

Ask the user for the vault path if not known:

AskUserQuestion:
  question: "What is the path to your Obsidian vault?"
  header: "Vault path"
  options:
    - label: "~/obsidian-vault"
      description: "Common default location"
    - label: "~/Documents/Obsidian"
      description: "Documents folder"

Reading Notes (Fallback)

# Read a specific note
Read(file_path: "/absolute/path/to/vault/note.md")

# List directory contents
Bash(command: "ls -la /path/to/vault/work/")

# Search content
Grep(pattern: "search term", path: "/path/to/vault", type: "md")

# Find by glob
Glob(pattern: "/path/to/vault/**/*.md")

Limitations in Fallback Mode

Feature	MCP Mode	Fallback Mode
Read notes	Full support	Full support
List directories	Full support	Full support (via Bash ls)
Search content	Optimized vault search	Grep (slower on large vaults)
Frontmatter parsing	Native	Manual parsing from Read output
Tags management	Native API	Grep-based search
Backlinks	If MCP supports it	Manual wikilink grep
Vault stats	Native API	Bash wc/find
Note metadata	Native API	Parsed from frontmatter

Frontmatter Parsing

This skill relies heavily on frontmatter for intelligent filtering. Expected fields:

---
title: "Document Title"
date: "2026-02-10"
project: "agent-sync-sdk"
type: "strategic-analysis"           # See type taxonomy below
tags: [strategy, roadmap, plan]
source: ".agents/plan/2026-02-10/"   # Original local path (set by obsidian-sync)
status: "active"                     # Optional: active, archived, draft
---

Type Taxonomy

Use these types for filtering and prioritization:

Type	Priority	Description
`strategic-analysis`	High	High-level project strategy and direction
`plan`	High	Actionable plans with tasks and timelines
`sprint-plan`	High	Sprint-level task breakdowns
`technical-debt`	High	Known issues and debt tracking
`architecture`	Medium	System design and architecture decisions
`requirements`	Medium	Feature requirements and specifications
`growth-vision`	Medium	Growth analysis and future vision
`analysis`	Medium	General analysis documents
`code-review`	Medium	Code review findings
`report`	Low	General reports and summaries
`note`	Low	Unstructured notes
`meeting`	Low	Meeting notes
`reference`	Low	Reference material

Priority Ranking Algorithm

When multiple notes are found, rank them using this weighted score:

score = recency_weight + type_weight + relevance_weight

recency_weight:
  - Today:       +3
  - This week:   +2
  - This month:  +1
  - Older:       +0

type_weight:
  - High types:   +3
  - Medium types:  +2
  - Low types:     +1

relevance_weight:
  - Exact match in title:     +3
  - Match in frontmatter:     +2
  - Match in body:            +1
  - Match in linked note:     +0.5

Relationship Mapping

Wikilinks

Detect and follow [[wikilinks]] to understand relationships:

# In a note:
"See [[01-technical-debt]] for details on the race condition."
"This connects to the [[architecture]] decisions from Sprint 3."

When the user asks about a topic, also check notes that are linked from the primary results.

Backlinks

Find notes that link TO a specific note:

MCP Mode:

mcp__obsidian__search_notes(query: "[[00-strategic-analysis]]")

Fallback Mode:

Grep(pattern: "\\[\\[00-strategic-analysis\\]\\]", path: "/path/to/vault", type: "md")

Tag Networks

Tags create cross-cutting relationships:

# Find all notes sharing a tag
Grep(pattern: "agent-sync-sdk", path: "/path/to/vault", type: "md")

Integration with Other Skills

Skill	How obsidian-reader Integrates
`obsidian-sync`	Read notes that were previously synced; verify sync status
`project-planner`	Provide existing project context before planning begins
`code-analyzer`	Supply architecture notes as reference for analysis
`universal-planner`	Feed historical plans and decisions as input context
`sdlc-planner`	Provide requirements docs and previous SDLC phases

Multi-Agent Composition

When used by another agent or skill, return a structured context object:

## Context from Obsidian Vault
### Project: {project-name}
### Retrieved: {timestamp}
### Notes Read: {count}

#### Summary
{2-3 sentence summary of what was found}

#### Key Documents
| Note | Type | Date | Relevance |
|------|------|------|-----------|
| path/to/note.md | strategic-analysis | 2026-02-10 | High |

#### Key Findings
1. {Finding 1 with source citation}
2. {Finding 2 with source citation}

#### Active Decisions
- {Decision from notes with source}

#### Open Questions
- {Anything the notes don't answer but might be relevant}

Input / Output Specification

Inputs

Input	Type	Required	Description
`query`	string	Yes	What to read/search/answer (natural language)
`scope`	string	No	Vault path to limit search (e.g., "work/agent-sync-sdk")
`filters`	object	No	Frontmatter filters: `{ project, type, tags, date_from, date_to }`
`depth`	enum	No	`summary` (default), `detailed`, `full`
`max_notes`	number	No	Maximum notes to read (default: 10)

Outputs

Output	Type	Description
`notes_found`	number	Count of matching notes
`results`	array	List of `{ path, title, type, date, summary, relevance_score }`
`answer`	string	Synthesized answer (for REASON operations)
`sources`	array	List of source note paths with relevant sections
`related`	array	Notes linked from results that may contain additional context

Error Handling

Error	Cause	Recovery
MCP tools not found	Obsidian MCP not configured	Switch to fallback mode, ask for vault path
MCP connection refused	Obsidian app not running or REST API disabled	Inform user, switch to fallback mode
Note not found	Wrong path or note deleted	Search for similar note names, suggest alternatives
Empty vault path	User's vault location unknown	Ask user with AskUserQuestion
Large vault (>1000 notes)	Performance concern	Use targeted searches, avoid full vault reads
Frontmatter parse error	Malformed YAML	Read as plain text, warn user about metadata loss
No results found	Query too specific or content doesn't exist	Broaden search, suggest alternative terms, check different folders
Permission denied	File access restrictions	Inform user, suggest checking vault permissions

Best Practices

Before Reading

Always try MCP first before falling back to filesystem
Scope searches to relevant folders when possible (don't search entire vault for project-specific info)
Check if the user has already mentioned the vault location or project in conversation context

During Reading

Parse frontmatter on every note read -- it's the primary metadata source
When reading multiple notes, process them in parallel when possible
For large notes (>500 lines), summarize instead of presenting full content unless asked
Track wikilinks as you read -- they form the knowledge graph

After Reading

Always cite sources with exact note paths
Distinguish between quoted content and your interpretation
If information seems outdated (old date), warn the user
Suggest related notes the user might want to check
If the query couldn't be fully answered, explain what's missing

Performance

For DISCOVER operations, limit to 2 levels of directory depth initially
For SEARCH operations, prefer MCP search over Grep on large vaults
For PROJECT_CONTEXT, cache the folder listing and reuse within the same conversation
Avoid reading more than 10 full notes in a single operation unless explicitly requested

Limitations

Read-only: This skill does not modify vault content (use obsidian-sync for writing)
No real-time sync: Reads the vault state at query time; doesn't watch for changes
Markdown only: Processes .md files; ignores images, PDFs, and other attachments
No graph view: Cannot render Obsidian's graph view; provides text-based relationship mapping
MCP dependency: Full functionality requires the Obsidian MCP server; fallback mode has reduced capabilities
No plugin data: Cannot access Obsidian plugin-specific data (Dataview queries, Kanban boards, etc.)
Single vault: Operates on one vault at a time (the one connected via MCP or specified by the user)
Context window: Very large vaults may require targeted queries; reading everything is not feasible

Example: Full Context Retrieval

User says: "What's the current state of agent-sync-sdk according to my Obsidian notes?"

Step 0: Load MCP tools

ToolSearch("+obsidian read")
ToolSearch("+obsidian search")
ToolSearch("+obsidian list")

Step 1: Locate project folder

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

mcp__obsidian__list_directory(path: "work/agent-sync-sdk")
# Found: plans/

mcp__obsidian__list_directory(path: "work/agent-sync-sdk/plans")
# Found: 00-strategic-analysis.md, 01-technical-debt.md, 02-growth-vision.md

Step 2: Read all project notes (parallel)

mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/00-strategic-analysis.md")
mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/01-technical-debt.md")
mcp__obsidian__read_note(path: "work/agent-sync-sdk/plans/02-growth-vision.md")

Step 3: Parse frontmatter, extract key info, rank by relevance

Step 4: Present synthesized answer:

Based on your Obsidian notes (3 documents, last updated 2026-02-10):

## Project Status: agent-sync-sdk

**Maturity Score:** 3.0/5 -- "Motor excelente, carroceria incompleta"

**Fortalezas:**
- TypeScript strict con 0 `any`, 458 tests, 92%+ coverage
- Arquitectura en capas con composition root, branded types, Result pattern
- 39 agentes soportados, 4 providers funcionales

**Problemas Criticos (P0):**
1. Race condition en LockFileManager (riesgo de corrupcion de datos)
2. 3 providers stub que fallan silenciosamente
3. AgentType desincronizado (16 de 39 agentes en tipo publico)

**Proximas Acciones (esta semana):**
1. Corregir race condition (2-4h)
2. Resolver providers stub (1h)
3. Unificar AgentType (30min)
4. Implementar dispose() (2h)
5. Agregar timeouts a fetch() (2h)

**Vision:** Publicar CLI + SDK en npm, crear starter-cognitives,
establecer release pipeline. Ventana: 4-6 semanas.

Sources:
- work/agent-sync-sdk/plans/00-strategic-analysis.md (Sections 1, 2, 5)
- work/agent-sync-sdk/plans/01-technical-debt.md (Sections 3, 7)
- work/agent-sync-sdk/plans/02-growth-vision.md (Sections 2, 7)

Example: Cross-Note Search

User says: "Busca en obsidian todas las menciones de race condition"

mcp__obsidian__search_notes(query: "race condition")

# Results:
Found 2 notes matching "race condition":

1. work/agent-sync-sdk/plans/01-technical-debt.md
   > "Condicion de carrera en LockFileManager (read-modify-write sin proteccion)"
   > "Si dos operaciones addEntry() se ejecutan concurrentemente, una puede
   >  sobreescribir los cambios de la otra."
   Type: technical-debt | Date: 2026-02-10 | Priority: P0

2. work/agent-sync-sdk/plans/00-strategic-analysis.md
   > "Condicion de carrera en LockFileManager (P0) - Hace inviable el uso del
   >  SDK en pipelines de CI/CD"
   > Solucion recomendada: mutex async o optimistic locking
   Type: strategic-analysis | Date: 2026-02-10

Recommendation: The technical-debt document (01) has the most detailed
analysis. The strategic document (00) summarizes the business impact.

Future Enhancements

Vault indexing: Build a local index of vault structure and frontmatter for faster queries
Semantic search: Use embeddings for meaning-based search beyond keyword matching
Change detection: Track what changed in the vault since last read
Dataview compatibility: Parse Dataview queries and present their results
Canvas support: Read and interpret Obsidian Canvas files (.canvas)
Multi-vault: Support reading from multiple vaults simultaneously
Obsidian URI: Generate obsidian:// URIs for direct note opening from terminal
Knowledge graph export: Generate a relationship map of the vault in Mermaid format