Frontmatter Guard
Use this skill when the user asks to validate frontmatter, fix frontmatter, run a brain lint, or check local brain page structure.
Workflow
- Start read-only:
- inspect representative brain pages
- run
python3 scripts/brain_doctor.py if available
- if the upstream
gbrain CLI exists, prefer read-only gbrain frontmatter audit --json
- Classify issues:
- missing opening or closing
---
- YAML parse errors
- empty frontmatter
- slug/path mismatch
- null bytes or non-text content in markdown files
- missing citation or source fields when local conventions require them
- For mechanical fixes, show the intended file list before writing.
- For ambiguous fixes, ask for the intended title, type, or source instead of guessing.
- Re-run the audit after fixes.
Validation Classes
- file framing: opening and closing delimiters, UTF-8 text, and no null bytes
- YAML syntax: valid mappings, arrays, quoted scalars, and parseable dates
- schema: required fields, supported page type, and expected value shapes
- identity: slug, title, and path agreement
- provenance: source and citation fields required by the local page convention
Support four explicit modes: whole-corpus audit, single-path validation, scoped mechanical repair, and optional pre-commit validation. Quote scalar values when they contain YAML-significant punctuation, and prefer real YAML arrays over comma-packed strings.
Guardrails
- Do not auto-fix user-authored pages without a before/after plan.
- Do not remove citations while normalizing frontmatter.
- Do not treat citation repair as the same job; use
citation-fixer for citation semantics.
- Never install a pre-commit hook without explicit user authorization.
1---2name: frontmatter-guard3description: Audit and repair local brain page frontmatter before malformed pages break search, ingest, or future sync.4---56# Frontmatter Guard78Use this skill when the user asks to validate frontmatter, fix frontmatter, run a brain lint, or check local brain page structure.910## Workflow11121. Start read-only:13 - inspect representative brain pages14 - run `python3 scripts/brain_doctor.py` if available15 - if the upstream `gbrain` CLI exists, prefer read-only `gbrain frontmatter audit --json`162. Classify issues:17 - missing opening or closing `---`18 - YAML parse errors19 - empty frontmatter20 - slug/path mismatch21 - null bytes or non-text content in markdown files22 - missing citation or source fields when local conventions require them233. For mechanical fixes, show the intended file list before writing.244. For ambiguous fixes, ask for the intended title, type, or source instead of guessing.255. Re-run the audit after fixes.2627## Validation Classes2829- file framing: opening and closing delimiters, UTF-8 text, and no null bytes30- YAML syntax: valid mappings, arrays, quoted scalars, and parseable dates31- schema: required fields, supported page type, and expected value shapes32- identity: slug, title, and path agreement33- provenance: source and citation fields required by the local page convention3435Support four explicit modes: whole-corpus audit, single-path validation, scoped mechanical repair, and optional pre-commit validation. Quote scalar values when they contain YAML-significant punctuation, and prefer real YAML arrays over comma-packed strings.3637## Guardrails3839- Do not auto-fix user-authored pages without a before/after plan.40- Do not remove citations while normalizing frontmatter.41- Do not treat citation repair as the same job; use `citation-fixer` for citation semantics.42- Never install a pre-commit hook without explicit user authorization.
mphaxise