Guide Metadata Navigator

Intelligent frontmatter and metadata navigation agent that indexes, queries, and validates YAML properties across Obsidian vaults.

When to Use This Agent

Choose this agent when you need to:

• Search and filter vault notes by complex metadata criteria across multiple frontmatter fields
• Validate that all notes conform to your vault's metadata schema requirements
• Generate metadata coverage reports showing which properties are missing or inconsistent
• Build dynamic indexes and views based on frontmatter property combinations

Consider alternatives when:

• You need to restructure the tag hierarchy itself (use Tag Agent Partner instead)
• Your goal is content quality assessment rather than metadata compliance

Quick Start

Configuration

Copy
name: guide-metadata-navigator
type: agent
category: obsidian-ops-team

Example Invocation

Copy
claude agent:invoke guide-metadata-navigator "Find all notes with status:draft that lack a 'project' field"

Example Output

=== Metadata Navigation Report ===
Query: status=draft AND project=MISSING

MATCHING NOTES: 28 of 1,103 total
  - inbox/api-rate-limiting-idea.md (created: 2025-08-14)
  - research/vector-db-comparison.md (created: 2025-09-22)
  - drafts/onboarding-flow-v2.md (created: 2025-10-01)
  ...25 more

SCHEMA VIOLATIONS: 12 notes missing required fields
  - 7 notes lack 'type' property
  - 5 notes lack 'created' date

SUGGESTED FIX: Batch-add project field using template defaults

Core Concepts

Metadata Schema Layers Overview

Aspect	Details
Required Fields	type, created, status — enforced on every note in the vault
Recommended Fields	tags, project, area — expected but not blocking on absence
Optional Fields	due, priority, source — context-dependent properties
Computed Fields	modified, word-count — auto-populated during indexing

Metadata Index Architecture

┌─────────────┐     ┌─────────────┐
│  YAML Front  │────▶│  Schema     │
│  Parser      │     │  Validator  │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Property    │────▶│  Query      │
│  Index       │     │  Engine     │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
schema_path	string	".obsidian/metadata-schema.yml"	Path to the vault metadata schema definition file
required_fields	list	["type","created","status"]	Frontmatter properties that every note must include
date_format	string	"YYYY-MM-DD"	Expected date format for validation of date properties
index_refresh	string	"on-demand"	When to rebuild the metadata index: on-demand or on-save
ignore_patterns	list	["templates/","_archive/"]	Glob patterns for files excluded from metadata validation

Best Practices

1. Define a Schema Before Scaling Your Vault Establish required and optional frontmatter fields early. Retrofitting metadata standards onto hundreds of existing notes is far more labor-intensive than enforcing schemas from the start.

2. Use Controlled Vocabularies for Key Properties Properties like status and type should draw from a fixed set of allowed values (e.g., draft, active, archived). Free-text metadata fields become inconsistent and unsearchable over time.

3. Leverage Computed Properties for Maintenance Let the agent auto-populate fields like modified and word-count during indexing passes. This keeps metadata current without requiring manual updates and enables powerful time-based queries.

4. Separate Navigation Metadata from Content Tags Frontmatter properties serve a different purpose than inline tags. Use properties for structured queries and filtering, and tags for thematic categorization and graph connections.

5. Run Validation Before Major Vault Operations Before executing bulk renames, merges, or restructuring, run a metadata validation pass. Catching schema violations beforehand prevents cascading inconsistencies in downstream reports and views.

Common Issues

1. YAML parsing errors on notes with special characters in frontmatter Wrap property values containing colons, brackets, or quotes in double quotes within the YAML block. The agent flags these parse failures but cannot auto-fix ambiguous syntax without risking data loss.

2. Index grows stale after bulk edits outside Obsidian If you edit files with external tools like VS Code or sed, the metadata index does not automatically refresh. Run the agent with --reindex to rebuild the property index from the current vault state.

3. Schema validation blocking on template files Template files intentionally use placeholder values like {{date}} that fail validation. Add your templates directory to ignore_patterns to prevent false violations from cluttering reports.