frontmatter-guard

Validate and auto-repair YAML frontmatter on brain pages.

1|Updated May 9, 2026
One-click install
npx skills add https://github.com/weiping/gbrain-cn --skill frontmatter-guard
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: frontmatter-guard
Source: https://github.com/weiping/gbrain-cn/tree/main/skills/frontmatter-guard
Command: npx skills add https://github.com/weiping/gbrain-cn --skill frontmatter-guard

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents malformed YAML frontmatter from breaking ingestion, audit, search, and downstream brain operations by validating and (when safe) repairing common structural and data issues before pages enter the system.

Core Features & Use Cases

  • Frontmatter validation across canonical classes: Detects missing delimiters, YAML parse failures, slug mismatches, null bytes, nested-quote title issues, and empty frontmatter.
  • Audit and targeted validation: Runs multi-source audits with per-source counts and samples, or validates a specific file/directory for CI and pre-commit workflows.
  • Safe auto-repair with backups: Applies fix mode with .bak backups for auto-fixable issues while avoiding risky repairs for cases that typically need human review.

Quick Start

Ask your agent to run a frontmatter audit and return JSON counts of any issues it finds across the brain.

Frequently Asked Questions about frontmatter-guard

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

FAQPage Schema
How do I validate YAML frontmatter in CI to prevent broken brain pages?

YAML frontmatter validation in CI runs targeted per-path checks to catch missing delimiters, slug mismatches, and parse failures before malformed documents enter ingestion. It outputs machine-readable JSON for automated pipeline integration.

What causes malformed YAML frontmatter to break search and ingestion pipelines?

Malformed YAML frontmatter breaks pipelines through missing delimiters, YAML parse failures, null bytes, nested-quote title issues, and empty frontmatter blocks that disrupt downstream document parsing and indexing operations.

Can I auto-repair broken frontmatter without losing original data?

Auto-repairing broken frontmatter applies fix mode with .bak backups for safe structural corrections, while leaving risky cases that require human review untouched to prevent data loss during validation.

How do I audit a full collection for frontmatter consistency issues?

Full-collection frontmatter auditing runs multi-source scans with per-source counts and sample outputs, identifying slug consistency errors and structural issues across the entire brain page dataset.

Does frontmatter validation support machine-readable JSON output for automation?

Frontmatter validation supports machine-readable JSON output, enabling automated processing of audit results and per-source issue counts for integration into CI linting and pre-commit workflows.

What are the limitations of auto-repairing YAML frontmatter on brain pages?

Auto-repairing YAML frontmatter is limited to safe, common structural fixes, deliberately avoiding risky repairs for complex cases like nested-quote title issues that typically require human review.