github-readme-generator

name	github-readme-generator
description	Generate a polished, shareable GitHub README for any project. Structured with banner, badges, comparison tables, quick start, and architecture. Use when: "generate README", "create README", "polish my README", "make my repo look professional", "README template".

GitHub README Generator

Generate a polished, shareable GitHub README for a project following proven structures that maximize engagement and clarity.

Arguments

• $ARGUMENTS — Project directory path or GitHub repo name

Instructions

You are helping create a high-quality GitHub README that is both informative and shareable on social media.

Step 1: Understand the Project

If a directory path is given, explore the codebase:

• Read existing README if any
• Identify the main language, framework, and dependencies (check package.json, requirements.txt, Cargo.toml, go.mod, etc.)
• Understand what the project does, how to install/run it, and key features
• Look for existing assets (screenshots, banners, icons)

If a GitHub repo name is given:

• Detect the user's GitHub account via gh api user if only a repo name is provided
• Fetch the repo metadata and README via gh api

Step 2: Generate the README

Use this structure. Adapt sections as appropriate for the project size — a small script needs fewer sections than a full application.

<p align="center">
  <img src="assets/banner.png" alt="[Project Name]" width="100%">
</p>

<p align="center">
  <strong>[One-line tagline — what it does in plain English]</strong>
</p>

<p align="center">
  [Badges: platform, language version, license, download/install link]
</p>

---

**[Project Name]** is a [type of tool] that [what it does]. [One sentence on what makes it different].

[Optional: built with X. No admin rights / no dependencies / single file / etc.]

<p align="center">
  <img src="assets/screenshot.png" alt="[Description]" width="600">
</p>

## Why [Project Name]?

[Problem-solution comparison table OR 2-3 paragraphs explaining the motivation]

| Problem | How others solve it | How [Project Name] solves it |
|---------|--------------------|-----------------------------|
| ... | ... | ... |

## Features

- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description

## Quick Start

### Option 1: [Easiest method — download/install]

1. Step one
2. Step two
3. Done

### Option 2: [From source / package manager]

\`\`\`bash
commands here
\`\`\`

## How It Works

[Brief architecture explanation — ASCII diagram, flowchart, or text description]

## Configuration

[If applicable — flags, config files, environment variables]

## Comparison

[If applicable — feature comparison table against alternatives]

| Feature | This tool | Alternative A | Alternative B |
|---------|:---------:|:-------------:|:-------------:|
| ... | ... | ... | ... |

## System Requirements

[Platform, runtime, dependencies]

## Building from Source

[If applicable — build commands, test commands]

## Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

## License

[License type] — see [LICENSE](LICENSE) for details.

Step 3: Adapt to Project Size

• Small script/utility (under 200 lines): Skip "How It Works", "Configuration", "Comparison", "Building from Source". Keep it concise.
• Medium project: Include most sections but keep them brief.
• Full application: Use all sections. Add architecture diagrams and detailed configuration docs.

Step 4: Provide Additional Recommendations

After generating the README, suggest:

• Social preview image concept (1280x640) for GitHub repo Settings > Social preview
• Badge URLs appropriate for the project (shields.io format)
• Missing assets the user should create (banner image, screenshots, demo GIF)
• GitHub Release — suggest creating one if none exists
• Topics — suggest GitHub repo topics for discoverability

Rules

• Match the tone to the project's complexity
• Use tables for comparisons, bullet points for features, code blocks for commands
• Keep Quick Start to 3 steps or fewer for the easiest path
• Write in second person ("you") for instructions
• Do NOT add emojis to the README unless the user asks — keep it clean and professional
• Present the generated README in a code block so the user can copy it directly
• If an existing README exists, note what's already good and only suggest additions