Prompt file imported from ekuris-repos/Swarm (.github/prompts/markdown-standards-validator.prompt.md). Copyright stays with the author.

Markdown Standards Validator

Documentation metadata (repo standard)

This .prompt.md file is a prompt definition. Prompt files have a restricted frontmatter schema, so the repo’s document-metadata fields are recorded here instead of YAML.

• title: Markdown Standards Validator
• category: prompts
• tags: markdown, documentation, validation, frontmatter, quality
• status: Working
• updated: 2026-01-16
• related: [".github/skills/markdown-frontmatter/SKILL.md", ".github/skills/frontmatter-context-traversal/SKILL.md", ".github/copilot-instructions.md"]
• links_from: []

You are validating Markdown documents in this repository for compliance with the documentation standards.

What to Validate

For each target Markdown file:

1) YAML frontmatter (required)

The file must start with YAML frontmatter (--- at top), containing all required fields:

• title (string)
• description (string)
• category (string)
• tags (array of strings)
• status (string; MUST be one of: Proposed, Working, Living)
• updated (ISO date string YYYY-MM-DD)
• related (array of strings; workspace-relative paths)
• links_from (array of strings; workspace-relative paths)

Rules:

• related and links_from paths MUST use / separators and be workspace-relative (no drive letters).
• Prefer YAML inline arrays for tags, related, and links_from to keep metadata compact.
• updated MUST be updated when the file content changes meaningfully.

2) Single-topic, wiki-style article

The document must be a single topic wiki-style article:

• One clear subject; avoid bundling unrelated topics.
• One top-level H1 heading that matches (or is consistent with) the frontmatter title.
• Starts with a short overview paragraph that explains what the page is and who it’s for.
• Uses headings for structure (e.g., ## Overview, ## Usage, ## Examples, ## Troubleshooting, ## References) as appropriate.
• Avoids changelog-style dumps; keep it task/knowledge oriented.

If the file contains multiple unrelated topics:

• Recommend splitting into multiple Markdown files.
• Add cross-links via related and links_from.

3) Link graph integrity

All paths referenced in frontmatter MUST exist:

• Every entry in related must resolve to an existing file in the repo.
• Every entry in links_from must resolve to an existing file in the repo.

If a referenced path does not exist:

• Treat as a validation failure.
• Propose a correction (typo fix, correct path) or remove the entry if it cannot be justified.

Target File Selection ("recently created" or "referenced")

Determine the set of Markdown files to validate using this priority order:

1. Files explicitly mentioned by the user in chat.
2. Newly created or modified Markdown files in the current working tree / PR.
   • Use git status --porcelain to find changed files.
   • Optionally use git diff --name-only --diff-filter=AM to focus on new/added files.

If git is unavailable, validate any .md files that were just created/edited as part of the current task.

How to Validate Efficiently

• Prefer quick checks first (frontmatter presence, required keys).
• Then validate structure (single-topic wiki style).
• Then validate existence of related/links_from targets.

Suggested PowerShell commands (use ; to chain commands):

• List changed Markdown files:
  • git status --porcelain | Select-String -Pattern '\.md$'
  • git diff --name-only --diff-filter=AM | Select-String -Pattern '\.md$'
• Check that a referenced file exists:
  • Test-Path -LiteralPath (Join-Path (Get-Location) '<path-from-frontmatter>')

Output Format

Return a concise validation report:

• For each file: PASS or FAIL
• If FAIL: list each violation and the minimal fix
• If fixes are straightforward and you have edit permissions: apply the minimal patch (frontmatter insertion, status correction, path corrections) and re-validate.

Common Fixes

• Add missing frontmatter block at top.
• Normalize status to one of: Proposed, Working, Living.
• Convert related/links_from to arrays (even if empty).
• Correct or remove invalid related/links_from entries.
• Split multi-topic docs into separate pages (if requested) and connect them using related/links_from.