← ClaudeAtlas

roast-readmelisted

Roasts only the README and the first five minutes a stranger spends with the project: can they tell what it is, install it and see it work in five minutes? Measures the README with a script (title, pitch length, line of the first command, install and usage sections, broken links), walks the setup on paper, scores it, then rewrites the top of the README and shows the diff before saving. Use when the user says "roast my README", "is my README any good", "would a stranger understand this repo", "fix my README intro", "why does nobody star my repo", or "review my getting started section".
vivekbhange-hub/repo-roast-skill · ★ 0 · Code & Development · score 73
Install: claude install-skill vivekbhange-hub/repo-roast-skill
# roast-readme: the first five minutes Most people decide whether to use a project before they scroll twice. This skill plays that stranger, times their five minutes, roasts every place they would give up, and then does the useful part: rewrites the top of the README so the next stranger does not give up. ## Inputs - A repo path or README path. Default: the current directory. - Mode flag: `--gentle`, none, or `--savage`, same meaning as in roast-repo (`${CLAUDE_SKILL_DIR}/../roast-repo/tone.md`). ## Outputs - `roast/README-ROAST.md`: score, the five-minute timeline, roasts with evidence and fixes. - `roast/README.top.md`: the proposed new top of the README (title through first working command). - The README itself is changed only after the user approves the diff. ## Steps 1. **Measure.** ``` python3 "${CLAUDE_SKILL_DIR}/readme_lint.py" <path> --format md python3 "${CLAUDE_SKILL_DIR}/readme_lint.py" <path> --format json ``` Exit code 1 means there is no README. That is the whole roast; skip to step 5 and write one. 2. **Run the five-minute clock on paper.** Read the README top to bottom as someone who has never seen the project. Record a timeline, one entry per obstacle, each with its README line: - 0:00-0:30: Do I know what this is and who it is for? (title, first paragraph) - 0:30-2:00: Can I install it? Every command the README gives: does the script, file, package name or version it refers to exist in the repo (`package.json` scripts,