inbrainfun/inbrain/frontmatter-guard
Claude Code and agent skill by inbrainfun/inbrain
- community
- ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]
Checking that the SKILL.md file is still in the repository.
Validate and auto-repair YAML frontmatter on brain pages. Catches malformed pages before they enter the brain (missing closing ---, nested quotes, slug mismatches, null bytes, empty frontmatter, YAML parse failures). Wraps the `inbrain frontmatter` CLI for agent-driven workflows.
Install
npx vskill@latest install inbrainfun/inbrain/frontmatter-guardSemi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard
SKILL.md
The same SKILL.md was published earlier as inbrainfun/inbrain/frontmatter-guard.
Frontmatter Guard Skill
Convention: seeskills/conventions/quality.mdfor citation rules; this skill is structural validation, not citation auditing.
Contract
This skill guarantees:
- Every brain page is scanned against the eight canonical frontmatter validation classes
- Mechanical errors (nested quotes, missing closing
---, null bytes, slug mismatch) are auto-repairable on demand with.bakbackups - Validation logic is shared with
inbrain doctor'sfrontmatter_integritysubcheck — single source of truth - Reports per source (inbrain is multi-source since v0.18.0); never silently audits the wrong root
Why This Exists
Brain pages pile up over months. Agents write them with malformed frontmatter:
- Missing closing
---(entity detector bugs) - Unstructured YAML in meeting pages (ingestion bugs)
- Slug mismatches (path renames not propagated)
- Null bytes (binary corruption from copy-paste accidents)
- Nested double quotes in titles (
title: "Phil "Nick" Last")
Without a guard, these accumulate silently until inbrain sync chokes or search returns garbage. The guard makes the failure visible at audit time and trivially fixable.
Validation classes
| Code | Meaning | Auto-fixable? | |
|---|---|---|---|
MISSING_OPEN | File doesn't start with --- | No (needs human) | |
MISSING_CLOSE | No closing --- before first heading | Yes | |
YAML_PARSE | YAML failed to parse | Sometimes (depends on cause) | |
SLUG_MISMATCH | Frontmatter slug: differs from path-derived slug | Yes (removes the field) | |
NULL_BYTES | Binary corruption (\x00) | Yes | |
NESTED_QUOTES | title: "outer "inner" outer" shape | Yes | |
NON_STRING_FIELD | title/type/slug is an unquoted non-string scalar (e.g. title: 123, slug: 2024-06-01) | No (quote the value) | |
EMPTY_FRONTMATTER | Open + close present but nothing between | No (needs human) |
Phases
Phase 1: Audit
Run a read-only scan across all registered sources (or one with --source <id>).
Reports:
- Per-source counts grouped by error code
- Sample of up to 20 affected pages per source
- Total count
- Scan timestamp
Output is JSON; agents parse errors_by_code and per_source to decide next steps.
Phase 2: Validate one path
Validate a single file or directory (does not require source registration):
Exit code 0 = clean; 1 = errors found. Use this in CI pipelines or pre-commit hooks.
Phase 3: Fix
When issues are found:
--fix writes <file>.bak for every modified file before mutating. The backup is the safety contract — works whether the brain is a git repo or a plain directory.
--dry-run previews without writing. Use this before applying fixes in batch.
Phase 4: Pre-commit hook (optional)
For brain repos that ARE git repos, install the pre-commit hook to block malformed pages from being committed in the first place:
The hook runs inbrain frontmatter validate against staged .md/.mdx files. Bypass with git commit --no-verify.
Trigger words
When the user says any of these, route here:
- "validate frontmatter"
- "check frontmatter"
- "fix frontmatter"
- "frontmatter audit"
- "brain lint"
Output rules
- Always run
inbrain frontmatter audit --jsonfirst; never assume a brain is clean. - Surface counts to the user in plain language; do not dump raw JSON.
- For
--fixoperations: state how many files will be modified BEFORE running, then confirm. SLUG_MISMATCHfixes remove the frontmatterslug:field — inbrain derives slug from path. Mention this when the user's title is intentionally renamed.- Never auto-fix
MISSING_OPENorEMPTY_FRONTMATTERwithout explicit user input — these usually mean a human author started a page and didn't finish.
Chains with
inbrain doctor— thefrontmatter_integritysubcheck reports the same counts asaudit.skills/maintain/SKILL.md— broader brain health audit; chain after this skill if other classes of issue are suspected.skills/lint/SKILL.md(viainbrain lint) — overlapping rules for skill-file lint; thefrontmatter-*rule names in lint output come from this skill's validation surface.
Output Format
Audit summary (terse, agent-friendly):
JSON envelope (when --json is passed):
inbrain frontmatter validate <path> --json returns a similar envelope keyed on per-file results instead of per-source.
Prevention — Writing Valid Frontmatter
This is the most important section. Fixing broken frontmatter is good. Not writing broken frontmatter in the first place is better.
YAML arrays (the historical #1 error source)
Why this used to break: before v0.37.5.0, the validator counted unescaped " characters and flagged any line with 3+. A flow sequence like tags: ["yc", "w2025"] has 4 unescaped " by design — it's valid YAML, but the dumb counter flagged it anyway. One brain saw 6,981 of these on a single doctor run. v0.37.5.0 parses suspicious values with js-yaml.safeLoad before flagging, so JSON-style arrays no longer trigger NESTED_QUOTES.
Why you should still write the canonical form: the auto-fix engine (inbrain frontmatter validate --fix) and the inferred-frontmatter serializer both emit single-quoted YAML for tags: / aliases:. Writing the canonical form in new content keeps the source files stylistically consistent and makes diffs against --fix runs empty.
The classic LLM trap: code like tags: [${items.map(t => JSON.stringify(t)).join(', ')}] produces tags: ["yc", "w2025"]. Use single quotes with an apostrophe fallback: tags: [${items.map(t => t.includes("'") ? JSON.stringify(t) : "'" + t + "'").join(', ')}]. Or use a YAML library that knows how to emit canonical YAML.
Quoted scalars
When to quote at all
- Unquoted is fine for simple values:
type: person,batch: w2025 - Quote when the value contains
: " ' # [ ] { } | > & * ! ? ,or starts with@ - Single quotes are the default safe choice
- Double quotes only when the value itself contains apostrophes
Anti-Patterns
Don't auto-fix `MISSING_OPEN` or `EMPTY_FRONTMATTER` without user input. These usually mean a human author started a page and didn't finish — silently inserting --- markers around an unfinished draft is wrong.
Don't use `--fix` to "make doctor green" without reading the audit first. SLUG_MISMATCH cases are surfaced for manual review specifically because inbrain derives the slug from path. A mismatch usually means the user renamed a file intentionally; auto-removing the slug field is the right outcome only when you've confirmed the rename was deliberate.
Don't skip the `.bak` backups. The .bak is the safety contract for non-git brain repos. If .bak files accumulate after a fix run, that's a feature, not a bug — the user can review the diffs and delete the backups when satisfied.
Don't run `audit` on a brain where sources aren't registered. The CLI returns "no registered sources to audit" gracefully, but the migration emits a skipped: no_sources phase result. Don't paper over this with a manual path-walk; the right fix is to register the source via inbrain sources add.
Don't install the pre-commit hook on non-git brain dirs. The install-hook command skips them automatically with a one-line note. If you see "skipped — not a git repo" and want validation at write time anyway, use the audit command on a cron schedule.
Security
- Security scanPassed, 96 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/frontmatter-guard/SKILL.md
Popularity
- Repository stars
- 143
- Repository forks
- 126
- 7-day trend score
- 25
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Extension points
hookPre/post lifecycle hooks
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/inbrainfun/inbrain/frontmatter-guard)