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

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

77%

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 a clear, validated workflow and clean self-contained organization; its main weakness is verbosity in the historical frontmatter-writing rationale, which pads the token budget without proportional value.

Suggestions

Compress the 'Why this used to break' and 'classic LLM trap' paragraphs into a one-line note plus the canonical single-quoted example, dropping the version-history narrative.

Consider moving the detailed 'Prevention — Writing Valid Frontmatter' guidance into a references/ file so the main body stays a lean overview while still pointing one level deep.

Dimension	Reasoning	Score
Conciseness	Most sections are tight and assume competence (validation-class table, bash commands, output envelope), but several passages are padded beyond necessity — the 'Why this used to break' historical narrative and the LLM-trap code snippet re-explain version history (v0.37.5.0, '6,981 of these') that Claude does not need, so it is mostly efficient but could be tightened.	2 / 3
Actionability	Provides copy-paste-ready commands for every phase (`gbrain frontmatter audit --json`, `validate <path> --json`, `--fix`, `--dry-run`, `install-hook`) plus concrete correct/broken YAML examples and a sample JSON envelope, matching the score-3 anchor of fully executable commands and specific examples.	3 / 3
Workflow Clarity	Phases are explicitly sequenced (Audit → Validate → Fix → Pre-commit) with validation checkpoints and feedback loops: exit codes, `--dry-run` before batch fix, state-before-modify rules, and explicit 'don't auto-fix without input' guards for destructive/batch operations, satisfying the score-3 anchor including the destructive-operations feedback-loop requirement.	3 / 3
Progressive Disclosure	No bundle files exist in references/, scripts/, or assets/, so the body is self-contained and organized into clearly labeled sections (Contract, Validation classes, Phases, Output rules, Prevention, Anti-Patterns) with no nested references; per the simple-skills note, well-organized single-file content scores 3.	3 / 3
	Total	11 / 12 Passed

Description

67%

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 and clearly scoped to a distinct niche, but it omits an explicit 'Use when...' trigger clause and natural user-facing keywords, leaving the 'when' half of completeness implied rather than stated.

Suggestions

Add an explicit 'Use when...' clause naming natural user phrases (e.g., 'Use when the user asks to validate, check, or fix frontmatter on brain pages, or mentions a brain lint / frontmatter audit').

Weave natural trigger terms ('frontmatter audit', 'brain lint', 'validate/fix frontmatter') directly into the description body rather than relying solely on the frontmatter `triggers` list.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Catches malformed pages' with a parenthetical enumeration of failure modes (missing closing ---, nested quotes, slug mismatches, null bytes, empty frontmatter, YAML parse failures) and 'Wraps the `gbrain frontmatter` CLI for agent-driven workflows', matching the score-3 anchor of multiple specific concrete actions.	3 / 3
Completeness	It clearly answers 'what' (validate/repair malformed frontmatter, lists classes) but the 'when to use it' guidance is absent from the description text itself — the judging guideline caps completeness at 2 when an explicit 'Use when...' clause or equivalent trigger guidance is missing.	2 / 3
Trigger Term Quality	The description body lacks natural user keywords; the only natural phrasing ('frontmatter') is technical, and the actual trigger phrases ('validate frontmatter', 'fix frontmatter', 'brain lint') live in frontmatter `triggers` rather than in `description`, so the judged text shows some relevant keywords but misses common natural variations.	2 / 3
Distinctiveness Conflict Risk	The niche is narrow and specific (YAML frontmatter validation/repair on brain pages via a named CLI), with distinct triggers unlikely to fire for unrelated skills, matching the score-3 anchor of a clear niche with distinct triggers.	3 / 3
	Total	10 / 12 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: 3fafb69

Reviewed: about 20 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.