Roast My AGENTS.md (Evidence Edition)

Trust Score 87/100

Run a data-backed audit of AGENTS.md/CLAUDE.md files: surface redundant rules, run A/B evals to prove which instructions are unnecessary, and recommend concise

triggers:roast my agents.mdaudit AGENTS.mdeval roastaudit CLAUDE.mdprove my rules are useless

GitHub SKILL.md

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.

Audit Summary

Roast My AGENTS.md is a well-crafted skill that audits AI instruction files for bloat, redundancy, and anti-patterns. The SKILL.md is detailed with three clear phases (static roast, A/B evidence, verdict). The bundled roast-audit.js script is a thorough static analyzer using only Node built-ins, but was skipped by the runner due to .js extension. No security concerns — no network calls, no credentials, no destructive commands.

Watch Out

Script runner skips .js files — only .py is supported
Phase 2 (A/B testing) requires moving user config files and spawning agents, which needs careful handling
The skill references {this-skill-path} and {project-root} placeholders that must be substituted at runtime

Notes

Innovative skill with a unique evidence-based approach to auditing instruction files. The roast/humor angle is engaging and the A/B testing methodology is well-designed. Code quality is strong — clean JS with good error handling and no dependencies. Architecture follows the skill spec well. Main gap is the .js script can't run in the current audit runner which only supports .py.

Information

Repository: skills
Stars: 7

Trust Score

Overall87

Security95

Code Quality82

Architecture74

Usefulness78

Related Skills

Readwise Reader Document Management

Manage Readwise Reader documents: list, save, search, move, tag, highlight, export and bulk-edit via official and custom CLIs.

ezBookkeeping API Tools

Command-line API tools for ezBookkeeping: record and query transactions, retrieve accounts/categories/tags, and fetch exchange rates for self-hosted personal fi

Tmux Bridge

Give an agent controlled access to a local tmux terminal bridge so it can run shell commands, capture output, and manage sessions on the user's machine.

ArcKit Architecture Conformance

Run a systematic architecture conformance assessment that compares ADRs and principles against HLD/DLD artifacts to surface drift, violations, and technical deb

Vibe Security Auditor

Audits AI-generated codebases for critical security flaws like exposed keys, broken RLS, and insecure payment flows.

SourceSage CLI

Generate concise, LLM-friendly repository summaries (Markdown) using the SourceSage CLI — supports lite mode, language switching, and targeted repo analysis.

Nit (Nitter CLI)

Terminal client to browse tweets, view profiles, and search posts via Nitter instances without opening a browser.

hn — Hacker News CLI

Terminal-based Hacker News client with a CLI and optional interactive TUI for browsing top/new/best/ask/show/jobs stories, viewing threads with nested comments,

Back to Skills