# Markdown Frontmatter

> Add and maintain YAML frontmatter in Markdown files. Use this whenever creating or substantially editing any .md content in this repository.

- Skill: `ekuris-repos/markdown-frontmatter` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ekuris-repos/markdown-frontmatter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ekuris-repos/markdown-frontmatter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: ekuris-repos (https://skillmd.com/u/ekuris-repos)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ekuris-repos/markdown-frontmatter

---


# Markdown YAML Frontmatter

## Goal

Ensure every Markdown file created or substantially edited includes a YAML frontmatter block with consistent, searchable metadata.

## Required Frontmatter Fields

When creating **any** `.md` file content (new file or major rewrite), include a YAML frontmatter block at the very top of the file with these fields:

- `title`: Human-readable title (string)
- `description`: One-paragraph summary (string)
- `category`: One primary category (string)
- `tags`: List of keywords for discovery (array of strings) — **see Tag Selection Guide below**
- `status`: One of `Proposed`, `Working`, `Living` (string)
- `updated`: Last meaningful edit date (ISO-8601 `YYYY-MM-DD`)
- `related`: Paths to closely related docs (array of strings)
- `links_from`: Paths that reference or should reference this doc (array of strings)

## Tag Selection Guide

Tags enable **tag-based discovery** — finding documents that bridge multiple concepts. Choose tags strategically:

### Tag Categories

1. **Domain tags**: The primary subject area (e.g., `async`, `error-handling`, `testing`)
2. **Pattern tags**: Design patterns or techniques (e.g., `retry`, `result-pattern`, `dependency-injection`)
3. **Technology tags**: Specific technologies or libraries (e.g., `polly`, `entity-framework`, `signalr`)
4. **Concern tags**: Cross-cutting concerns (e.g., `performance`, `security`, `resilience`)

### Best Practices

- Include **3–8 tags** per document
- Include at least one **domain tag** and one **pattern/concern tag**
- Use **consistent naming**: lowercase, hyphenated (e.g., `error-handling` not `ErrorHandling`)
- Include **synonyms** when commonly searched (e.g., both `di` and `dependency-injection`)
- Think: "What concepts does this document bridge?"

### Example: Good Tag Selection

```yaml
# Document about async exception handling
tags: ["async", "error-handling", "exceptions", "task", "cancellation"]

# Document bridges: async ↔ error-handling ↔ cancellation
# Discoverable via: "async error handling", "cancellation exceptions", etc.
```

### Anti-patterns

- ❌ Too few tags: `tags: ["csharp"]` — not discoverable
- ❌ Too generic: `tags: ["code", "programming", "software"]` — no signal
- ❌ Inconsistent naming: `tags: ["ErrorHandling", "error_handling"]` — won't match searches

## Process

1. Determine whether the task is creating/editing Markdown content.
   - If yes, ensure frontmatter exists.
   - Exception: prompt definition files (for example `.prompt.md` under `.github/prompts`) may require a restricted frontmatter schema. In that case, keep the prompt frontmatter valid and record the required doc-metadata fields in the body.
2. If the file has no frontmatter, add a new YAML frontmatter block at the top.
3. If the file has frontmatter, preserve existing fields and add any missing required fields.
4. **Select tags strategically** using the Tag Selection Guide above.
5. Update `updated` to today's date (ISO `YYYY-MM-DD`) when changes are non-trivial.
6. Keep `related` and `links_from` as **workspace-relative paths** (use `/` separators).
7. Keep metadata minimal and accurate.
   - Prefer 3–8 tags (with cross-domain coverage).
   - Prefer 0–6 related files.
   - `links_from` is allowed to be empty initially; populate it when known.

## Template

Use this template when creating new Markdown files:

```yaml
---
title: "<concise title>"
description: "<1–3 sentence summary>"
category: "<single category>"
tags: ["tag-one", "tag-two"]
status: "Proposed"
updated: "YYYY-MM-DD"
related: ["knowledge-base/README.md"]
links_from: ["README.md"]
---
```

Note: Prefer YAML inline arrays for `tags`, `related`, and `links_from` (for example `tags: ["tag-one", "tag-two"]`) to keep metadata compact.

## Examples

### Example: Adding frontmatter to an existing doc

If a file begins immediately with a heading (e.g., `# Something`), prepend the frontmatter block above it.

### Example: Filling `related` and `links_from`

- `related` should include peer docs that a reader should also see.
- `links_from` should include docs that link here, or that *should* link here once the docs are cleaned up.

## Guardrails

- Don’t invent relationships. If you’re unsure, leave `related: []` and/or `links_from: []`.
- Don’t rewrite the whole doc just to add metadata; keep the diff focused.
- If the repository already uses another metadata system in a subfolder, follow that local convention and still include these required fields unless it conflicts.