readme-generator

name	readme-generator
description	Generates a comprehensive, standardized README.md for any project. Use when the user wants to create or regenerate a README file following the project's documentation standard.
metadata	{"author":"emaginebr"}

Generate Standardized README.md

You are a README.md generator that creates comprehensive, well-structured project documentation. Your task is to analyze the project and generate a complete README following a strict template.

Input

The user may provide additional context or a project path as argument: $ARGUMENTS

If no arguments are provided, analyze the current project directory.

Instructions

Phase 1 — Project Discovery

Analyze the project to gather all necessary information:

1. Identify the project type: Check for project files to determine the technology stack:

   • .csproj / .sln → .NET
   • package.json → Node.js / React / Angular
   • pom.xml / build.gradle → Java
   • requirements.txt / pyproject.toml / setup.py → Python
   • go.mod → Go
   • Cargo.toml → Rust
   • Gemfile → Ruby
   • Other config files as needed

2. Read project configuration files: Read the main project config to extract:

   • Project name and version
   • Description (if available)
   • Dependencies and their versions
   • Build/run scripts
   • License

3. Analyze the directory structure: Use ls and Glob to understand the folder structure, identify key directories (source, tests, docs, config, docker, CI/CD).

4. Check for Docker support: Look for Dockerfile, docker-compose.yml, .dockerignore.

5. Check for CI/CD: Look for .github/workflows/, .gitlab-ci.yml, Jenkinsfile, azure-pipelines.yml, bitbucket-pipelines.yml.

6. Check for existing badges: Look at existing README (if any), SonarCloud, NuGet, NPM, or other badge sources.

7. Check for environment configuration: Look for .env.example, appsettings.*.json, config/ directories.

8. Check for tests: Identify test frameworks and test directory structure.

9. Check for related ecosystem projects: Look for references to sibling repositories, packages, or monorepo structure.

10. Analyze system architecture: Identify the main components, services, APIs, databases, message brokers, caches, and external integrations that make up the system. Look at:

    • docker-compose.yml for service topology
    • API gateway or reverse proxy configurations
    • Database connections and ORM configurations
    • Message broker or event bus usage (RabbitMQ, Kafka, Redis Pub/Sub)
    • External service integrations (payment, email, storage, auth providers)
    • Microservice boundaries (multiple .csproj/package.json in subdirectories)
    • Infrastructure-as-code files (Terraform, Pulumi, CloudFormation)

11. Check for existing documentation: Look for a docs/ directory with existing .md files that should be linked in the README.

Phase 2 — Generate System Design Diagram

Use the mermaid-chart skill to create a system design diagram for the project:

1. Based on the architecture analysis from Phase 1 step 10, determine the most appropriate diagram type:

   • C4 Context Diagram (C4Context) — For projects with external actors and system boundaries
   • Flowchart (flowchart TD/LR) — For general service interaction flows
   • Sequence Diagram (sequenceDiagram) — For projects where request flow is the key aspect

2. Invoke the mermaid-chart skill to generate the diagram:

   /mermaid-chart system-design diagram for <project-name> showing <identified components>
   

   • Save to docs/system-design.mmd and docs/system-design.png
   • The diagram must represent real components discovered during Phase 1 — never invent services or integrations

3. If the project is too simple for a system design diagram (e.g., a single CLI tool or a static library with no external dependencies), skip this phase entirely.

Phase 3 — Manage Additional Documents

Use the doc-manager skill to create or update any supplementary documentation that would benefit the project:

1. Check if a docs/ directory already exists with documents
2. If additional documents are needed (e.g., ARCHITECTURE_DECISIONS.md, DEPLOYMENT_GUIDE.md, API_REFERENCE.md), use the doc-manager skill to create them:

   /doc-manager create <document-name>
   

3. Collect all document paths from docs/ to link them in the README

Phase 4 — Generate README

Generate the README.md following the exact template structure below. Only include sections that are relevant to the project. If the project has no Docker setup, skip the Docker section. If no CI/CD, skip that section.

Phase 5 — Save the File

Save the generated README to README.md in the project root (or the path specified by the user).

README Template

The generated README MUST follow this structure and formatting standard:

# <Project Name> - <Short Tagline>

![<Framework>](https://img.shields.io/badge/<Framework>-<Version>-blue)
![License](https://img.shields.io/badge/License-<License>-green)
<!-- Add relevant badges: SonarCloud, NuGet, NPM, build status, coverage, etc. -->

## Overview

**<Project Name>** is <one paragraph description of what the project does, who it's for, and what problems it solves>. Built using **<main technologies>**.

<If part of an ecosystem, describe the relationship with other projects here.>

<Brief mention of    >

---



 🔐  - Brief description
 🔑  - Brief description
 🔄  - Brief description
<!-- List all major features with appropriate emoji and bold title -->

---




  - Brief description


  - Brief description
<!-- Only if applicable -->


  - Brief description
<!-- Only if applicable -->


  - Brief description


  - Brief description


  - Brief description
<!-- Only if applicable -->

---



\\`
/
├── /                  # Description
│   ├── /            # Description
│   └──                # Description
├── /                  # Description
├──             # Description
└── README.md                # This file
\\`

<!-- If part of an ecosystem, add: -->



| Project | Type | Package | Description |
|---------|------|---------|-------------|
|  | Type | Badge | Description |



\\`

\\`

---



<!-- Generated by the mermaid-chart skill. Only include if a system design diagram was created in Phase 2. -->

The following diagram illustrates the high-level architecture of :

![]()





---



<!-- Only include if there are documents in docs/. List all .md files managed by the doc-manager skill. -->

| Document | Description |
|----------|-------------|
| []() | Brief description |

<!-- Repeat for each document found in docs/ -->

---



Before running the application, you need to configure the environment variables:



\\`bash
cp .env.example .env
\\`



\\`bash

VARIABLEvalue
\\`

⚠️ :
 Never commit the \ file with real credentials
 Only the \ should be version controlled
 Change all default passwords and secrets before deployment

---







\\`bash

\\`



\\`bash
docker-compose up -d --build
\\`



\\`bash
docker-compose ps
docker-compose logs -f
\\`



| Service | URL |
|---------|-----|
|  | http://localhost:PORT |



| Action | Command |
|--------|---------|
| Start services | \ |
| Start with rebuild | \ |
| Stop services | \ |
| View status | \ |
| View logs | \ |
| Remove containers | \ |
| Remove containers and volumes (⚠️) | \ |

---




 
 





\\`bash

\\`



\\`bash

\\`

---






\\`bash

\\`


\\`bash

\\`



\\`
/
├── /         # Description
├── /         # Description
└── /         # Description
\\`

---



<!-- Only for API projects. Include authentication flow, endpoint summary, key examples. -->



\\`
 Step 1 → 2. Step 2 → 3. Step 3
\\`



| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | \ | Description | No |
| GET | \ | Description | Yes |

---




  - Description

---



<!-- Only for projects with databases -->



\\`bash

\\`



\\`bash

\\`

---








\\`bash

\\`


 Cause 1
 Cause 2


 Solution 1
 Solution 2

---







\\`
// Example code
\\`

---





\\`bash

\\`



\\`bash

\\`



<!-- Only if relevant. Include examples for major cloud providers. -->

---






 Trigger 1
 Trigger 2


 Step 1
 Step 2

---





 [ ]  - Description
 [ ]  - Description

---



Contributions are welcome! Please feel free to submit a Pull Request.



 Fork the repository
 Create a feature branch (\)
 Make your changes
 Run tests (\)
 Commit your changes (\)
 Push to the branch (\)
 Open a Pull Request



 
 

---



Developed by 

---



This project is licensed under the  - see the LICENSE file for details.

---



 Built with []()
 Powered by []()

---



 : []()
 : []()

---

Critical Rules

1. Only include relevant sections: If the project has no Docker, skip the Docker section. If no database, skip Backup/Restore. If not an API, skip API Documentation. The template above shows ALL possible sections — only use the ones that apply.

2. Accurate information only: Every piece of information in the README must come from actual project files. Do NOT invent features, dependencies, or configurations that don't exist.

3. Realistic badge URLs: Only add badges for services that are actually configured (SonarCloud, NuGet, NPM, etc.). Check for existing badge configurations in CI/CD files or existing README.

4. Complete project structure: Show the actual directory tree, not a made-up one. Use ls and Glob to verify what exists.

5. Correct commands: All build, test, run, and Docker commands must be verified against actual project configuration files (package.json scripts, .csproj settings, Makefile, etc.).

6. Preserve existing content: If the user has an existing README with custom content (like a specific roadmap or acknowledgments), ask whether to preserve it or regenerate.

7. Emoji consistency: Use the emoji style shown in the template for section headers. Each feature in the Features list should have a contextually appropriate emoji.

8. Horizontal rules: Use --- between major sections for visual separation.

9. Tables for structured data: Use markdown tables for Docker commands, endpoints, ecosystem packages, and other structured data.

10. Code blocks with language hints: Always specify the language in fenced code blocks (bash, json, csharp, javascript, etc.).

11. Environment variables: Never include real secrets or passwords in examples. Always use placeholder values like your_secure_password_here_change_this.

12. Git remote detection: Try to detect the GitHub/GitLab repository URL from .git/config to generate correct links for Issues, Discussions, and related projects.

13. System Design diagram is mandatory: Always attempt to generate a system design diagram using the skill. Only skip if the project is trivially simple (single-file script, static library with no dependencies). The diagram must reflect discovered during analysis — never fabricate components.

After Generating

After creating the README, inform the user:

• The file path where the README was saved
• Which sections were included and which were skipped (and why)
• The system design diagram path (docs/system-design.mmd and docs/system-design.png), or why it was skipped
• Any additional documents created in docs/ via the doc-manager skill
• Any information that could not be auto-detected and may need manual review

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.