--- name: markdown-article-frontmatter source: https://app.decimal.ai/s/markdown-article-frontmatter@1/SKILL.md source_sha256: b7fd3d1bee4c --- # Markdown Article Frontmatter Convention ## Contract When you format or "beautify" prose into a publish-ready markdown file, emit a YAML frontmatter block with EXACTLY the fields below, in the given order, move any body H1 into `title`, and leave the body prose untouched. Apply whenever the task asks to format, beautify, clean up, or add a metadata/frontmatter header to an article, post, or note. ## Rules ### R1 — Field set is exactly four (plus one conditional) The frontmatter contains EXACTLY these four fields, in THIS order: 1. `title` 2. `slug` 3. `summary` 4. `description` Add `coverImage` (5th) ONLY when a cover image actually exists for the article. Never invent it. Add NOTHING else: no `date`, `author`, `tags`, `category`, `excerpt`, `keywords`, `draft`, `layout`, `published`, `readingTime`, or any other key — even if it seems helpful or conventional elsewhere. Four fields, that order, full stop. ### R2 — Title lives only in frontmatter; body is H1-free If the body starts with an H1 (`# ...`), MOVE that exact text into the `title` field and DELETE the `# ...` line from the body. If the source has no H1, derive a `title` from the content. The body must contain NO level-1 heading anywhere — the first body heading is `##`. There is never both a `title` in frontmatter and a `# ` line in the body (that duplicates the title). ### R3 — slug is kebab-case derived from the title `slug` is the title lowercased and kebab-cased: all lowercase, words joined by SINGLE hyphens, ASCII only, no spaces, no punctuation (drop `?`, `:`, `,`, `.`, `'`, `"`, `&`, `/`), no leading/trailing hyphen, no doubled hyphens. Drop nothing meaningful — keep the content words so the slug stays recognizable. It is NOT a random id, NOT snake_case, NOT camelCase, NOT title-cased. ### R4 — summary is ONE short sentence conveying reader VALUE `summary` is a SINGLE sentence, roughly 50–80 characters, that conveys the reader value (what they get), not merely the topic. It is the punchy hook used in feeds and SEO meta. It MUST be shorter (fewer characters) than `description`. ### R5 — description is 2–3 sentences of richer context `description` is 2–3 sentences, roughly 100–200 characters, expanding on `summary` with supporting detail. It is always LONGER than `summary`. ### R6 — Forbidden openings for summary and description NEITHER `summary` NOR `description` may begin with: "This article", "This post", "This guide", "In this article", "In this post", "In this", "Here we", "A guide to", or a reworded copy of the title. Lead with the value or the concrete claim instead. ### R7 — Never touch the body prose Only formatting (headings, bold, lists, code, blockquotes) and the frontmatter may change. Never add sentences, delete content, shorten, or rephrase the author's words. Preserve voice, tone, and every word. ## Worked examples ### R1 — exact field set (BEFORE → AFTER) BEFORE (base adds helpful extras — `date`, `author`, `tags`): ```yaml --- title: Caching Is a Distributed System date: 2026-06-26 author: Engineering Team tags: [caching, systems] slug: caching-is-a-distributed-system description: ... --- ``` AFTER (exactly four fields, correct order): ```yaml --- title: Caching Is a Distributed System slug: caching-is-a-distributed-system summary: Add a cache and you inherit a second source of truth to keep honest. description: A cache turns one source of truth into two. Treat invalidation as a design decision up front, not a bug you patch later. --- ``` ### R2 — H1 moves into frontmatter (BEFORE → AFTER) BEFORE (title duplicated as a body H1): ```markdown --- title: Postgres Is All You Need slug: postgres-is-all-you-need summary: ... description: ... --- # Postgres Is All You Need You probably do not need Kafka, Redis, and Elasticsearch on day one. ``` AFTER (body H1 deleted; body starts with prose or `##`): ```markdown --- title: Postgres Is All You Need slug: postgres-is-all-you-need summary: ... description: ... --- You probably do not need Kafka, Redis, and Elasticsearch on day one. ``` ### R3 — slug kebab-case (BEFORE → AFTER) Title: `Why We Switched to Postgres: A Field Guide` BEFORE (base keeps casing/punctuation or uses snake_case): ```yaml slug: Why_We_Switched_to_Postgres:_A_Field_Guide ``` AFTER: ```yaml slug: why-we-switched-to-postgres-a-field-guide ``` ### R4 / R5 — summary value vs topic, and length ordering (BEFORE → AFTER) BEFORE (topic restatement, and summary longer than description): ```yaml summary: This article is about how our team migrated the billing service to Rust and what we learned during the process. description: A migration story. ``` AFTER (summary = punchy value, shorter than description): ```yaml summary: Rewriting billing in Rust cut p99 latency from 800ms to 40ms. description: A Python billing service that timed out under load became a Rust one with 20x lower tail latency. Here are the migration surprises that mattered. ``` ### R6 — forbidden opening (BEFORE → AFTER) BEFORE: ```yaml summary: This article explores why standups became status theater. ``` AFTER: ```yaml summary: Async, five-line standups gave the team its mornings back. ``` ### R7 — body prose preserved (BEFORE → AFTER) BEFORE (base "improves" the wording while formatting): ```markdown We made standups async and capped them at five lines, reclaiming our focus time. ``` (original was: "We made them async, capped at five lines each, and got our mornings back.") AFTER (original words kept verbatim; only frontmatter/formatting added): ```markdown We made them async, capped at five lines each, and got our mornings back. ``` ## Edge cases & exceptions - **No H1 in source.** Derive `title` from the content; still emit all four fields. The body simply never gains a `# ` line. - **An existing frontmatter field is already present.** Keep an existing good `title`, `summary`, or `description`; only fill the missing ones. But still strip any non-conforming extra keys (`date`, `tags`, …) per R1. - **Title has a colon or subtitle** (`Foo: A Field Guide`). The colon and space become a hyphen in the slug → `foo-a-field-guide` (no stray double hyphen). - **Numbers and ampersands in the title.** Keep digits; spell-or-drop symbols: `Cut Our AWS Bill in Half` → `cut-our-aws-bill-in-half`; `Q&A` → `q-a` (ampersand dropped, not kept). - **No real cover image.** Do NOT add `coverImage`. It is the only conditional field and it requires an actual image to exist. - **summary creeping past ~80 chars.** Tighten it; the one-sentence, shorter-than- description constraints are hard, not soft. ## Do / Don't - DON'T add `date`, `author`, `tags`, `category`, or `excerpt`. ALWAYS emit exactly `title`, `slug`, `summary`, `description` (+ `coverImage` only if one exists). - DON'T leave a `# Title` line in the body. ALWAYS move it into `title` and delete it. - DON'T write the slug in Title Case, snake_case, or with punctuation. ALWAYS kebab-case, lowercase, ASCII, single hyphens. - DON'T open `summary`/`description` with "This article…". ALWAYS lead with the value. - DON'T make `summary` longer than `description`. ALWAYS keep `summary` the shorter, one- sentence field. - DON'T reword, trim, or add to the body prose. ALWAYS preserve every original word. ## Common mistakes (the base's wrong defaults) 1. Helpfully adding `date`, `author`, and `tags` — extra fields that violate the exact-four rule. 2. Keeping the title as a body `# H1` AND putting it in frontmatter — duplication. 3. Emitting a slug that mirrors the title's casing/punctuation, or using snake_case. 4. Writing `summary` as a topic restatement ("This article covers…") instead of value. 5. Making `summary` longer than `description`, or making them near-identical. 6. Silently polishing the author's sentences while "formatting." ## Quick checklist - [ ] Frontmatter has exactly `title`, `slug`, `summary`, `description`, in that order. - [ ] No `date`/`author`/`tags`/`category`/`excerpt`/`keywords`. - [ ] Body has no `# ` H1; title is only in frontmatter. - [ ] `slug` is lowercase kebab-case, ASCII, single hyphens, no punctuation. - [ ] `summary` is one sentence (~50–80 chars), value-led, shorter than `description`. - [ ] `description` is 2–3 sentences (~100–200 chars), longer than `summary`. - [ ] Neither opens with "This article/post/guide" or restates the title. - [ ] Body prose is byte-for-byte the author's.