AgentMD

Parse & Validate

AgentMD parses AGENTS.md into structured sections and commands, then validates against the standard and best practices.

What We Parse

  • YAML frontmatter — Agent config (name, permissions, guardrails)
  • Markdown sections — Headings (# ## ###) with content
  • Commands — Backtick-wrapped, code blocks, run/execute patterns
  • Directives — <!-- agents-md: key=value --> for composition

Validation Rules

RuleSeverityDescription
EMPTYErrorAGENTS.md must not be empty
LONG_FILEWarningRecommended under 150 lines for brevity
NO_SECTIONSWarningAdd markdown headings for structure
UNSAFE_COMMANDErrorDangerous commands (rm -rf /, etc.) are blocked

Agent-Readiness Score (0–100)

The score is based on: content, sections, commands, frontmatter, recommended sections (testing, build, PR), and command safety.

agentmd score
# Agent-readiness score: 75/100

Badge

Add an agent-readiness badge to your README. Use the score directly or fetch from GitHub:

# Static score (e.g. 87)
[![AgentMD Score](http://localhost:3001/api/badge/score?score=87)](http://localhost:3001)

# Dynamic from repo (owner/repo)
[![AgentMD Score](http://localhost:3001/api/badge/score?repo=owner/repo)](http://localhost:3001)

Optional: ?branch=main for non-default branches.

CLI Usage

# Validate AGENTS.md
agentmd validate [path]

# Parse and show structure
agentmd parse [path]

→ CLI Reference