CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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), explains files sync holds instead of importing, and drives the previewed `gbrain repair frontmatter` fix. Wraps the `gbrain frontmatter` CLI for agent-driven workflows.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/frontmatter-guard/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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.

An exceptionally actionable, well-sequenced CLI-wrapping skill with strong validation loops for its destructive batch operations. Its weaknesses are moderate verbosity (duplicated trigger lists, motivational and historical narrative, generic YAML quoting rules) and a monolithic single-file layout that inlines detailed reference material a leaner SKILL.md would point to.

Suggestions

Delete the body 'Trigger words' section (it duplicates the frontmatter triggers field) and trim the 'Why This Exists' narrative and v0.37.5.0 quote-counter history to one line each.

Move the 'Prevention — Writing Valid Frontmatter' tutorial and the JSON output envelope into references/ files (e.g. references/writing-frontmatter.md, references/output-format.md), keeping SKILL.md an overview with clearly signaled links.

Drop the generic 'When to quote at all' YAML rules Claude already knows, keeping only the gbrain-specific canonical form (single-quoted flow style) and the LLM template-literal trap.

DimensionReasoningScore

Conciseness

The bulk is dense, token-earning material (exact commands, flags, exit codes, hold-record fields), but roughly 30 of 267 lines could be cut: the 'Trigger words' section duplicates the frontmatter triggers field verbatim, 'Why This Exists' is a motivation narrative, the v0.37.5.0 quote-counter history is a war story, 'When to quote at all' teaches generic YAML quoting, and several cautions repeat across Output rules, When it fails, and Anti-Patterns. Fits anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') better than 4's 'minor instances'.

3 / 5

Actionability

Fully executable throughout: copy-paste-ready commands with complete flags ('gbrain repair frontmatter --source <id> --include-ambiguous --only <path> --apply --expect <hash> --yes'), exit-code semantics, backup paths, exact size limits (24 MiB / 5 MB), correct-vs-broken YAML examples, and a full JSON output envelope. Matches the 5 anchor: specific examples cover the common cases.

5 / 5

Workflow Clarity

Phases 1-4 are clearly sequenced (audit, validate, fix, hook) with explicit validation checkpoints and feedback loops for a file-rewriting batch skill: '--dry-run' previews before batch fixes, '--diff' then hash-bound '--apply --expect <hash>', '--fix' 're-validates, and exits 1 when errors remain', mandatory user approval before every apply, and a 'When it fails' recovery section. The destructive/batch cap at 3 does not apply because validation is thorough — a clear anchor 5.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent), so all ~267 lines live in SKILL.md. Internal headers and one-level-deep external links ('docs/guides/repair.md#held-files', '../conventions/agent-operator-protocol.md') are clearly signaled, but substantial reference material is inlined where the rubric expects an overview — the ~55-line Prevention/YAML tutorial and ~35-line output-format spec belong in separate reference files. Fits anchor 3 ('content that should be separate is inline'); not 2, since structure and links are good, and not 4, given the volume of inlined detail.

3 / 5

Total

16

/

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.

A highly specific, third-person description with concrete actions, enumerated error classes, and a distinct niche. Its main gap is the missing 'Use when...' trigger clause inside the description itself, which caps completeness; trigger phrases exist only in the separate frontmatter triggers field.

Suggestions

Append a 'Use when...' clause to the description field itself with natural trigger phrases, e.g. 'Use when the user says "validate/check/fix frontmatter", "brain lint", "frontmatter audit", or when a gbrain sync holds a file.'

Soften domain jargon like 'explains files sync holds instead of importing' to phrasing a user would naturally say, such as 'explains why sync held a file instead of importing it'.

Fold one or two natural trigger synonyms ('audit', 'lint', 'held files') into the description so it matches the trigger coverage already declared in the frontmatter.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — 'Validate and auto-repair YAML frontmatter', 'explains files sync holds instead of importing', 'drives the previewed `gbrain repair frontmatter` fix' — and enumerates the exact error classes caught ('missing closing ---, nested quotes, slug mismatches, null bytes, empty frontmatter, YAML parse failures'), giving comprehensive coverage of the skill's capabilities.

5 / 5

Completeness

The 'what' is explicit and detailed, but the description field contains no 'Use when...' clause or equivalent explicit trigger guidance (the trigger phrases live only in the separate frontmatter `triggers` field), which caps completeness at 3 per the judging guidelines. It fits anchor 3 ('clear what but when is missing') and does not reach 4, which requires both what and when.

3 / 5

Trigger Term Quality

Terms like 'validate', 'frontmatter', 'repair', and 'sync holds' are natural phrases for this domain, but common variations the skill itself lists as triggers ('check frontmatter', 'frontmatter audit', 'brain lint') are absent from the description, and 'files sync holds' is awkward phrasing. Good coverage, a few natural terms missing — matches the 4 anchor, not comprehensive enough for 5.

4 / 5

Distinctiveness Conflict Risk

'YAML frontmatter on brain pages' plus the named `gbrain` CLI is a clear niche with distinct triggers; no other generic skill would fire on these phrases. Minimal conflict risk — matches the 5 anchor.

5 / 5

Total

17

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 2 suspicious

Warning

Total

14

/

16

Passed

Repository

garrytan/gbrain

Path

skills/frontmatter-guard/SKILL.md

Reviewed

Table of Contents

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.