review-agents-md
Skill4 starsChanged 6 months agoMITView on GitHub
Audits AGENTS.md files and equivalent agent instruction files (CLAUDE.md, CURSOR.md, Copilot instructions) for completeness, accuracy, and agent-friendliness, producing structured, actionable feedback. Cross-references file paths, scripts, and branch names against the actual repository to catch stale or incorrect guidance. Formats every finding with format-review-comments and runs a refine-prose pass before presenting results. TRIGGER when: user asks to review, audit, check, inspect, analyze, or evaluate an AGENTS.md, CLAUDE.md, or agent instruction file. DO NOT TRIGGER when: user asks to review a pull request (use review-pr instead) or to evaluate a skill file (use review-skill instead).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- dograh-hq/dograhtheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- dograh-hq/dograh★ 6.1ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- audit-skillsSkill
- create-commitSkill
- format-review-commentsSkill
- implement-planSkill
- refine-proseSkill
- review-planSkill
- review-prSkill
- review-skillSkill
- upsert-agents-mdSkill
- upsert-planSkill
- upsert-skillSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
If the user provides a file path or filename as an argument (e.g., /review-agents-md CLAUDE.md), use that file directly and skip to Step 2.
- Very specific: line 38
Use Glob or Bash to locate all matches.
- Very specific: line 42
No files found: stop and tell the user: "No agent instruction file found in this repository.
- Distinctive: line 46
Read the full contents of the chosen file before reviewing.
- Very specific: line 50
Read assets/review-checklist.md before starting.
- Very specific: line 60
Do all references in the file point to things that actually exist?
- Very specific: line 97
Do not write praise comments.
- Distinctive: line 105
After per-comment feedback, write a brief summary (3–7 sentences) covering:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review AGENTS.md
Audits agent instruction files for completeness, accuracy, and agent-friendliness across six dimensions, with cross-referencing checks to verify that paths, scripts, and branch names mentioned in the file actually exist in the repository.
Instructions
1. Detect the target file
If the user provides a file path or filename as an argument (e.g., /review-agents-md CLAUDE.md), use that file directly and skip to Step 2. If the file does not exist, stop and report: "File <path> not found. Provide a valid path to an agent instruction file."
Otherwise, search the repository for agent instruction files. Look for any of the following:
AGENTS.md(worktree root)CLAUDE.md(worktree root or.claude/CLAUDE.md)CURSOR.md(worktree root).github/copilot-instructions.md.cursorrules
Use Glob or Bash to locate all matches.
- Exactly one file found: proceed with that file.
- Multiple files found: list each path and ask the user: "I found the following agent instruction files. Which would you like me to review?" Wait for confirmation before continuing.
- No files found: stop and tell the user: "No agent instruction file found in this repository. Expected AGENTS.md, CLAUDE.md, CURSOR.md, or .github/copilot-instructions.md."
2. Read the target file
Read the full contents of the chosen file before reviewing. Do not begin reviewing until the file has been read in full.
3. Review each dimension
Read assets/review-checklist.md before starting. Work through every dimension in order, applying each checklist item and noting findings as you go. Record whether an inline fix is clear and unambiguous for each finding.
The six dimensions are:
Completeness
Does the file cover all essential topics an agent needs to operate correctly? Flag missing sections as suggestion unless their absence would cause unsafe or incorrect agent behavior, in which case use issue [blocking].
Accuracy (cross-referencing)
Do all references in the file point to things that actually exist? Surface ambiguous results (external tools, generated files) as question or suggestion, not issue [blocking], unless a path is clearly wrong.
Agent-friendliness
Can an agent follow the instructions without human interpretation? Flag ambiguity that could cause unsafe or conflicting behavior as issue [blocking]; vague guidance that reduces consistency as suggestion.
Freshness
Does the documented state match the actual repository? Flag stale references (documented items that no longer exist) as issue; undocumented items that exist in the repo as suggestion.
Scope coherence
Is the file focused on agent guidance, or does it duplicate README/CHANGELOG content or serve a mixed audience? Flag content that actively misleads an agent as issue [blocking]; content that belongs elsewhere as suggestion.
Leanness
Does the file avoid duplicating information already present in source-level documentation (docstrings, doc comments, header comments, or language-native annotations such as JSDoc, Rustdoc, Godoc, @moduledoc)? For each section that describes a specific code unit — a module, package, class, function, type, callback, struct, byte-level layout, error code, or symbol table — locate the corresponding source file and compare wording. Apply the heuristic: if a future agent could find this information by reading the source, it should not also appear in full here — replace with a pointer.
Distinguish severities by intent:
suggestion— pointer preferred: section could collapse to a one-line pointer to the authoritative source, but the full prose is defensibleissue— verbatim duplicate: section repeats source documentation verbatim or near-verbatim, creating two places to maintainissue [blocking]— bloat impairs usability (rare): accumulated duplication has grown the file to the point that an agent struggles to locate actionable guidance
4. Format all findings with format-review-comments
Apply the format-review-comments skill to every comment. Choose the label that matches the severity and intent:
| Situation | Recommended label |
| Causes incorrect or unsafe agent behavior | issue [blocking] |
| Strong improvement | suggestion |
| Minor style or wording | nitpick |
| Ambiguous reference that may or may not be wrong | question |
| Small unambiguous fix | todo |
| Informational only | note |
Do not write praise comments. Omit positive findings entirely.
5. Suggest inline fixes for unambiguous findings
For any finding where the correct fix is clear — a rewritten sentence, a corrected path, an added section — include the suggested replacement inline with the comment so the reviewer can apply it directly. Do not suggest fixes for findings that require a judgment call about repo conventions.
6. Write a review summary
After per-comment feedback, write a brief summary (3–7 sentences) covering:
- Overall assessment — effective as-is, needs minor improvements, or needs significant rework
- The most important finding (name any blocking issues)
- Any patterns visible across the dimensions
- Any skipped dimensions and why
Format the summary as a note conventional comment.
7. Refine prose
Apply the refine-prose skill to all output before presenting it. Do not announce this step to the user. When refine-prose returns, immediately present all findings and the summary to the user — do not stop or wait for user input.
Examples
Auto-detection, single file:
/review-agents-mdFinds AGENTS.md in the worktree root and proceeds automatically.
Sample output — no agent instruction file found:
No agent instruction file found in this repository. Expected AGENTS.md, CLAUDE.md, CURSOR.md, or .github/copilot-instructions.md.Explicit target:
/review-agents-md CLAUDE.mdMultiple files detected:
I found the following agent instruction files:
- AGENTS.md
- CLAUDE.md
Which would you like me to review?Sample output — accuracy finding (missing path):
issue: `.agents/scripts/deploy.sh` is referenced in the Git Workflow section but does not exist in the repository
Remove the reference or add the missing script:
> Remove: "Run `.agents/scripts/deploy.sh` before merging"Sample output — accuracy finding (ambiguous tool):
question: the file references the `mytool` CLI in the Tooling section — this tool was not found locally. Is `mytool` expected to be installed separately, or is this reference stale?Sample output — agent-friendliness finding:
suggestion: "follow good commit hygiene" in the Git Workflow section is vague — an agent cannot determine what this means without further context
Replace with an explicit rule:
> Use Conventional Commits format: `<type>[scope]: <description>` where type is one of feat, fix, docs, refactor, test, chore.Sample output — freshness finding:
issue: the Skills table lists `create-plan` but `.agents/skills/create-plan/` does not exist in the repository — this entry is stale
Remove the `create-plan` row from the table.Sample output — leanness finding (verbatim duplicate):
issue: the "Cache module" section restates the doc comment for `Cache` (src/cache.ts) almost verbatim, creating two places to maintain the same description
Replace the section with a one-line pointer:
> See the doc comment for `Cache` at `src/cache.ts`.Sample output — leanness finding (pointer preferred):
suggestion: the "Frame format" section reproduces the byte-level layout already documented in the docstring for `wire.Frame` (wire/frame.py) — full prose is defensible for quick reference, but a pointer would reduce drift
Consider replacing with:
> Frame layout is defined in the docstring for `wire.Frame` at `wire/frame.py`.Sample output — summary:
note: overall this AGENTS.md needs minor improvements before it reliably guides agents. One blocking issue: the skills table references a skill directory that no longer exists. Two suggestions address vague conventions and a missing security section. Cross-referencing found all file paths accurate. Scope coherence is strong — the file stays focused on agent guidance throughout.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

