readme-doctor
Skill48 starsChanged 17 days agoMITView on GitHub
Reviews a README for the things that make people try a project, covering the opening line, install steps, a runnable example, proof that it works and contribution info, then proposes concrete edits. Use when the user asks to improve a README, wants more stars or users for an open source project, or is preparing a launch.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- rahulrajaram/rahulskillstheir own version, first seen Oct 13, 2026
- JungHoonGhae/skillstheir own version, first seen Mar 10, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- JungHoonGhae/skills★ 4same name
- rahulrajaram/rahulskills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- api-endpoint-testerSkill
- changelog-generatorSkill
- commit-message-writerSkill
- csv-profilerSkill
- dockerfile-linterSkill
- env-file-auditorSkill
- json-diffSkill
- log-analyzerSkill
- meeting-notes-to-actionsSkill
- pr-description-writerSkill
- python-code-smellsSkill
- secure-code-reviewSkill
- skill-authorSkill
- sql-query-reviewerSkill
- todo-extractorSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Check every command and link before recommending them.
- Distinctive: line 37
Prefer showing a real output to describing it.
- Distinctive: line 47
If the README is empty, ask what the project does and who it is for, then draft only the opening line and the install section.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
README doctor
Most visitors decide in under a minute. The README has to answer three questions fast: what is this, does it solve my problem, and how do I try it.
When to use
- The user shares a README and asks for feedback.
- A project is about to be announced on a forum or social media.
- The repository has traffic but few stars or issues.
Review order
- Opening line. One sentence naming the problem and the audience. Reject slogans and buzzwords.
- Proof above the fold. A terminal recording, screenshot or short output sample within the first screen.
- Install. One command that works on a clean machine. State supported platforms and versions.
- First success. A minimal example whose output is shown, so the reader sees the result without running it.
- Why this exists. Two or three sentences on how it differs from the alternatives, with honest limits.
- Features. A short list of things the tool does, written as capabilities, not adjectives.
- Reference. Commands, options and configuration in tables or short sections.
- Project health. Badges for CI and version, license, contributing guide, roadmap, how to report bugs.
Rules
- Check every command and link before recommending them. Do not suggest claims that cannot be shown.
- Cut anything that sounds like marketing and does not carry information.
- Prefer showing a real output to describing it.
- Suggest a repository description and topics that match what people search for.
Output
Return a prioritized list: the three changes with the most impact first, each with a before and after snippet. End with a short checklist of what is still missing.
Errors
If the README is empty, ask what the project does and who it is for, then draft only the opening line and the install section.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.