@reaatech/agents-markdown-validator
Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.
Zod schema validation engine for AGENTS.md and SKILL.md files. Validates frontmatter structure, required sections, section ordering, skill references, MCP tools tables, and content quality against the AGENTS.md specification.
Installation
terminal
npm install @reaatech/agents-markdown-validator
# or
pnpm add @reaatech/agents-markdown-validatorFeature Overview
- Frontmatter validation — Zod schemas enforce required YAML fields, types, and optional config
- Required sections — Checks all mandated sections are present for both AGENTS.md (8 sections) and SKILL.md (5 sections)
- Recommended sections — Warns on missing recommended sections for AGENTS.md
- Section ordering — Validates that sections follow the recommended order
- Skill references — Ensures referenced
skills/*.mdfiles exist and skill IDs are unique - MCP tools table — Validates table structure, required columns, and tool naming conventions
- Content quality — Flags placeholder text (
TODO,FIXME), empty sections, missing PII mentions, missing logging mentions - User-friendly errors — Formatted findings with context, suggestions, and grouped summaries
Quick Start
typescript
import { parseMarkdown } from "@reaatech/agents-markdown-parser";
import { validate, validateAgentsMd, validateSkillMd } from "@reaatech/agents-markdown-validator";
const doc = await parseMarkdown(content, "./AGENTS.md");
// Generic validate (auto-detects AGENTS.md vs SKILL.md)
const result = validate(doc, { strict: true });
if (!result.valid) {
for (const error of result.errors) {
console.error(`${error.rule}: ${error.message}`);
}
}
// Type-specific validators
const agentResult = validateAgentsMd(doc, { basePath: "./", existingSkills: ["echo"] });
const skillResult = validateSkillMd(doc, { basePath: "./" });API Reference
validate(document, options?)
Auto-dispatches to the correct validator based on document type.
typescript
function validate(
document: AgentsMdDocument | SkillMdDocument,
options?: ValidationOptions
): ValidationResult
interface ValidationOptions {
strict?: boolean; // Fail on warnings
basePath?: string; // Base path for skill resolution
existingSkills?: string[]; // Known skill IDs for reference checking
}validateMultiple(documents, options?)
Batch validate. Returns one ValidationResult per document.
AGENTS.md Validation (validateAgentsMd)
Validates 10 checks:
| Check | Severity | Description |
|---|---|---|
| Frontmatter existence + Zod parse | error | Must have valid YAML frontmatter |
| Confidence threshold | error | confidence_threshold must be present |
| Title | error | Must have a # heading |
| Required sections | error | All 7+ sections must exist |
| Recommended sections | warning | 5 recommended sections should exist |
| Heading order | warning | Headings must not skip levels |
| Skill references | error | Referenced skills must exist and be unique |
| PII handling | warning | Security section should mention PII |
| Logging | warning | Observability section should mention structured logging |
| Placeholders / empty | warning | No TODO/FIXME or empty sections |
SKILL.md Validation (validateSkillMd)
Validates 8 checks:
| Check | Severity | Description |
|---|---|---|
| Frontmatter | error | Must have valid YAML frontmatter |
| Title | error | Must have a # heading |
| Required sections | error | All 5 sections must exist |
| MCP tools table | error | Must have proper table with Tool, Input Schema, Output columns |
| MCP tool names | warning | Tool names should follow naming conventions |
| Usage examples | warning | Should include both success and error cases |
| Security permissions | warning | Should mention permission requirements |
| Placeholders / empty | warning | No placeholder text or empty sections |
Helpers
typescript
function createFinding(
rule: string, severity: Severity, message: string,
location?: ErrorLocation, suggestion?: string,
autoFixable?: boolean, fix?: unknown
): Finding
function createError(rule: string, message: string, location?: ErrorLocation): Finding
function createWarning(rule: string, message: string, location?: ErrorLocation): Finding
function createInfo(rule: string, message: string, location?: ErrorLocation): Finding
function createSuggestion(rule: string, message: string, location?: ErrorLocation): Finding
function createFixableFinding(rule: string, message: string, fix: unknown, location?: ErrorLocation): FindingError Formatting
| Function | Description |
|---|---|
formatFinding(finding) | Human-readable finding with severity, rule, message, location, suggestion |
formatValidationSummary(result) | One-line summary: valid/invalid with counts |
formatFindingsGrouped(findings) | Grouped by severity with emoji headers |
formatWithContext(finding, content, contextLines?) | Finding + surrounding source lines |
createErrorReport(results, options?) | Full ASCII-boxed report with summary |
getAutoFixableFindings(results) | Filter to fixable findings with fix data |
Related Packages
@reaatech/agents-markdown— Core types and schemas@reaatech/agents-markdown-parser— Markdown AST parser@reaatech/agents-markdown-linter— Linting rules engine