Agent skill
frontmatter-validation-everyone-needs-a-cop-claude-copilot
Validate and fix YAML frontmatter in markdown documentation
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/frontmatter-validation-everyone-needs-a-cop-claude-copilot
SKILL.md
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)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?