Guide · Agent skill

How to use the Frontmatter Guard agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Frontmatter Guard is an agent skill for gbrain, a knowledge store made of Markdown pages that each start with a YAML metadata block between --- lines. It teaches an agent to check those headers, explain why sync held a file back, and preview repairs before changing anything. This guide covers what the skill does, how to install it, how to ask for it in plain language, and the safety limits you should respect.

Frontmatter Guardgarrytan/gbrain · MIT Download the skill

Quick start

1Download the ZIP. Download the frontmatter-guard ZIP from the skill page on this site.
2Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder.
3Or upload in the Claude apps. Alternatively, upload the skill under Settings → Capabilities → Skills.
4Confirm gbrain is ready. Make sure the gbrain CLI is installed and that your sources are registered.
5Ask in plain language. Request something like "check frontmatter" or "frontmatter audit" so the agent uses the skill.
6Review previews. Look at the diff the skill shows before approving any apply.

What is an agent skill?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to handle a specific kind of task. When the skill is available, the agent can use it when a request matches the skill's triggers, following the steps and commands written in the file.

Frontmatter Guard is one such skill. Its SKILL.md declares the exec tool, which means the agent runs shell commands to call the gbrain CLI.

What the skill makes the agent do

The skill validates the YAML frontmatter on brain pages and catches malformed pages before they enter the brain. It checks for eight validation classes, including missing closing --- markers, nested quotes in titles, slug mismatches, null bytes, empty frontmatter and YAML parse failures.

It also explains files that sync holds instead of importing. For each hold, the agent reads the reason and the line involved, then works toward a fix. Repairs are previewed first, and changes are applied only after the user approves the exact diff. Backups are kept as .bak files or under ~/.gbrain/backups/frontmatter/.

Audit all registered sources, or one source, for frontmatter errors
Validate a single file or directory
Explain held files from their hold record
Preview and, with approval, apply fixes

Install the skill

Download the ZIP from the skill page on this site and unzip it. The skill is a single file, SKILL.md, so the unzipped folder should contain that file.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/
Project: .claude/skills/ inside your project
Claude apps: Settings → Capabilities → Skills

Check the requirements

The skill assumes the gbrain CLI is installed and configured with registered sources. Its commands will not work on a generic Markdown folder without gbrain. The agent runtime must also be able to run shell commands through the exec tool.

gbrain CLI installed and configured with registered sources
An agent runtime that can execute shell commands (exec tool)

How to trigger the skill with natural requests

Ask in plain language. The skill's triggers include phrases such as "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint", "held files" and "sync held a file". Requests that mention these ideas should lead the agent to the skill.

"Run a frontmatter audit on my brain."
"Check frontmatter on notes/2026-10-04-digest.md before I import it."
"Sync held a file. Why, and what do I need to fix?"
"Fix frontmatter on the held pages, but show me the diff first."

Example workflows

For an audit, the agent runs a read-only scan across all registered sources and reports counts grouped by error code. To validate one file, it runs a validate command on that path. To fix held files, the skill's documented flow starts with a status check, then a safe preview, then a broader preview if needed, and only then an apply that is bound to a previewed hash.

The skill's guidance is that every --apply rewrites the user's files, so the agent should ask before applying.

gbrain frontmatter audit --json
gbrain frontmatter validate <path> --json
gbrain frontmatter validate <path> --fix

Safety notes: scripts and network

The skill runs scripts: yes. It executes gbrain commands through the exec tool, and --apply and --fix modify files on disk. It does not use the network.

Automated bulk repair is risky. Applying repairs rewrites files, and the skill requires explicit approval for each apply, so review changes before any automation runs. The skill also says never to write access or identity keys such as visibility, slug, type, id or source_id from untrusted text.

Runs scripts: yes, via the gbrain CLI and exec tool
Uses network: no
Every apply needs your approval; review the diff first
Do not let agents write visibility, derived_from, slug, type, id or source_id from untrusted text

Tips for reliable results

Write pages with a YAML serializer or through gbrain's own put_page and capture paths, not by string interpolation. Check generated content with validate --stdin before writing it to disk.

Use --dry-run or the preview options before any fix in batch, and restage fixed files in git with git add afterward.

Prefer gbrain put or put_page over hand-built Markdown
Validate generated content with gbrain frontmatter validate --stdin before writing
Preview first; apply only the hash you reviewed
Never split a page that fits under the size limit to work around file_too_large

printf '%s' "$content" | gbrain frontmatter validate --stdin --path notes/2026-10-04-digest.md

What people use it for

Auditing a gbrain knowledge base for malformed pages after agents or scripts have written to it
Explaining why sync is holding a specific file and what line needs fixing
Validating generated Markdown in a CI pipeline or pre-commit hook using the validate command's exit codes
Previewing safe quoting fixes for titles with nested double quotes before applying them

Frequently asked questions

How do I install the frontmatter-guard skill?

Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What does the frontmatter-guard skill need to run?

It needs the gbrain CLI installed and configured with registered sources, plus an agent runtime that can run shell commands through the exec tool. Without gbrain, the commands in the skill have little use.

Is frontmatter-guard free, and what is its licence?

The item is listed under the MIT licence. The source does not state any price, so check the skill page for current terms.

Does frontmatter-guard change my files automatically?

Not without approval. The skill previews fixes first, and it requires explicit user approval of the exact changes before any apply. Applies rewrite files, and backups are kept.

Why did sync hold my file?

Sync holds a file it cannot import without guessing. Hold records include a code, reason, key, line and suggested fix. The skill reads these and explains the next step, such as a manual line fix for a YAML parse error.

Can I use frontmatter-guard without gbrain?

The skill is built around the gbrain CLI and its source registry, so it gives little value elsewhere. For generic Markdown linting, a separate tool would be a better fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Frontmatter Guard suits developers who maintain a gbrain knowledge base, especially when sync reports held files or when agents and scripts write Markdown with YAML headers. It is a poor choice if you do not run gbrain, or if you want unattended bulk repairs, since every apply rewrites files and needs your review.

Download the skill