Roast My AGENTS.md (Evidence Edition)

What it does

Roast My AGENTS.md performs a two-stage audit of repository instruction files (AGENTS.md, CLAUDE.md). First it runs a static analysis to identify bloat, duplication, and token-tax. Then it can run controlled A/B evaluations to prove which rules are redundant (non-discriminating) and which genuinely change agent behavior. The result is a ranked list of guilty rules, recommended fixes, and token-savings estimates.

When to use it

Use this skill when you suspect your AGENTS.md or CLAUDE.md is noisy or when you want evidence before pruning configuration. Trigger examples: 'roast my agents.md', 'audit my CLAUDE.md', 'prove my rules are useless', or when preparing a major rewrite of instruction files.

What's included

• Scripts: the repo includes audit and evaluation scripts to run static checks and A/B trials when available (has_scripts=true).
• References: guidance on progressive disclosure, size budgets, and migration notes are included inline in the skill documentation.
• Instructions: the SKILL.md body outlines a step-by-step workflow: static roast, pick suspects for A/B tests, run clean baseline evaluations, restore files, and produce a final verdict with recommended restructuring.

Compatible agents

Designed for developer-facing agent frameworks and code assistants: Claude Code, Cursor, Codex/GitHub Copilot-style tooling, and other agent systems that read AGENTS.md/CLAUDE.md.