Obsidian Vault Analyzer

Overview

Analyzes Obsidian vaults comprehensively and proposes actionable improvements for organization, performance, and plugin configuration. Performs multi-dimensional analysis including file structure, graph connectivity, metadata consistency, and performance bottlenecks.

When to Use

Activate this skill when the user requests:

• Vault analysis or health check
• Performance optimization
• Organization improvements
• Investigation of broken links or orphans
• Metadata/tag audit
• Plugin configuration review
• Structure reorganization

Analysis Workflow

Step 1: Identify Vault Location

First, determine the vault path. The vault is typically:

• Current working directory (if it contains .obsidian folder)
• User-specified path
• Common Obsidian location (iCloud, Dropbox, etc.)

Check for .obsidian folder to confirm vault root:

ls -la | grep .obsidian

Step 2: Structure Analysis

Run structure analysis script:

python3 scripts/analyze_structure.py <vault_path>

What it analyzes:

• Total markdown files and folders
• Folder depth distribution
• File naming patterns (camelCase, snake_case, kebab-case, spaces)
• Folder sizes (identifies overloaded folders)
• Empty folders
• Long filenames (>50 chars)

Common recommendations:

• Standardize naming convention (prefer kebab-case)
• Flatten deep nesting (>6 levels)
• Split overloaded folders (>50 files)
• Remove empty folders

Step 3: Graph Analysis

Run graph analysis script:

python3 scripts/analyze_graph.py <vault_path>

What it analyzes:

• Total links and connected files
• Broken links (pointing to non-existent files)
• Orphaned files (no incoming links)
• Most connected files (hub notes)

Common recommendations:

• Fix broken links
• Create index files for orphans
• Improve connectivity if low link density

Step 4: Performance Check

Run performance analysis:

python3 scripts/check_performance.py <vault_path>

What it analyzes:

• Large files (>100KB markdown, >5MB attachments)
• Attachment count and total size
• Community plugins count
• Workspace file sizes

Common recommendations:

• Split large markdown files
• Optimize or externalize large attachments
• Disable unused plugins
• Close unused workspace panes

Step 5: Metadata Analysis

Run metadata analysis:

python3 scripts/analyze_metadata.py <vault_path>

What it analyzes:

• Frontmatter coverage percentage
• YAML errors in frontmatter
• Tag usage and common tags
• Frontmatter properties usage
• Similar tags (case variations, plurals)

Common recommendations:

• Add frontmatter to improve searchability
• Fix YAML errors
• Standardize tags
• Use standard properties (date, status, category)

Step 6: Content Analysis (Requires Authorization)

IMPORTANT: Before analyzing actual content of notes, ask the user:

"Para completar a análise, posso examinar o conteúdo das suas notas para identificar padrões de escrita, qualidade, e possíveis melhorias. Isso envolve ler o texto das notas. Você autoriza essa análise?"

Only proceed with content analysis if user explicitly agrees.

Content analysis includes:

• Writing pattern analysis
• Note quality assessment
• Template usage
• Duplicate content detection

Step 7: Generate Comprehensive Report

After all analyses are complete, generate a comprehensive report with:

1. Executive Summary

   • Overall vault health score
   • Key findings
   • Priority actions

2. Detailed Findings by Category

   • Structure issues
   • Graph issues
   • Performance issues
   • Metadata issues

3. Prioritized Recommendations

   • High priority (broken links, critical performance)
   • Medium priority (organization, metadata)
   • Low priority (optimizations)

4. Implementation Guide

   • Step-by-step actions
   • Tools to use
   • Expected outcomes

References

obsidian-api.md

Obsidian API reference for vault operations. Use when:

• Understanding file access patterns
• Learning best practices for performance
• Implementing custom analysis

best-practices.md

Vault organization best practices. Use when:

• Proposing structural changes
• Recommending naming conventions
• Suggesting maintenance routines

plugins-reference.md

Essential plugins and configurations. Use when:

• Recommending plugins for specific needs
• Optimizing plugin configuration
• Troubleshooting plugin conflicts

Important Considerations

Performance on Large Vaults

For vaults with >1000 files:

• Scripts may take several minutes to run
• Consider analyzing specific folders first
• Use progress indicators for long operations

Privacy and Content Access

• Never share vault content externally
• Ask before reading note content
• Respect .obsidian folder (already excluded)

Customization

Scripts can be modified for:

• Specific folder structures
• Custom naming patterns
• Additional metrics
• Vault-specific requirements

Example Output

═══════════════════════════════════════════════════════════════
OBSIDIAN VAULT ANALYSIS REPORT
═══════════════════════════════════════════════════════════════

📊 VAULT OVERVIEW
   Total Files: 847
   Total Folders: 42
   Total Links: 3,245
   Frontmatter Coverage: 34.2%

✅ GOOD
   - Consistent kebab-case naming (92%)
   - Reasonable folder depth (max 4 levels)
   - Good tag usage (67% of files)

⚠️  NEEDS ATTENTION
   - 127 broken links
   - 23 orphaned files
   - 15 large markdown files (>100KB)
   - Low frontmatter coverage

📋 PRIORITY RECOMMENDATIONS
   1. Fix broken links (high priority)
   2. Add frontmatter to improve searchability
   3. Split large files for better performance
   4. Create index files for orphaned notes

═══════════════════════════════════════════════════════════════

Troubleshooting

Script Execution Issues

If scripts fail:

1. Check Python 3 is installed: python3 --version
2. Verify vault path is correct
3. Check file permissions
4. Look for specific error messages

Missing Dependencies

Scripts require:

• pyyaml for frontmatter parsing

Install with:

pip3 install pyyaml

Large Vault Performance

For very large vaults (>10,000 files):

• Run analyses separately (structure, graph, performance, metadata)
• Analyze specific folders first
• Consider increasing script timeouts