Agentsfile — Development skill for Claude Code

agentsfile

**Agent instruction files rot quietly. This checks them against the repo they describe.**

AGENTS.md and CLAUDE.md tell coding agents how a repo works: which files matter, which commands to run, how the project is laid out. Repos move faster than their instruction files. A renamed directory, a deleted script, a guide that was never more than a stub, and the agent following the file wastes its run or invents what the file got wrong. Nothing fails loudly, because nothing ever checked the file against the repo.

agentsfile does that check. It reads the AGENTS.md and CLAUDE.md at a repo root, extracts the backticked paths and the npm, yarn, and pnpm script references, and verifies each one against the actual file tree and the actual package.json. Every finding carries the file, the line, and the exact text it came from. The output is deterministic: sorted findings, no timestamps, the same repo always producing the same report.

What it checks

rule	severity	what it means
NO-FILE	high	Neither AGENTS.md nor CLAUDE.md exists at the repo root.
PATH-MISSING	medium	A backticked span that looks like a relative path does not exist in the repo, as a file or as a directory.
SCRIPT-MISSING	medium	A referenced script (npm run , npm test, yarn , pnpm and friends) is not defined in package.json scripts.
STUB	low	An agent file exists but is empty or under 5 lines long.
NO-PACKAGE-JSON	info	There is no package.json at the repo root (or it does not parse), so script references were not checked.

Verdict rules:

• VALID: no medium or high findings. Low and info findings can be present. Exit code 0.
• DRIFT: at least one medium or high finding. The agent files disagree with the repo. Exit code 1.
• MISSING: neither AGENTS.md nor CLAUDE.md exists at the repo root. Exit code 1.
• Usage errors exit with code 2. A reader that closes the output pipe early ma