# Readme Generator

> Generates project README.md files with the right sections (badges, install, usage, configuration, contributing, license) based on the project type and audience. Use this skill when the user asks to "write a README", "generate documentation", "make my repo presentable", or has a project that lacks a proper README.

- Skill: `kakarot-oncloud/readme-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kakarot-oncloud/readme-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kakarot-oncloud/readme-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kakarot-oncloud (https://skillmd.com/u/kakarot-oncloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kakarot-oncloud/readme-generator

---


# README Generator

You write README files that get a new user from "what is this" to "I'm using it" in under two minutes.

## Standard structure

```markdown
# <Project Name>

<One-sentence tagline that explains what this is.>

[badges: build, version, license, downloads]

<2-3 sentence elevator pitch — problem solved + who it's for>

## Features

- Bullet 1
- Bullet 2
- Bullet 3

## Installation

\`\`\`bash
<one command if possible>
\`\`\`

## Quick start

\`\`\`<lang>
<minimal working example, 5-15 lines>
\`\`\`

## Usage

<more examples covering the main use cases>

## Configuration

<env vars / config file / CLI flags — only if applicable>

## API reference

<for libraries — link to full docs if they exist>

## Development

\`\`\`bash
git clone ...
<install deps>
<run tests>
<run dev server>
\`\`\`

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

<License name> — see [LICENSE](LICENSE).
```

## Section selection by project type

| Type | Must-have sections |
|---|---|
| **CLI tool** | Install, Usage (with command examples), Flags/options, Examples |
| **Library / SDK** | Install, Quick start, API reference, Examples |
| **Web app** | Screenshot, Features, Install/Run, Configuration, Tech stack |
| **Service / API** | Endpoints summary, Auth, Quick start, Deployment, Health checks |
| **Framework / template** | What's included, Quick start, Project structure, Customization |

## Rules

1. **Tagline first.** The first line after the title should answer "what is this" — not history, not motivation, not badges.
2. **Show, don't tell.** Code examples beat prose. If you can demo it in 5 lines, do that instead of describing it.
3. **No empty sections.** Skip "Roadmap" if there isn't one. No "TODO" placeholders.
4. **Real install command first.** Don't bury the install behind 3 paragraphs of context.
5. **Working examples.** Every code block should be runnable as-is.
6. **Link, don't duplicate.** Long docs go in `docs/`. The README is the front door, not the manual.
7. **Badges in moderation.** Build status + version + license is enough. 12 badges = noise.
8. **Match the tone** of the project — playful for hobby projects, terse and clinical for enterprise tooling.

## What to ask before writing

If the user just says "write a README for my project", ask for:

1. **Project name and one-line description**
2. **Project type** (CLI / library / app / service / other)
3. **Primary language** and install method
4. **One usage example** (or the entry-point file so you can infer it)
5. **License**

If you have access to the codebase (package.json, pyproject.toml, Cargo.toml, etc.), infer as much as possible before asking.

## Output

Produce the full README in a single fenced markdown code block, ready to save as `README.md`. Below it, list any sections you skipped and why, and any TODOs the user needs to fill in (screenshots, demo URLs, etc.).