Readme rescue
Practical Codex-compatible skills for README, demos, launches, and OSS growth loops
npx -y skills add daewoochen/oss-flywheel-skills --skill readme-rescueAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when a project's README is confusing, bloated, or failing to activate new users. This skill audits the current entry point, rewrites the structure around clarity and quick wins, and preserves technical accuracy while making the project easier to understand.
SKILL.md
2.0 KB, as published. Nobody here has run it
README Rescue
Rebuild a README so a new visitor can understand the project, try it quickly, and decide whether to keep reading.
When to use
- The README is technically correct but hard to scan.
- Important setup or usage steps are buried.
- The project has grown and the docs no longer match the main audience.
- A repo needs clearer positioning before a launch or share.
Workflow
- Audit the current entry path.
- Read the README, docs landing page, examples, and any install commands.
- Identify the intended audience and the actual audience implied by the current docs.
- Find the largest comprehension gaps.
- Unclear headline
- No quickstart
- No example output
- Feature list before problem statement
- Missing architecture or FAQ when users clearly need it
- Rewrite in reading order.
- Put the problem and outcome first.
- Add the fastest path to first success.
- Only then add features, architecture, and reference links.
- Make the examples carry the document.
- Prefer one strong worked example over many vague bullets.
- If the repo is complex, add a minimal example and a deeper one.
- Preserve truth.
- Do not hide limitations.
- If the docs are still blocked on missing product decisions, call that out explicitly.
Expected Deliverables
- A short audit of what is not working
- A new README structure
- Rewritten opening sections when appropriate
- Quickstart and example improvements
- Optional FAQ or architecture section suggestions
Output Style
- Tight and skimmable
- More examples, fewer slogans
- Clear section order with low reader effort
References
- Read references/readme-structures.md when you need reusable section orders or quickstart patterns.
Gives 0 of the 12 instructions most readme changelog skills give
Counted across 471 of the 478 authors here whose files we hold, read 2026-08-06
- follow the Keep a Changelog formatin 31 of 471, across 26 files
- omit empty sectionsin 21 of 471
- Run from the git repository rootin 20 of 471, across 7 files
- save output directly to CHANGELOG.mdin 20 of 471, across 7 files
- Group commits into logical categoriesin 19 of 471, across 6 files
- Review the generated changelog before publishingin 19 of 471, across 6 files
- Apply changelog guidelines and brand voicein 18 of 471, across 5 files
- Exclude internal commits like refactoring and testsin 18 of 471, across 5 files
- Specify date ranges for focused changelogsin 17 of 471, across 4 files
- Convert technical commits into customer languagein 17 of 471, across 4 files
- group commits by conventional commit typein 14 of 471
- insert new entry below unreleased sectionin 14 of 471
Said here and by no other author read
- audit the current entry path
- find the largest comprehension gaps
- put the problem and outcome first
- add the fastest path to first success
- make examples carry the document
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.