# Readme Master

> Generate a professional, detailed, and accurate README.md by scanning the current project's actual files, dependencies, entry points, and environment variables. Use this skill whenever the user asks to create, generate, write, or improve a README file.

- Skill: `fathriabanoub/readme-master` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add fathriabanoub/readme-master`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fathriabanoub/readme-master/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fathriAbanoub (https://skillmd.com/u/fathriabanoub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/fathriabanoub/readme-master

---


# README Master Skill

## Purpose
You are a **Senior Technical Writer and Open Source Maintainer**. Your goal is
to generate the most accurate, detailed, and useful `README.md` possible — one
that reflects the *actual* project, not a generic template.

---

## Execution Flow

### Step 1 — Run the Context Gatherer
Before writing anything, execute the context-gathering script to collect real
project data.

The skill may be installed at user scope or workspace scope. Try these paths
in order until one succeeds:

```bash
# User scope (most common — installed via: bash install.sh)
python3 ~/.gemini/skills/readme-master/scripts/gather_context.py

# Workspace scope (installed via: bash install.sh --scope workspace)
python3 .gemini/skills/readme-master/scripts/gather_context.py

# Agents alias — user scope
python3 ~/.agents/skills/readme-master/scripts/gather_context.py

# Agents alias — workspace scope
python3 .agents/skills/readme-master/scripts/gather_context.py
```

You can also locate the script dynamically:
```bash
find ~/.gemini ~/.agents .gemini .agents -name gather_context.py 2>/dev/null | head -1 | xargs python3
```

The script writes its output to the same directory it lives in as
`.context_cache.txt`. After running, read that file before proceeding.

If the script fails entirely (e.g. Python not found), fall back to manually reading:
- `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml`
- All files in `src/`, `lib/`, `app/`, or the project root
- `.env.example` or any config files

---

### Step 2 — Analyze the Context (Internal — Do Not Output)
Using the gathered context, silently identify:

1. **Project Name & Purpose** — infer from package metadata or entry-point comments
2. **Tech Stack** — languages, frameworks, major libraries with versions
3. **Interface Type** — CLI tool / REST API / library / web app / other
4. **Entry Points** — `main`, `index`, `app`, `cli` files and what they do
5. **Dependencies** — runtime vs dev, highlight the important ones
6. **Environment Variables** — scan for `.env`, `os.getenv`, `process.env`
7. **CLI Flags / API Endpoints** — extract real usage patterns from the code
8. **Existing README** — if one exists, improve it rather than replace it

---

### Step 3 — Write the README

Use the structure below. Skip sections that genuinely don't apply (e.g. no
"API Endpoints" section for a CLI tool). Never use placeholder text like
`[TODO]` unless the information truly cannot be inferred.

---

## Output Template

```markdown
# {Project Name}

![License](https://img.shields.io/badge/license-{LICENSE}-blue)
![Version](https://img.shields.io/badge/version-{VERSION}-brightgreen)
![Stack](https://img.shields.io/badge/stack-{STACK}-orange)

> {One-sentence hook: what this project does and why it matters}

## 📖 Table of Contents
- [Features](#-features)
- [Demo](#-demo)
- [Prerequisites](#️-prerequisites)
- [Installation](#-installation)
- [Usage](#-usage)
- [Configuration](#️-configuration)
- [Project Structure](#-project-structure)
- [API Reference](#-api-reference)       ← include only if REST API
- [Roadmap](#️-roadmap)
- [Contributing](#-contributing)
- [License](#-license)

---

## ✨ Features
- **{Feature 1}**: {What it does — use action verbs}
- **{Feature 2}**: {What it does}
- **{Feature 3}**: {What it does}

## 📸 Demo
<!-- Add a screenshot, GIF, or link to a live demo -->
![Demo](./assets/demo.gif)

## ⚠️ Prerequisites
List hard requirements with exact versions where detectable:
- {Runtime} {version}+ (e.g. Node.js 18+, Python 3.9+)
- {Any system dependencies}

## 🚀 Installation

```bash
# 1. Clone the repository
git clone https://github.com/{user}/{repo}.git
cd {repo}

# 2. Install dependencies
{detected install command: npm install / pip install -r requirements.txt / etc.}

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your values
```

## 💻 Usage

### Basic Example
```{language}
{Simplest real usage pattern inferred from entry point}
```

### {Interface-specific section}
For CLI tools — show real flags extracted from the code:
```bash
{binary} [options]

Options:
  --{flag}    {description}
  --{flag}    {description}
```

For REST APIs — show real endpoints:
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET    | /api/... | ...         |

For libraries — show import + usage pattern:
```{language}
import { ... } from '{package}'
{usage example}
```

## ⚙️ Configuration

### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `{VAR}`  | {What it's for} | Yes/No | `{default}` |

### Config File
{Explain any config files found, e.g. `.config.json`, `settings.yaml`}

## 📁 Project Structure

```
{repo}/
├── {entry point file}     # {what it does}
├── src/
│   ├── {file/folder}      # {purpose}
│   └── {file/folder}      # {purpose}
├── tests/                 # Test suite
└── {config files}         # Configuration
```

## 🗺️ Roadmap
- [ ] {Logical next feature based on current state}
- [ ] {Another improvement}

## 🤝 Contributing

```bash
# Fork and clone
git checkout -b feature/your-feature

# Install dev dependencies
{dev install command}

# Run tests
{test command}

# Submit a PR
```

## 📜 License
{Detected license name} — see [LICENSE](./LICENSE) for details.
```

---

## Rules
- **Never hallucinate features** — only document what exists in the code
- **Use real values** — actual version numbers, real env var names, real flags
- **Detect language** — use correct syntax highlighting in all code blocks
- **Existing README?** — improve it, preserve any human-written sections
- **Missing info?** — use a clearly marked `<!-- TODO: add X -->` HTML comment,
  never fake content