Frontmatter Validation Skill

Purpose: Validate YAML frontmatter in documentation against template requirements. Ensures consistency across all docs.

Trigger

When: Any .md file in docs/ is saved or created Context Needed: Document content, template for document_type MCP Tools: mcp_payment-syste_query_docs_by_type, read_file

Required Fields

All documents MUST have:

---
document_type: "[type]" # REQUIRED
module: "[module]" # REQUIRED
status: "[status]" # REQUIRED
version: "X.Y.Z" # REQUIRED
last_updated: "YYYY-MM-DD" # REQUIRED
author: "@username" # REQUIRED

keywords:
  - "[keyword1]" # REQUIRED (5-10)

related_docs: # REQUIRED (can be empty)
  database_schema: ""
  api_design: ""
  ux_flow: ""
---

Document Types → Templates

Status Values

status: "draft"       # Work in progress
status: "in-review"   # Under review
status: "approved"    # Ready for use
status: "deprecated"  # No longer valid

Validation Rules

1. Type Check: document_type must match valid types
2. Date Format: last_updated must be ISO date (YYYY-MM-DD)
3. Version Format: version must be semver (X.Y.Z)
4. Keywords: At least 5 keywords required
5. Author: Must start with @
6. Related Docs: Paths must exist or be empty string

Auto-Fix Suggestions

When validation fails, suggest:

• Missing fields with defaults
• Date format corrections
• Path corrections for related_docs

Example Output

{
  "valid": false,
  "errors": [
    {
      "field": "last_updated",
      "message": "Invalid date format",
      "suggestion": "2026-01-26"
    }
  ],
  "warnings": [
    { "field": "keywords", "message": "Only 3 keywords, recommend 5-10" }
  ]
}

Reference

• DOCUMENTATION-WORKFLOW.md
• docs/templates/