@reaatech/agents-markdown
Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.
Core domain types, Zod validation schemas, and shared utilities for the @reaatech/agents-markdown-* ecosystem. This package is the single source of truth for all document shapes — AgentsMdDocument, SkillMdDocument, Finding, LintResult, ValidationResult — used throughout the toolkit.
Installation
terminal
npm install @reaatech/agents-markdown
# or
pnpm add @reaatech/agents-markdownFeature Overview
- Canonical domain types —
AgentsMdDocument,SkillMdDocument,ValidationResult,LintResult,Finding,ScaffoldConfig, and 10+ more interfaces - Zod validation schemas —
AgentsMdSchema,SkillMdSchema,AgentsMdFrontmatterSchema,SkillMdFrontmatterSchemaderived from the AGENTS.md specification - Shared utilities —
assertNever,delay,debounce,groupBy,randomId,sanitizePath,normalizeLineEndings,truncate - Inferred types —
AgentsMdFrontmatter,SkillMdFrontmatter,AgentsMdValidation,SkillMdValidation,McpTool,SkillReference - Version constant —
VERSIONstring shared across the ecosystem
Quick Start
typescript
import type { AgentsMdDocument, ValidationResult } from "@reaatech/agents-markdown";
import { AgentsMdFrontmatterSchema, VERSION } from "@reaatech/agents-markdown";
import { assertNever, groupBy, randomId } from "@reaatech/agents-markdown";
// Validate frontmatter with Zod
const parsed = AgentsMdFrontmatterSchema.safeParse({
agent_id: "my-agent",
display_name: "My Agent",
version: "1.0.0",
description: "An example agent",
type: "mcp",
});
if (!parsed.success) {
console.error(parsed.error.issues);
}API Reference
AgentsMdDocument
The parsed representation of an AGENTS.md file after running through the @reaatech/agents-markdown-parser.
typescript
interface AgentsMdDocument {
path: string;
raw: string;
frontmatter: ParsedFrontmatter;
title: string;
sections: Section[];
tables: MarkdownTable[];
codeBlocks: CodeBlock[];
frontmatterRange?: { start: number; end: number };
}SkillMdDocument
Identical shape to AgentsMdDocument, representing a parsed SKILL.md file.
ValidationResult
Returned by validators in @reaatech/agents-markdown-validator.
typescript
interface ValidationResult {
valid: boolean;
type: "agents" | "skill";
path: string;
errors: Finding[];
warnings: Finding[];
suggestions: Finding[];
}LintResult
Returned by runLintRules in @reaatech/agents-markdown-linter.
| Property | Type | Description |
|---|---|---|
path | string | File path being linted |
findings | Finding[] | All findings across all rules |
errorCount | number | Number of error-severity findings |
warningCount | number | Number of warning-severity findings |
infoCount | number | Number of info-severity findings |
fixableCount | number | Number of auto-fixable findings |
Finding
| Property | Type | Required | Description |
|---|---|---|---|
rule | string | Yes | Rule identifier |
severity | Severity | Yes | error" | "warning" | "info" | "suggestion |
message | string | Yes | Human-readable description |
location | ErrorLocation | No | Line/column in source |
suggestion | string | No | Suggested fix text |
autoFixable | boolean | No | Whether an auto-fix exists |
fix | unknown | No | Fix payload for auto-fix engine |
ScaffoldConfig
typescript
interface ScaffoldConfig {
agentType: AgentType;
agentId: string;
displayName: string;
description?: string;
version?: string;
skills: ScaffoldSkillConfig[];
outputDir: string;
overwrite?: boolean;
}Schemas
All Zod schemas are exported as named consts. Inferred types are exported alongside them.
| Schema | Inferred Type | Validates |
|---|---|---|
AgentsMdFrontmatterSchema | AgentsMdFrontmatter | YAML frontmatter fields (agent_id, display_name, version, description) |
SkillMdFrontmatterSchema | SkillMdFrontmatter | YAML frontmatter fields (skill_id, display_name, version, description) |
AgentsMdSchema | AgentsMdValidation | Full AGENTS.md structure with required sections |
SkillMdSchema | SkillMdValidation | Full SKILL.md structure with required sections |
McpToolSchema | McpTool | MCP tool definition (name, inputSchema, output, rateLimit) |
SkillReferenceSchema | SkillReference | Skill reference (skillId, path) |
SectionSchema | SchemaSection | Section heading metadata |
Utilities
| Function | Signature | Description |
|---|---|---|
assertNever | (x: never) => never | Exhaustive switch guard |
delay | (ms: number) => Promise<void> | setTimeout wrapper |
randomId | () => string | crypto.randomUUID() |
sanitizePath | (path: string) => string | Backslash to forward slash |
normalizeLineEndings | (text: string) => string | \r\n → \n |
truncate | (text: string, max: number) => string | Truncate with ... |
debounce | (fn: Function, ms: number) => Function | Generic debounce |
groupBy | <T, K>(arr: T[], fn: (item: T) => K) => Record<K, T[]> | Generic groupBy |
Type Aliases
| Type | Values |
|---|---|
Severity | error" | "warning" | "info" | "suggestion |
AgentType | mcp" | "orchestrator" | "classifier" | "router" | "evaluator |
SkillType | tool" | "orchestration" | "evaluation" | "routing |
OutputFormat | console" | "json" | "html" | "markdown |
Related Packages
@reaatech/agents-markdown-parser— Markdown AST parser with frontmatter extraction@reaatech/agents-markdown-validator— Schema validation engine for AGENTS.md and SKILL.md@reaatech/agents-markdown-linter— Style, content, and best-practice linting rules@reaatech/agents-markdown-scaffold— Template-based file generator