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:

# 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:

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

# {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

{Simplest real usage pattern inferred from entry point}

{Interface-specific section}

For CLI tools — show real flags extracted from the code:

{binary} [options]

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

For REST APIs — show real endpoints:

For libraries — show import + usage pattern:

import { ... } from '{package}'
{usage example}

⚙️ Configuration

Environment Variables

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

# 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 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