gitreadme

---
name: gitreadme
description: Generate a polished README.md for any git repository — local or remote. Use this skill whenever the user says "make a readme", "write a readme", "add a readme", "generate readme", "readme for [url]", "create a readme for this repo", "this repo needs a readme", or references creating documentation for a GitHub/GitLab/git repository. Also triggers on "/gitreadme". Works with the current directory's repo OR a remote URL (e.g., "readme for github.com/user/repo"). After generating, it commits the README automatically.
---

# GitReadme — Generate a README for Any Repo

Arguments passed: `<optional URL or repo path>`

## Argument Handling

- If a URL is provided (e.g., `https://github.com/user/repo` or `github.com/user/repo`), clone it to a temp directory and analyze it there
- If a local path is provided, use that directory
- If no arguments, use the current working directory
- If the current directory isn't a git repo and no URL was given, ask the user what repo they want a README for

## Workflow

### Step 1: Get the Repo

**Remote repo:**
1. Clone to a temp directory: `git clone --depth 1 <url> /tmp/gitreadme-<repo-name>`
2. Work from that directory for analysis
3. After generating the README, push it back (create a branch, commit, push, open PR — or commit directly to main if the user owns it)

**Local repo:**
1. Verify it's a git repo (`git rev-parse --git-dir`)
2. Check if a README.md already exists — if yes, ask: "This repo already has a README. Overwrite it?" Wait for confirmation.
3. Work from the current directory

### Step 2: Analyze the Repo

Gather intelligence about the project by reading files and structure. Do this thoroughly — the README quality depends entirely on how well you understand the project.

**File structure:**
```bash
find . -type f -not -path './.git/*' | head -100
```

**Detect tech stack** by looking for:
- `package.json` → Node.js/JavaScript/TypeScript (read it for name, description, scripts, dependencies)
- `requirements.txt` / `pyproject.toml` / `setup.py` → Python
- `Cargo.toml` → Rust
- `go.mod` → Go
- `pom.xml` / `build.gradle` → Java
- `Gemfile` → Ruby
- `*.sln` / `*.csproj` → C#/.NET
- `Dockerfile` / `docker-compose.yml` → containerized
- `vercel.json` / `next.config.*` → Vercel/Next.js

**Read key files** (if they exist):
- Existing README (to understand what was there before)
- Package manifests (package.json, pyproject.toml, Cargo.toml, etc.)
- Main entry points (index.ts, main.py, src/lib.rs, etc.)
- Config files (tsconfig.json, .eslintrc, Makefile, etc.)
- CI/CD files (.github/workflows/, .gitlab-ci.yml)
- License file
- CONTRIBUTING.md, CHANGELOG.md
- Any docs/ directory

**Git history** (for context):
```bash
git log --oneline -20
git shortlog -sn --no-merges | head -10
```

### Step 3: Generate the README

Write a README.md that feels like it was written by a developer who genuinely cares about the project. Not boilerplate — every section should contain real, specific information from the analysis.

**Structure (adapt based on what's relevant — skip sections that don't apply):**

```markdown
# Project Name

One-line description that explains what this project does and why someone would use it.

## Overview

2-3 sentences expanding on what the project does. What problem does it solve? Who is it for?
If the project has visual output (images, UI, etc.), mention it here.

## Features

- Bullet list of key capabilities
- Derived from actual code, not guesses
- Each feature should be specific and concrete

## Getting Started

### Prerequisites

What needs to be installed before setup (Node.js version, Python version, system deps, etc.)

### Installation

Step-by-step commands to get running. Test these mentally against the package files you read.

### Usage

Show the primary way to use the project:
- CLI commands (if it's a CLI tool)
- Code examples (if it's a library)
- How to run the dev server (if it's a web app)
- How to run it (if it's a script)

## Project Structure

Brief overview of the directory layout — only include this if the project has more than a handful of files. Focus on the directories/files a new contributor would need to understand.

## Tech Stack

List the major technologies, frameworks, and tools used. Be specific about versions only if they matter.

## Contributing

Brief contribution guidelines. If CONTRIBUTING.md exists, point to it. Otherwise, a simple "PRs welcome" with basic instructions.

## License

State the license if one was detected. Link to the LICENSE file.
```

**Writing guidelines:**
- Be concise. Every sentence should earn its place.
- Use the project's actual names, commands, and paths — not placeholders.
- If you're not sure about something, leave it out rather than guessing wrong.
- Code blocks should use the correct language identifier for syntax highlighting.
- Don't add badges unless the repo already has CI/CD set up (then add the appropriate status badge).
- Don't include a table of contents unless the README is very long.
- Match the tone to the project: a fun side project can be casual, an enterprise tool should be professional.

### Step 4: Write and Commit

1. Write the README.md to the repo root
2. Stage it: `git add README.md`
3. Commit:
   ```
   git commit -m "Add README.md

   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
   ```
4. For local repos: done (don't push unless asked)
5. For remote repos: push and report the result

### Step 5: Report

Tell the user what was generated:
```
README.md created and committed for <repo-name>.

Sections: Overview, Features, Getting Started, Project Structure, Tech Stack, License
Based on: <what you found — e.g., "Next.js 16 app with 23 components, Prisma ORM, Clerk auth">
```

## Rules

- **Read before writing.** The quality of the README depends on how well you understand the project. Don't skim — actually read the key files.
- **Don't fabricate.** If you can't determine something from the codebase, don't include it. A shorter accurate README beats a longer inaccurate one.
- **Respect existing work.** If a README already exists, ask before overwriting.
- **Keep it real.** Generic READMEs with placeholder text are worse than no README. Every line should be specific to this project.