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.

```markdown
<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