vault-schema

Validate and migrate Obsidian vault frontmatter against a YAML note-type schema.

2|Updated Apr 4, 2026
One-click install
npx skills add https://github.com/DoctorMozg/claude-pipelines --skill vault-schema-doctormozg
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vault-schema
Source: https://github.com/DoctorMozg/claude-pipelines/tree/main/plugins/mz-knowledge/skills/vault-schema
Command: npx skills add https://github.com/DoctorMozg/claude-pipelines --skill vault-schema-doctormozg

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Obsidian vaults accumulate notes with inconsistent frontmatter over time, and enforcing a schema across hundreds of notes by hand is error-prone and irreversible without backups. This Skill validates every note's frontmatter against a declared YAML schema and runs approval-gated migrations with a rollback manifest written before any change. ## Core Features & Use Cases - Schema Validation: Dispatches a validator agent to check every note against declared note_types, producing severity-labeled findings (Critical for missing required fields or enum violations, Nit for unknown keys). - Approval-Gated Migration: Converts Critical findings into a per-note migration plan with user-filled placeholders, writes a rollback manifest with content hashes before any write, and patches frontmatter only after explicit approval. - Schema Bootstrapping: When no schema exists at .mz/vault-schema.yml, presents a starter template with permanent, fleeting, and research note types for the user to accept, edit, or reject. - Use Case: After adding a required status field to your permanent notes schema, run migrate mode to backfill the field across all existing notes, reviewing each proposed patch and keeping a rollback manifest for recovery. ## Quick Start Ask the AI to validate your Obsidian vault's frontmatter against the schema at .mz/vault-schema.yml, or to run a schema migration with rollback protection.

Frequently Asked Questions about vault-schema

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate Obsidian frontmatter against a schema?

Run the skill in validate mode with your vault path. It reads the schema at .mz/vault-schema.yml, checks every markdown note's frontmatter against its declared note_type, and writes a report with Critical findings for missing required fields or enum violations and Nit findings for unknown keys.

How do I migrate vault notes to a new frontmatter schema?

Run the skill in migrate mode after a validation pass. It converts Critical findings into a per-note migration plan, writes a rollback manifest with original frontmatter and content hashes before any change, and applies patches only after you approve the plan and fill in all placeholder values.

What happens if the vault schema file does not exist?

The skill presents a bootstrap template via an interactive prompt with options to accept, edit, or abort. The template declares permanent, fleeting, and research note types. It never fabricates a schema or validates against invented defaults.

Can I undo a frontmatter migration if something goes wrong?

Yes. A rollback manifest capturing each note's original frontmatter and a content hash is written to disk before any patch is applied. If a run halts mid-batch, you restore notes by pasting the original frontmatter from the manifest back into each file.

What are the limitations of the vault schema DSL?

The v1 DSL supports only required fields, optional fields, and allowed_values enums for string fields. It does not support cross-field constraints, regex patterns, type coercion, inheritance between note types, or list-element enumeration such as constraining individual tag values.

Why are some notes skipped during frontmatter validation?

Notes are skipped when their type field is missing or when their type is not declared in the schema's note_types map. This pass-through behavior is intentional so unknown types do not block validation while the schema is under construction.