7y-9/agentsmd-check

agentsmd-check is a command line tool that scans a repository's AGENTS.md file and checks whether it is accurate, safe, and actually useful for AI coding agents to follow. AGENTS.md has become a kind of README written specifically for AI agents, describing a project's build commands, test commands, code style, and safety rules. The problem this tool addresses is that these files often go stale over time: they might tell an agent to run npm test when the project switched to pnpm, point to a documentation file that was deleted, or reference a Makefile target that no longer exists. The current version checks several things. It looks for a missing root AGENTS.md file, checks markdown formatting like headings and code blocks, verifies that referenced file paths actually exist, compares package manager lockfiles against the commands the file tells agents to run, flags dangerous patterns such as piping a downloaded script straight into sh, and checks whether important sections like testing or safety notes are missing entirely. The goal is not to grade writing quality, but to answer basic questions: can an agent actually follow these instructions, are the commands real, are the referenced files real, and are the instructions safe to run. It runs from the command line and requires Node.js 24 or newer. Once installed, running the check command prints a report listing each problem, the line it was found on, why it is a problem, and a suggested fix. It also supports JSON output for integrating with other tools, and a flag to fail the run on warnings, not just errors. A ready to use GitHub Actions configuration is included so the check can run automatically on every push or pull request. The project explicitly avoids running or hosting coding agents itself, replacing existing project documentation, managing prompts across a team, or forcing one universal AGENTS.md format on every project. It also will not silently rewrite a file without first showing the proposed change. This is described by its author as their first open source project, and they are looking for real examples of stale AGENTS.md instructions, false positives, and rule ideas grounded in an actual repository. It is released under the Apache 2.0 license.