Clean README is a convention for clear, consistent open-source project READMEs. It gives maintainers and AI assistants a predefined section order, recognizable emoji headings, and project-specific headers made with GitHub Repo Banner.
Use it for a fresh project or to bring an existing README into a familiar structure while preserving the project's identity and important guidance.
Specification · Quick reference · Examples
- A defined reading order: introduce the project, show its value, guide first use, then explain deeper details and community participation.
- Exact section names and emojis: readers know where to find setup, usage, support, and credits.
- Sections selected by context: required topics stay consistent; configuration, deployment, demos, and sponsorship appear when appropriate.
- Context-driven headers: banner colors, typography, and copy reflect the project's purpose, branding, and audience.
- Practical adoption guidance: apply the same convention to apps, libraries, CLIs, bots, skills, and documentation projects.
- Evidence-based writing: use real commands and project facts; preserve warnings, licensing, attribution, and sponsor commitments.
No installation is needed to use the convention manually.
- Read the section catalog.
- Inspect your project's existing README, scripts, examples, license, and branding.
- Keep the required sections and include conditional sections that match the project.
- Generate a header with GitHub Repo Banner, using the project's context to choose its theme.
- Write the content, then use the conformance checklist.
For an existing README, follow the migration walkthrough and check links affected by renamed headings. For a new project, describe its actual status and clearly label planned capabilities.
Identity → value → first use → deeper guidance → community → credits
The complete catalog defines 16 ordered positions, including the opening header. A small project can use fewer sections when conditional and optional topics do not apply.
For example, a library without hosting or sponsors starts with its title, banner, introduction, and features; guides installation and usage; then closes with contribution guidance, support, license, and credits. The library example shows that structure with content.
| Project context | Apply the convention |
|---|---|
| A bot has a supported hosting path | Include 🚢 Deployment. |
| A project has user-facing settings | Include ⚙️ Configuration when they extend beyond minimal first setup. |
| A sponsor is publicly acknowledged | Include 💎 Sponsors & Partners near the introduction. |
| Maintainers accept voluntary funding | Optionally include 💖 Support the Project near the end. |
| A convention has no runtime | Explain adoption under 🚀 Getting Started and application under 📖 Usage. |
Keep the exact H2 names, emojis, and relative order. Place project-specific detail in H3 subsections or linked guides.
Ask an assistant to read this repository's specification and apply it to your project, preserving important existing information. The convention is the source of truth for both manual and assisted adoption.
An installable Clean README skill and its Clean Workflow integration are planned follow-up work. This repository currently provides the convention and examples; there are no skill installation commands yet.
- Full specification: mandatory rules, section definitions, banner guidance, adoption, and edge cases.
- Quick reference: section order and a compact checklist.
- Example gallery: complete teaching examples for different project types.
- Migration walkthrough: preserve existing content while adopting the structure.
- Clean Workflow: the wider family of development conventions and skills.
This is a documentation project. To validate changes locally, use Node.js 22 or newer and npm:
git clone https://github.com/wgtechlabs/clean-readme.git
cd clean-readme
npm ci
npm run lintMarkdown lint checks run in GitHub Actions. They check Markdown formatting; they do not establish factual accuracy, section conformance, working installation commands, or banner appearance. Review those against the specification before submitting changes.
Proposals, clearer examples, and corrections are welcome. Read CONTRIBUTING.md before opening a pull request.
This repository follows Clean Flow, Clean Commit, and Clean Labels. Create work branches from dev and target pull requests at dev.
Search existing issues before opening a convention issue or proposal. Include the relevant section and an example of the ambiguity or improvement.
For questions about applying the convention, open an issue describing the project type and the decision you need help with. Avoid including credentials or private project material.
Participation is covered by the Code of Conduct.
Clean README is licensed under the MIT License.
Created by Waren Gonzaga under WG Technology Labs, with contributions from the community.