readme-generator
Skill67 starsChanged 59 days agoMITView on GitHub
Generate, audit, or improve a project README following a 15-section structure (Title, Table of Contents, About, Features, Tech Stack, Architecture, Project Structure, Getting Started, Configuration, Security, How to Contribute, What's Next, License, Acknowledgements, Author) with Mermaid diagrams for architecture and flows. Use this skill whenever the user asks to "write a README", "create a README", "draft a README", "generate README.md", "scaffold project docs", "document this repo", "improve my README", "audit my README", "what should go in my README", or starts a new repository and needs documentation. Also trigger on phrases like "the README is bare", "this project has no docs", "fill in my README sections", or any request that produces or reviews a top-level repository README. The skill defaults to Mermaid for diagrams because it renders natively on GitHub, GitLab, Bitbucket, and most modern Markdown viewers — no external image hosting required.
37 other projects use a version of this.
Adopted by
Most recently taken up by
- dmccreary/ibook-skillstheir own version, first seen Nov 3, 2026
- Sagargupta16/agent-recipestheir own version, first seen Nov 1, 2026
- jaskirat1616/grok-skillstheir own version, first seen Nov 1, 2026
- wedsamuel1230/arduino-skillstheir own version, first seen Nov 1, 2026
- Tejas9406/vibe-coding-ostheir own version, first seen Nov 1, 2026
- weininghui/skillstheir own version, first seen Oct 30, 2026
Used with
Projects with it also use book-chapter-generator, concept-classifier and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
vishalsachdevSkillbook-chapter-generator
This skill generates a structured chapter outline for intelligent textbooks by analyzing course descriptions, learning graphs, and concept dependencies. Use this skill after the learning graph has been created and before generating chapter content, to design an optimal chapter structure that respects concept dependencies and distributes content evenly across 6-20 chapters.
Also in 3 projects that use this
- vishalsachdevSkill
concept-classifier
Create an interactive classification quiz MicroSim using p5.js where students read scenarios and classify them into the correct category from multiple choice options. Uses a data.json file for easy question editing. Ideal for teaching students to recognize patterns, identify types, or categorize examples across any subject domain.
Also in 3 projects that use this
JayRHaSkillchangelog-keeper
Maintains a CHANGELOG.md in the Keep a Changelog format with Semantic Versioning, grouping user-facing entries under Added/Changed/Deprecated/Removed/Fixed/Security and cutting dated releases from an Unreleased section. Use this skill when the user asks to "update the changelog", "add a changelog entry", "cut a release", "bump the version", "what changed since the last release", or to create/clean up a CHANGELOG.md or release notes.
Also in 3 projects that use this
ATOM00blueSkillerror-message-explainer
Explains errors, stack traces, exceptions, and cryptic build/runtime messages in plain language, identifies the root cause, and gives a concrete fix. Use when the user pastes an error, stack trace, traceback, panic, compiler error, or failing log and asks what it means, why it happens, or how to fix it.
Also in 3 projects that use this
peopleforresterSkillrefactoring-guide
Safe refactoring patterns and techniques. Use when the user wants to improve code structure, reduce duplication, or make code more maintainable without changing behavior. Emphasizes incremental changes with test coverage.
Also in 3 projects that use this
- +7 more from vishalsachdev
Other versions37 projects use a version of this.
Word for word · 1
- anchildress1/awesome-ai★ 67100% same
Edited · 0
None found.
Wrote their own version · 36
- serejaris/personal-corp-os★ 243same name
- serejaris/ris-claude-code★ 243same name
- dmccreary/claude-skills★ 110same name
- dmccreary/ibook-skills★ 110same name
- MCDxAI/minecraft-dev-mcp★ 47same name
- geekjourneyx/readme-generator★ 44same name
- glincker/claude-code-marketplace★ 37same name
- johnqtcg/awesome-skills★ 30same name
- jshsakura/awesome-opencode-skills★ 30same name
- wedsamuel1230/arduino-skills★ 28same name
26 more not listed
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 repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- changelog-writerSkill
- eslint-plugin-configuringSkill
- generate-commit-messageSkill
- pr-comment-reviewSkill
- test-writerSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 30 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 42
Start from assets/template.md.
- Very specific: line 43
No signal → <!-- TODO: describe X -->.
- Distinctive: line 66
Every badge must say something the README body doesn't say faster.
- Distinctive: line 68
Default to zero. License is the only near-default on a public repo.
- Distinctive: line 70
Never restate Tech Stack ("Built with React", "Uses TypeScript").
- Distinctive: line 71
Verify every claim and every link target from repo state.
“Common” is measured: kept by at least 6 in 10 of the 30 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Readers: a stranger opening the repo cold, and the author six months later. Write for scanning, not reading.
| File | Use for |
assets/template.md | Starting point for every new README |
references/sections.md | Include / avoid / skip rules per section — read before drafting or judging any section |
references/mermaid-guide.md | Diagram type, shapes, arrows, render-target fallback |
assets/mermaid-examples.md | Diagram patterns to adapt |
Section selection
Project type unknown → ask before generating. A wrong-shape README is wasted work.
| Project type | Always include | Usually skip |
| Public open-source (apps, libraries) | All 15 | — |
| Internal team service | Title, About, Tech Stack, Architecture, Getting Started, Configuration, Security, Author | Acknowledgements, What's Next (use the issue tracker) |
| CLI tool / library | Title, About, Features, Tech Stack, Getting Started, Configuration, How to Contribute, License, Author | Architecture, Project Structure |
| Solo experiment / sandbox | Title, About, Getting Started | Most others |
| Documentation-only / tutorial repo | Title, About, Table of Contents, Project Structure, License, Author | Getting Started, Configuration, Security |
Order is fixed: Title and Introduction · Table of Contents · About · Features · Tech Stack · Architecture · Project Structure · Getting Started · Configuration · Security · How to Contribute · What's Next · License · Acknowledgements · Author.
Separate sections with ---.
Workflow
Fresh README
- Collect before asking: project name, one-sentence purpose, project type, primary stack.
Pull from
package.json,pyproject.toml,Cargo.toml,go.mod, and the top-level listing when the repo is readable. - Start from
assets/template.md. Fill every section you have signal for. - No signal →
<!-- TODO: describe X -->. Never fabricate install steps, config, or license. - Architecture diagram: Mermaid, type chosen from
references/mermaid-guide.md. - Present the draft with every TODO listed. Never call a placeholder-heavy draft done.
Improve existing
- Map existing content onto the 15 sections. Keep the user's section names when reasonable ("Setup" stays "Setup").
- List missing and weak sections before rewriting. Never restructure silently.
- Targeted edits only. The user's specific phrasing beats generic replacement copy.
Audit only
Per section: ✓ present · ~ partial · ✗ missing. One concrete fix for each ~ and ✗. No replacement content unless asked.
Diagrams
Mermaid for every diagram. Never draw.io or Lucidchart screenshots.
Badges
Every badge must say something the README body doesn't say faster.
- Default to zero. License is the only near-default on a public repo.
- Cap ~3, hard ceiling 5.
- Never restate Tech Stack ("Built with React", "Uses TypeScript").
- Verify every claim and every link target from repo state. Unverifiable → omit.
- One horizontal line, space-separated. Break lines only to group (status row above package-metadata row).
Live-count badges — omit unless the number is non-trivial today:
| Badge | Omit if |
| Stars | < ~50, or unverifiable |
| Forks | < ~10 |
| Contributors | solo, or < ~3 |
| Downloads / installs | unpublished, or low/zero traffic |
| Open issues / PRs | new repo, no triage history |
| Coverage % | no published coverage report URL |
| Build status | no public CI workflow at that path |
Candidates worth considering, each only when its condition holds:
| Badge | Condition |
| License | Always relevant |
| CI status | Workflow exists and runs on main |
| Security scan (CodeQL, Snyk) | Actually wired up |
| Latest release / version | Published package with a moving version |
| Conventional Commits | commitlint actually enforced |
Everything else (framework, runtime, "built with X") belongs in Tech Stack.
Never
- Generic filler ("powerful, modern, cutting-edge"). No specifics → placeholder.
- Implementation detail in About or Features.
- Getting Started the user hasn't run — mark it needs verification.
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.