Maintaining consistent YAML frontmatter in brain pages is important for system reliability. Errors in frontmatter can lead to indexing issues or broken page displays, impacting how information is processed and retrieved. To address this, Omni Apps introduces frontmatter-guard, an AI agent skill designed to validate and auto-repair YAML frontmatter before pages enter the system. This tool helps ensure the structural integrity of your brain's content, making it a valuable addition for anyone managing extensive documentation or knowledge bases.
What frontmatter-guard Does
The frontmatter-guard skill focuses on catching eight specific classes of mechanical errors within YAML frontmatter. These include important issues like missing delimiters, which can prevent a parser from recognizing the frontmatter block at all, and malformed YAML syntax that would otherwise cause processing failures. It also identifies null bytes, which can lead to unexpected data corruption or parsing errors, and slug mismatches that might break internal linking or URL generation. Quote-nesting issues, a common source of syntax errors in complex YAML structures, are also detected and addressed. The tool performs structural validation only; it does not engage in citation auditing or content review, focusing purely on the parsability and correctness of the YAML itself.
How it Operates
The frontmatter-guard operates through a defined four-phase process to manage frontmatter integrity. It begins with an audit phase, which performs a read-only scan of the frontmatter to identify potential issues without making any changes. This is followed by a validate phase, which conducts a single-path check to confirm the frontmatter's adherence to YAML specifications. If errors are detected and a repair is desired, the fix phase initiates auto-repair. During this phase, the tool always writes .bak backups of the original files first before attempting any modifications, ensuring data recovery is possible. Optionally, the skill can install a pre-commit hook, integrating its checks directly into your version control workflow. Underlying these operations, the skill runs a frontmatter CLI command, enabling agent-driven workflows to automate these validation and repair tasks.
For example, to check a specific brain page, you might issue the command frontmatter audit my-brain-page.md. If this audit reveals errors, a subsequent command like fix frontmatter my-brain-page.md would attempt repairs, always creating backups before any changes are made. This ensures that while the system works to maintain data quality, your original content remains protected.
Triggering and Limitations
To engage the frontmatter-guard skill, you can use several intuitive triggers. These include 'validate frontmatter', 'check frontmatter', 'fix frontmatter', 'frontmatter audit', and 'brain lint'. These commands allow you to initiate a scan, validation, or repair process as needed. It is important to note the specific limitations of this tool. While it effectively handles many mechanical errors, it will not attempt to fix pages with missing opening delimiters or empty frontmatter blocks without human input. Such cases usually indicate incomplete authoring or intentional omissions rather than simple mechanical errors, requiring an author's review rather than an automated repair. The tool is designed to be an exec type, meaning it can make changes to files, but always with the safety net of backups.
FAQ
Q: What types of errors does frontmatter-guard primarily fix?
A: It fixes mechanical YAML errors such as malformed syntax, null bytes, slug mismatches, and quote-nesting issues within the frontmatter.
Q: Will this tool review my content or citations? A: No, it focuses solely on the structural integrity and syntax of the YAML frontmatter. Content review or citation auditing is outside its scope.
Q: Can it repair a page if the opening --- delimiter is missing?
A: No, if a page is missing its opening delimiter or has an empty frontmatter block, the tool assumes incomplete authoring and requires human input before any fixes are attempted.
The frontmatter-guard skill provides a reliable way to manage the consistency and parsability of your brain page frontmatter. Integrating it into your workflow helps reduce manual debugging of common structural issues, ensuring your data remains consistently formatted and accessible.
