roast-readmelisted
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,