jacob-balslev/skill-graph / examples/projects/markdown-static-site/skills/markdown-post-frontmatter-validation
markdown-post-frontmatter-validation
UnverifiedUse when authoring or reviewing the frontmatter of a markdown post — checking required fields (title, date, slug, tags), validating against the content schema in `lib/content/schema.ts`, catching ambiguous date formats or tags not in the controlled vocabulary, and ensuring the slug matches the file path. Activate this skill whenever the task touches files under `content/posts/**/*.md`, the `parsePostFrontmatter()` helper, or any code path that reads YAML frontmatter from a content file. Do NOT use for general YAML schema design (use a generic schema-design skill) or for chasing a specific build-time validation failure (use debugging).
Markdown Post Frontmatter Validation
Concept of the skill
What it is: The project-specific validation discipline for the YAML frontmatter on markdown posts. Mental model: Frontmatter is a typed interface between content files and the site runtime. Why it exists: Routing, indexes, tags, dates, and previews all depend on frontmatter being complete and unambiguous. What it is NOT: It is not general YAML schema design, parser performance work, or debugging a specific failed build. Adjacent concepts: Content schemas, slug derivation, controlled vocabularies, date normalization. One-line analogy: It is the checklist that makes every post safe for the build to consume. Common misconception: If the markdown renders, the frontmatter is good enough; metadata can break listing pages even when body content renders.
Coverage
- Required-field enforcement — every post must declare
title,date,slug, andtags; missing fields fail the build at parse time - Date format discipline — ISO 8601 with explicit timezone (
2026-05-06T12:00:00Z); ambiguous formats like2026-05-06or5/6/26are rejected - Slug-to-path consistency — the
slugfield must match the post's directory name; out-of-sync slugs cause silent route conflicts - Controlled-vocabulary tagging — every tag in the post's
tagsarray must appear inlib/content/tag-vocabulary.ts; lowercase, hyphen-separated, no synonyms - Schema evolution — when
lib/content/schema.tschanges, every post's frontmatter is re-validated; existing posts that violate the new schema are flagged before the next build runs - Reserved-field protection — fields like
_id,_internal, or any underscore-prefixed key are reserved for the build pipeline and rejected in author-facing frontmatter
Philosophy of the skill
The frontmatter block is the contract every post makes with the site's index, the router, and the renderer. If that contract is loose — if posts can omit fields, use ambiguous dates, or invent ad-hoc tags — the index drifts, routes silently overlap, and the search surface degrades. The cost of catching frontmatter bugs at build time is one re-run; the cost of catching them in production is a broken page or a missing entry in the archive. The rule is: validate at parse time, fail loud, and keep the schema small enough that authors can hold it in their head.
Key Files
| File | Purpose |
|---|---|
content/posts/_template.md | The canonical template every new post copies — its frontmatter is the worked example of every required field |
lib/content/schema.ts | The TypeScript schema (Zod or equivalent) that runtime validation calls |
lib/content/parse-frontmatter.ts | The thin wrapper that reads the YAML block and runs schema.parse() — the failure surface for build-time errors |
Verification
Before merging any change to a post's frontmatter or to the schema:
- Every post has the four required fields:
title,date,slug,tags -
dateis ISO 8601 with timezone (no nakedYYYY-MM-DD, no locale-formatted dates) -
slugmatches the post's directory name exactly — not derived fromtitleat runtime - Every tag in
tagsis present inlib/content/tag-vocabulary.ts(runnpm run check:tagsto confirm) - No underscore-prefixed fields (
_id,_internal, etc.) — those are reserved for the pipeline - Schema changes (
lib/content/schema.ts) are paired with anpm run validate:postspass against the entirecontent/posts/**/*.mdset
Do NOT Use When
| Use instead | When |
|---|---|
| (a generic schema-design skill) | The task is designing a new YAML schema for an unrelated domain |
debugging | A specific build is failing and you need to reproduce the validation error from logs |
documentation | The task is writing a runbook or contributor doc about the frontmatter format |
refactor | The task is restructuring parse-frontmatter.ts without changing the validation contract |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |