review-agents-md_skill

Overview

This skill creates and refactors AGENTS.md files that are minimal, focused, and follow progressive disclosure. I keep the root file tiny—only what every agent needs—and move domain rules into linked docs or agent skills. The goal is better agent behavior by lowering instruction noise and token cost.

How this skill works

I detect whether AGENTS.md or CLAUDE.md exists and propose fixes (create, symlink, or merge). I read or build a one-sentence project description, record nonstandard package/build/test commands, estimate token cost, and extract only the essentials for the root file. I then produce the new AGENTS.md, any auxiliary docs for progressive disclosure, and a changelog of removed or relocated content with reasons.

When to use it

• Project has no AGENTS.md at the root (proactive check)
• Create a new AGENTS.md from scratch
• Refactor a bloated or contradictory AGENTS.md
• Review agent configuration when CLAUDE.md is missing or mis-symlinked
• Set up AGENTS.md for a monorepo with per-package rules

Best practices

• Keep root AGENTS.md minimal: project one-liner, package manager if nonstandard, and nonstandard build/test commands
• Use progressive disclosure: link to docs/ files or agent skills for domain specifics
• Never document file paths or exhaustive file trees in the root file
• Avoid obvious, vague, or opinionated rules—delete or move them
• Make CLAUDE.md a symlink to AGENTS.md; do not maintain a standalone CLAUDE.md

Example use cases

• Generate a 6-line AGENTS.md for a new repo (project purpose, package manager, special commands, pointers)
• Refactor an existing AGENTS.md into a minimal root plus docs/TYPESCRIPT.md and docs/TESTING.md
• Detect a standalone CLAUDE.md and replace it with a symlink to AGENTS.md
• Create nested AGENTS.md files for a monorepo root and per-package overrides
• Produce a list of removed/relocated items with rationale for a PR description