Obsidian Read Context Skill

Understand the current state of knowledge in an Obsidian vault by analyzing markdown files.

See also: Shared Conventions | Safety Guidelines

Purpose

Scan and analyze Obsidian vault contents to identify topics, detect overlaps, find gaps, and suggest canonical document targets for consolidation.

Background Knowledge

What is an Obsidian Vault?

An Obsidian vault is a folder containing Markdown files that form a knowledge base. Key characteristics:

• Markdown files: Plain text with .md extension
• Wikilinks: Internal links using [[double brackets]] syntax
• Frontmatter: Optional YAML metadata at file start
• Folders: Organize notes by category or status (e.g., _inbox, specs, design)

Common Vault Structures

vault/
├── _inbox/           # Unprocessed notes, quick captures
├── specs/            # Technical specifications
├── design/           # Design documents
├── notes/            # General notes
├── templates/        # Obsidian templates
└── README.md         # Vault overview

Reading Modes

Input Sources

The skill accepts:

• Paths: Single files or directories within the vault
• Mode: skim or deep analysis depth
• Filters: Optional file patterns to include/exclude

Output Contract

Produce a structured analysis:

{
  "vault_path": "/path/to/vault",
  "files_analyzed": 42,
  "mode": "skim | deep",
  "topics": [
    {
      "name": "Topic Name",
      "files": ["file1.md", "file2.md"],
      "coverage": "partial | complete | fragmented"
    }
  ],
  "overlaps": [
    {
      "topic": "Topic Name",
      "files": ["file1.md", "file2.md"],
      "description": "Both files cover X"
    }
  ],
  "gaps": [
    {
      "topic": "Topic Name",
      "description": "Missing coverage of X",
      "suggested_sources": ["file1.md mentions this"]
    }
  ],
  "suggested_canonicals": [
    {
      "target_path": "specs/feature-x.md",
      "title": "Feature X Specification",
      "source_files": ["_inbox/note1.md", "_inbox/note2.md"],
      "rationale": "Consolidate fragmented notes into spec"
    }
  ]
}

Workflow

1. Identify Vault Boundary

Locate the vault root and verify it contains Obsidian markers:

# Check for .obsidian folder (indicates vault root)
ls -la /path/to/vault/.obsidian 2>/dev/null && echo "Vault confirmed"

# List top-level structure
ls -la /path/to/vault/

2. Gather File List

Enumerate markdown files in target paths:

# List all markdown files
find /path/to/vault -name "*.md" -type f

# Count files per directory
find /path/to/vault -name "*.md" -type f | xargs -I{} dirname {} | sort | uniq -c

3. Skim Mode Analysis

For quick overview, extract:

• File names and paths
• First-level headings (# Heading)
• Frontmatter keys
• Wikilink targets

# Extract headings from a file
grep -E "^#+ " /path/to/file.md

# Extract wikilinks
grep -oE "\[\[[^\]]+\]\]" /path/to/file.md

4. Deep Mode Analysis

For thorough analysis, additionally read:

• Full file content
• All heading levels
• Paragraph content for topic extraction
• Link relationships

5. Detect Topics and Patterns

Analyze collected data to identify:

• Topics: Recurring themes across files
• Overlaps: Multiple files covering same concepts
• Gaps: Referenced but undefined concepts
• Orphans: Files with no incoming links

6. Generate Suggestions

Based on analysis, propose:

• Canonical document targets for fragmented content
• Consolidation opportunities
• Missing documentation needs

Example: Analyzing an Inbox

Input:

Path: vault/_inbox/
Mode: deep

Analysis Process:

1. List all files in _inbox/
2. Read each file's content
3. Extract topics and relationships
4. Identify consolidation opportunities

Output:

{
  "vault_path": "vault",
  "files_analyzed": 5,
  "mode": "deep",
  "topics": [
    {
      "name": "Authentication",
      "files": ["_inbox/auth-notes.md", "_inbox/login-flow.md"],
      "coverage": "fragmented"
    },
    {
      "name": "Database Schema",
      "files": ["_inbox/db-thoughts.md"],
      "coverage": "partial"
    }
  ],
  "overlaps": [
    {
      "topic": "Authentication",
      "files": ["_inbox/auth-notes.md", "_inbox/login-flow.md"],
      "description": "Both cover OAuth flow with different details"
    }
  ],
  "gaps": [
    {
      "topic": "Error Handling",
      "description": "Referenced in auth notes but no dedicated coverage",
      "suggested_sources": ["_inbox/auth-notes.md line 42"]
    }
  ],
  "suggested_canonicals": [
    {
      "target_path": "specs/authentication.md",
      "title": "Authentication Specification",
      "source_files": ["_inbox/auth-notes.md", "_inbox/login-flow.md"],
      "rationale": "Consolidate fragmented auth documentation"
    }
  ]
}

Policies

Always

• Operate in read-only mode - never modify files
• Respect vault boundaries - only analyze specified paths
• Report uncertainty when topics are ambiguous
• Include source file references for all findings
• Use relative paths from vault root in output

Never

• Modify, move, or delete any files
• Access files outside the specified vault/paths
• Make assumptions about file organization intent
• Infer meaning where content is genuinely ambiguous

Handling Ambiguity

When encountering unclear content:

1. Flag the item as uncertain
2. Include the raw excerpt for human review
3. Suggest multiple possible interpretations if applicable
4. Do not force a single interpretation

Integration

This skill works with:

• obsidian-extract-inbox - Use read context to inform extraction
• obsidian-write-document - Suggested canonicals inform document creation
• obsidian-issue-from-doc - Topics inform issue generation

Output Format

When run, report:

1. Summary statistics (files analyzed, mode used)
2. The structured JSON analysis
3. Key findings highlighted for human review
4. Recommended next steps (which skills to invoke next)