Our review
Validates Markdown files with YAML frontmatter against JSON Schema definitions.
Strengths
- Automates quality checks for structured content in Markdown files.
- Provides clear error messages with field path and file location.
- Simple single-command usage.
Limitations
- Requires a schema.yaml file in the target directory.
- Depends on Python and the pyyaml and jsonschema libraries.
- Only validates YAML frontmatter, not the Markdown body.
To validate structured Markdown files with YAML metadata (e.g., CRM entries, documentation pages) in a repeatable manner.
For validating free-form Markdown content without frontmatter or when the schema is unknown.
Security analysis
SafeThe skill instructs running a Python validation script on markdown files; no destructive, exfiltrating, or obfuscated actions are present. The script is not included, but the skill itself contains no malicious instructions.
No concerns found
Examples
Run validation on the crm/contacts directory to check all markdown files against the schema.Validate the crm/opportunities directory and fix any missing required fields like 'stage'.name: validate-md description: Validates markdown files with YAML frontmatter against JSON Schema definitions. allowed-tools: [Bash, Read, Glob]
Validating Markdown Files
Instructions
-
Run validation script for the target directory containing a
schema.yamlfile:python validate-md.py <directory> -
Review results:
- Success:
✓ OK: filename.md is valid - Errors: Shows validation error, field path, and file location
- Success:
Examples
Example 1: Validate contacts directory
python validate-md.py crm/contacts
Output:
✓ OK: smith-john.md is valid
✓ OK: doe-jane.md is valid
✓ SUCCESS: All 2 files are valid!
Example 2: Validation error - missing required field
python validate-md.py crm/opportunities
Output:
❌ deal-2024-q1.md validation error: 'stage' is a required property
In file: crm/opportunities/deal-2024-q1.md
Fix: Add stage: qualified to the frontmatter.
Scripts
validate-md.pythe python validation script
Required Python Packages
- pyyaml - for parsing YAML frontmatter
- jsonschema - for validating against JSON Schema
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Documentation Maintenance
Documentation
This skill provides a structured workflow for updating project documentation including CLAUDE.md, README, and CHANGELOG. It walks through phases like inventorying existing docs, analyzing git history for needed changes, optimizing for AI readability, and ensuring cross-document consistency. Use it when synchronizing documentation with code changes or improving documentation effectiveness for AI coding agents.