skills.rest
tapway
tapwayOFFICIAL
Explore all skills by this author →
WebsiteGitHub

gbrain-frontmatter-guard

Validates YAML frontmatter and scans markdown files for null bytes before brain writes.

1|Updated Jun 21, 2026
Search Tags:#markdown#validation#yaml#frontmatter#gbrain#null bytes#pre-write hook
One-click install
npx skills add https://github.com/tapway/shogun-os --skill gbrain-frontmatter-guard-tapway
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gbrain-frontmatter-guard
Source: https://github.com/tapway/shogun-os/tree/main/skills/gbrain/frontmatter-guard
Command: npx skills add https://github.com/tapway/shogun-os --skill gbrain-frontmatter-guard-tapway

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) components.

What problem does it solve? Corrupted YAML frontmatter silently breaks search, rendering, and embedding in a gbrain knowledge base, and null bytes in imported markdown corrupt git diffs and truncate content. This Skill gates every brain write with validation so malformed pages never reach the database. ## Core Features & Use Cases - Pre-Write Validation Gate: Checks YAML parsability, required fields per page type, tag structure, ISO date formats, slug hygiene, and duplicate keys before any mcp_gbrain_put_page call. - Null-Byte Scanner: A bundled Python script scans markdown files for null bytes, with git-tracked-only mode, in-place fixing, JSON output, and CI-friendly exit codes. - Use Case: When importing an external markdown repository into the brain, run the scanner with --git-only --fix to strip null bytes, then validate each page's frontmatter against the required-fields table before writing. ## Quick Start Ask the agent to validate the frontmatter of a markdown page against the required-fields rules before writing it to the brain with mcp_gbrain_put_page.

Frequently Asked Questions about gbrain-frontmatter-guard

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

FAQPage Schema
How do I validate YAML frontmatter before writing markdown pages?▼

Parse the frontmatter with Python's yaml.safe_load, then check required fields per page type, tag list structure, ISO date format, and slug hygiene. If any rule fails, fix the content before calling mcp_gbrain_put_page.

How do I find and remove null bytes in markdown files?▼

Run the scan_null_bytes.py script with --path pointing at your repo and --fix to strip null bytes in place. Add --git-only to scan only git-tracked files and --json for programmatic output.

What required fields does each gbrain page type need?▼

Every page needs title, type, and tags; idea, decision, conversation, weekly, and daily pages also require a date, and reference pages require a source. Valid types include person, company, project, idea, reference, decision, conversation, weekly, daily, concept, and note.

Can I use the null-byte scanner in a CI or pre-commit hook?▼

Yes, the script exits with code 0 when clean and 1 when null bytes are found without --fix, making it safe for CI pipelines and pre-commit hooks. Use --json for machine-readable results.

When should I not run frontmatter validation?▼

Validation is write-time only, so skip it when reading existing pages or handling non-YAML content. Pages already checked by a post-write brain-compliance pass do not need re-validation.

Related Skills

Explore More Software Engineering Skills→
PostergullyPostergully

frontmatter-guard

Validate and repair YAML frontmatter on brain pages with .bak backups.

Community
Advanced
garrytangarrytan
29.4k

brain-ingest-gate

Validates named-entity resolution and semantic dedup before writing pages into a gbrain knowledge base.

Community
Advanced
sixtycat2000-ctrlsixtycat2000-ctrl

maintain

Automate health checks and maintenance on a digital brain dataset.

Community
Advanced
werfwerf
4.7k

test-the-tests

Validates tests by applying real code mutations and confirming they fail as expected.

Official
Intermediate