frontmatter-guard

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 `gbrain frontmatter` CLI for agent-driven workflows.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/frontmatter-guard/SKILL.md

Quality

Content

68%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with executable commands and concrete examples, and well-structured, but it carries noticeable narrative padding with version-specific history and lacks an explicit post-fix verification loop for a batch mutating operation.

Suggestions

Trim the 'Why This Exists' and 'Why this used to break' narratives (including the 6,981-error anecdote) to a line or two, or move version history (v0.18.0, v0.37.5.0) into a 'Deprecated/old behavior' section to recover conciseness.

Add an explicit post-fix verification step to the Fix phase (e.g. 'After --fix, re-run gbrain frontmatter audit --json and confirm total == 0') so the batch mutating workflow has a complete validate→fix→re-validate feedback loop.

Consider moving the 'Prevention — Writing Valid Frontmatter' YAML reference and the full JSON output envelope into a references/ file linked from the body, to deepen progressive disclosure for the longer sections.

Dimension	Reasoning	Score
Conciseness	The operational core (validation table, commands, output rules, YAML examples) is efficient, but narrative padding ('Why This Exists', 'Why this used to break' with the 6,981-error anecdote) and time-sensitive version numbers (v0.18.0, v0.37.5.0) outside any deprecated section add unnecessary explanation, matching the mostly-efficient-but-could-tighten score-3 anchor.	3 / 5
Actionability	Provides copy-paste-ready commands for every phase (audit, validate, --fix, install-hook), concrete JSON envelopes, exit-code semantics, and correct/broken YAML pairs — fully executable guidance covering the common cases per the score-5 anchor.	5 / 5
Workflow Clarity	Phases 1–4 are clearly sequenced with pre-mutation safety (--dry-run, .bak backups, confirm-count-before-fix), but this is a batch mutating operation and there is no explicit post-fix re-audit/verification feedback loop, so per the batch-operation cap workflow clarity stays at 3.	3 / 5
Progressive Disclosure	Well-organized into clearly headed sections with chain references to other skills signaled by path; no bundle files exist so everything is inline, and the 230-line body could arguably split the YAML-prevention reference or output-format spec into separate files, giving good-but-minor-gaps structure matching the score-4 anchor.	4 / 5
	Total	15 / 20 Passed

Description

75%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, actionable, and clearly niched, but it lacks an explicit 'Use when...' trigger clause, which caps completeness. Trigger-term coverage is good rather than exhaustive because synonyms live in the separate triggers field rather than the description.

Suggestions

Add an explicit 'Use when...' clause to the description (e.g. 'Use when auditing brain pages for malformed frontmatter, or before running gbrain sync') to lift completeness above 3.

Fold one or two natural trigger synonyms (e.g. 'frontmatter audit', 'brain lint') into the description body itself so trigger-term coverage does not depend on the separate triggers field.

Dimension	Reasoning	Score
Specificity	Lists concrete actions ('Validate and auto-repair YAML frontmatter', 'Catches malformed pages') and enumerates six specific defect classes (missing closing ---, nested quotes, slug mismatches, null bytes, empty frontmatter, YAML parse failures) plus the wrapped CLI — comprehensive coverage matching the score-5 anchor.	5 / 5
Completeness	The 'what' is explicit and detailed, but there is no 'Use when...' clause or equivalent explicit trigger guidance in the description; 'Catches malformed pages before they enter the brain' only weakly implies when, so per the missing-trigger-guidance rule completeness is capped at 3.	3 / 5
Trigger Term Quality	Contains natural terms a user would say ('frontmatter', 'validate', 'auto-repair', 'YAML', 'brain pages') but stops short of the full synonym/extension coverage (e.g. no '.md', no 'lint'/'audit' synonyms inside the description itself — those live only in the separate triggers field), landing just below the comprehensive score-5 anchor.	4 / 5
Distinctiveness Conflict Risk	Tied to a narrow niche ('YAML frontmatter on brain pages' via the 'gbrain frontmatter' CLI) with distinct triggers, giving minimal overlap with other skills — a clear match for the score-5 anchor.	5 / 5
	Total	17 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: garrytan/gbrain
Path: skills/frontmatter-guard/SKILL.md
Commit: 7b7921d

Reviewed: ~12 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.