@reaatech/agents-markdown-linter

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Style, content, and best-practice linting rules for AGENTS.md and SKILL.md files. Ships with 18 built-in rules across three categories, plus an extensible rule registry and auto-fix engine for format-level issues.

Installation

npm install @reaatech/agents-markdown-linter
# or
pnpm add @reaatech/agents-markdown-linter

Feature Overview

• 18 built-in rules — Style (6), Content (7), Best Practice (5) covering formatting, structure, and quality
• Extensible rule registry — Register custom lint rules with registerRule
• Auto-fix engine — Fix trailing whitespace, missing code block languages, inconsistent table formats, and missing headings
• Severity levels — error, warning, info, suggestion
• Per-rule isolation — A failing rule does not abort the lint run
• Finding output — Standard Finding[] format consumable by reporters

Quick Start

import { parseMarkdown } from "@reaatech/agents-markdown-parser";
import { runLintRules, registerRule, runAutoFix } from "@reaatech/agents-markdown-linter";
 
const doc = await parseMarkdown(content, "./AGENTS.md");
const result = runLintRules(doc);
 
console.log(`Errors: ${result.errorCount}, Warnings: ${result.warningCount}`);
 
for (const finding of result.findings) {
  console.log(`${finding.severity}: ${finding.rule} — ${finding.message}`);
}
 
// Auto-fix formatting issues
const fixed = runAutoFix(content, ["trailing-whitespace", "no-code-language", "table-format"]);

API Reference

runLintRules(document)

Runs all registered rules against a document. Catches per-rule errors so one failing rule does not abort the run.

function runLintRules(
  document: AgentsMdDocument | SkillMdDocument
): LintResult

registerRule(category, ruleId, rule, definition)

Register a custom lint rule. Rules are side-effect modules — importing @reaatech/agents-markdown-linter automatically registers all built-in rules.

function registerRule(
  category: "style" | "content" | "bestPractice",
  ruleId: string,
  rule: LintRule,
  definition: RuleDefinition
): void

getRegisteredRules()

function getRegisteredRules(): RuleDefinition[]

runAutoFix(content, ruleIds)

Apply auto-fixes for the specified rules. Returns the fixed content string.

function runAutoFix(content: string, ruleIds: string[]): string

getAutoFixableRules()

Returns the list of rule IDs that support auto-fix.

function getAutoFixableRules(): string[]

Built-in Rules

Style Rules

Content Rules

Best Practice Rules

Custom Rule Example

import { registerRule } from "@reaatech/agents-markdown-linter";
 
registerRule("style", "my-custom-rule",
  (doc) => {
    const findings = [];
    if (!doc.frontmatter.description) {
      findings.push({
        ruleId: "my-custom-rule",
        severity: "warning",
        message: "Description is recommended in frontmatter",
      });
    }
    return findings;
  },
  {
    id: "my-custom-rule",
    description: "Enforce description in frontmatter",
    severity: "warning",
    category: "style",
    autoFixable: false,
  }
);

Related Packages

• @reaatech/agents-markdown — Core types and domain interfaces
• @reaatech/agents-markdown-parser — Markdown AST parser
• @reaatech/agents-markdown-validator — Schema validation engine

License

MIT