everyone-needs-a-copilot/frontmatter-validation

Frontmatter Validation

Validate and fix YAML frontmatter metadata in markdown documentation files.

Purpose

Frontmatter enables efficient AI navigation of documentation. This skill ensures all files have correct, complete metadata for their document type.

Frontmatter Schemas by Document Type

Tier 1: Skills (SKILL.md)

---
name: forces-analysis                # required, kebab-case
description: >-                      # required, trigger-rich — used by `cc skill search` for keyword matching
  One-line description covering use cases and when to invoke this skill.
version: 1.2                         # required, semver
allowed-tools: [Read, Write, Edit]   # required, array
tags: [forces, organization]         # required, array
---

Tier 2: Product Documentation

---
product: Insights Copilot            # required
status: active                       # required: active, beta, deprecated
last_updated: 2025-01-15             # required, ISO date
owner: Platform Team                 # required
token_estimate: 650                  # required, integer
doc_type: architecture               # required: overview, architecture, api, integration, security
source_of_truth: ../repo/docs/...    # optional, path to canonical doc
dependencies: [product-a, product-b] # optional, array
summary: Brief description           # optional, 1-2 sentences
key_entities: [Force, Pattern]       # optional, domain entities
integration_endpoints: [POST /api/x] # optional, for API docs
---

Tier 3: Operational Documentation

---
title: Documentation Strategy Guide  # required
doc_type: guide                       # required: guide, standard, reference, runbook
category: operations                  # required: operations, security, development
last_updated: 2025-01-15              # required, ISO date
version: 2.1                          # optional
status: active                        # required: active, deprecated, draft
primary_audience: [developers]        # optional, array
required_reading: false               # optional, boolean
token_estimate: 2500                  # required, integer
replaces: _archive/old-doc.md         # optional, path to replaced doc
related: [other-doc.md]               # optional, array
---

Procedure

1. Identify Target Files

find . -name "*.md" -type f -not -path "./_archive/*"

2. Detect Document Type

Infer from path and filename:

| Pattern | Document Type | |---------|---------------| | */SKILL.md | Tier 1: Skill | | 02-products/* | Tier 2: Product | | 03-ai-enabling/03-operations/* | Tier 3: Operational | | */00-overview.md | Product overview | | *-profile.md or 02-profiles/* | Agent profile |

3. Extract Existing Frontmatter

Frontmatter is YAML between --- markers at file start:

sed -n '/^---$/,/^---$/p' file.md | head -n -1 | tail -n +2

4. Validate Against Schema

Check for:

| Check | Severity | Description | |-------|----------|-------------| | Required fields missing | ERROR | Must be present | | Wrong type | ERROR | e.g., string instead of array | | Invalid value | ERROR | e.g., status: "live" not in enum | | Missing token_estimate | WARNING | Should be calculated and added | | Stale last_updated | WARNING | Older than file modification | | Broken path reference | WARNING | source_of_truth doesn't exist |

5. Auto-Fix Where Possible

| Missing Field | Auto-Fix Strategy | |---------------|-------------------| | token_estimate | Calculate from word count × 1.4 | | last_updated | Use current date | | status | Default to "active" | | name | Derive from directory name | | doc_type | Infer from path/filename |

6. Generate Missing Frontmatter

For files without frontmatter, generate based on type:

---
title: [Derived from H1 or filename]
doc_type: [Inferred from path]
last_updated: 2025-12-21
status: active
token_estimate: [Calculated]
---

Output Format

## Frontmatter Validation Report

### Summary
- Files scanned: N
- Valid: N
- Errors: N
- Warnings: N
- Fixed: N

### Errors (Must Fix)

| File | Issue | Field | Details |
|------|-------|-------|---------|
| skills/x/SKILL.md | Missing required | name | Add skill name |
| products/y.md | Invalid value | status | "live" not valid, use "active" |

### Warnings

| File | Issue | Field | Suggestion |
|------|-------|-------|------------|
| docs/guide.md | Missing | token_estimate | Add: 1,250 (calculated) |
| docs/api.md | Stale | last_updated | Update to current date |

### Auto-Fixes Applied

| File | Field | Old Value | New Value |
|------|-------|-----------|-----------|
| docs/setup.md | token_estimate | (missing) | 890 |
| docs/setup.md | last_updated | 2024-06-01 | 2025-12-21 |

Validation Rules

Field Value Rules

| Field | Valid Values | |-------|--------------| | status | active, deprecated, draft, beta | | skill_category | analysis, engineering, facilitation, strategy, documentation | | doc_type | overview, architecture, api, integration, security, guide, standard, reference, runbook | | allowed_tools | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch |

Path Validation

For path fields (source_of_truth, methodology, replaces, related):

• Resolve relative to file location
• Check target exists
• Warn if external to repository

Token Estimate Accuracy

Compare token_estimate to actual:

• Within 10%: OK
• 10-25% off: WARNING

• 25% off: ERROR (likely stale)