Frontmatter Validation

Validate and fix YAML frontmatter in markdown documentation

majiayu000 Updated Sep 22, 2026 567 repo stars

Install

Press C to copy

$ npx skillmds@latest add majiayu000/frontmatter-validation-2

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/majiayu000/frontmatter-validation-2.svg)](https://skillmd.com/skills/majiayu000/frontmatter-validation-2)

Trust & safety

Audits pending

Not yet audited · commit 77cc726

Permissions this skill uses

Reads secrets
The instructions read tokens, keys, or other credentials.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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)

---
skill_name: forces-analysis          # required, kebab-case
skill_category: analysis             # required: analysis, engineering, facilitation, strategy
description: One-line description    # required, max 100 chars
allowed_tools: [Read, Write, Edit]   # required, array
token_estimate: 1850                 # required, integer
version: 1.2                         # required, semver
last_updated: 2025-01-15             # required, ISO date
owner: Service Design Team           # required
status: active                       # required: active, deprecated, draft
tags: [forces, organization]         # required, array
related_skills: [moments-mapping]    # optional, array
methodology: path/to/methodology.md  # optional, relative path
---

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"
`skill_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 | skill_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)

---name: frontmatter-validation-2description: Validate and fix YAML frontmatter in markdown documentation---# Frontmatter ValidationValidate and fix YAML frontmatter metadata in markdown documentation files.## PurposeFrontmatter 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)```yaml---skill_name: forces-analysis # required, kebab-caseskill_category: analysis # required: analysis, engineering, facilitation, strategydescription: One-line description # required, max 100 charsallowed_tools: [Read, Write, Edit] # required, arraytoken_estimate: 1850 # required, integerversion: 1.2 # required, semverlast_updated: 2025-01-15 # required, ISO dateowner: Service Design Team # requiredstatus: active # required: active, deprecated, drafttags: [forces, organization] # required, arrayrelated_skills: [moments-mapping] # optional, arraymethodology: path/to/methodology.md # optional, relative path---```### Tier 2: Product Documentation```yaml---product: Insights Copilot # requiredstatus: active # required: active, beta, deprecatedlast_updated: 2025-01-15 # required, ISO dateowner: Platform Team # requiredtoken_estimate: 650 # required, integerdoc_type: architecture # required: overview, architecture, api, integration, securitysource_of_truth: ../repo/docs/... # optional, path to canonical docdependencies: [product-a, product-b] # optional, arraysummary: Brief description # optional, 1-2 sentenceskey_entities: [Force, Pattern] # optional, domain entitiesintegration_endpoints: [POST /api/x] # optional, for API docs---```### Tier 3: Operational Documentation```yaml---title: Documentation Strategy Guide # requireddoc_type: guide # required: guide, standard, reference, runbookcategory: operations # required: operations, security, developmentlast_updated: 2025-01-15 # required, ISO dateversion: 2.1 # optionalstatus: active # required: active, deprecated, draftprimary_audience: [developers] # optional, arrayrequired_reading: false # optional, booleantoken_estimate: 2500 # required, integerreplaces: _archive/old-doc.md # optional, path to replaced docrelated: [other-doc.md] # optional, array---```## Procedure### 1. Identify Target Files```bashfind . -name "*.md" -type f -not -path "./_archive/*"```### 2. Detect Document TypeInfer 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 FrontmatterFrontmatter is YAML between `---` markers at file start:```bashsed -n '/^---$/,/^---$/p' file.md | head -n -1 | tail -n +2```### 4. Validate Against SchemaCheck 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" || `skill_name` | Derive from directory name || `doc_type` | Infer from path/filename |### 6. Generate Missing FrontmatterFor files without frontmatter, generate based on type:```yaml---title: [Derived from H1 or filename]doc_type: [Inferred from path]last_updated: 2025-12-21status: activetoken_estimate: [Calculated]---```## Output Format```markdown## 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 | skill_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 ValidationFor path fields (`source_of_truth`, `methodology`, `replaces`, `related`):- Resolve relative to file location- Check target exists- Warn if external to repository### Token Estimate AccuracyCompare `token_estimate` to actual:- Within 10%: OK- 10-25% off: WARNING- >25% off: ERROR (likely stale)

majiayu000/claude-skill-registry-data/tree/main/documents/frontmatter-validation commit 77cc726c19

Frequently asked questions

npx skillmds@latest add majiayu000/frontmatter-validation-2