# Readme Generator

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

- Skill: `tomevault-io/readme-generator-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/readme-generator-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/readme-generator-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/readme-generator-3

---


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

```markdown
# <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 architecture approach if relevant.>

---

## 🚀 Features

- 🔐 **Feature 1** - Brief description
- 🔑 **Feature 2** - Brief description
- 🔄 **Feature 3** - Brief description
<!-- List all major features with appropriate emoji and bold title -->

---

## 🛠️ Technologies Used

### Core Framework
- **<Framework>** - Brief description

### Database
- **<Database>** - Brief description
<!-- Only if applicable -->

### Security
- **<Security tech>** - Brief description
<!-- Only if applicable -->

### Additional Libraries
- **<Library>** - Brief description

### Testing
- **<Test framework>** - Brief description

### DevOps
- **<DevOps tool>** - Brief description
<!-- Only if applicable -->

---

## 📁 Project Structure

\`\`\`
<ProjectRoot>/
├── <dir1>/                  # Description
│   ├── <subdir>/            # Description
│   └── <file>               # Description
├── <dir2>/                  # Description
├── <config-file>            # Description
└── README.md                # This file
\`\`\`

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

### Ecosystem

| Project | Type | Package | Description |
|---------|------|---------|-------------|
| **[Project1](url)** | Type | Badge | Description |

#### Dependency graph

\`\`\`
<ASCII art dependency graph>
\`\`\`

---

## 🏗️ System Design

<!-- 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 **<Project Name>**:

![System Design](docs/system-design.png)

<Brief explanation of the main components and how they interact.>

> 📄 **Source:** The editable Mermaid source is available at [`docs/system-design.mmd`](docs/system-design.mmd).

---

## 📖 Additional Documentation

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

| Document | Description |
|----------|-------------|
| [DOCUMENT_NAME](docs/DOCUMENT_NAME.md) | Brief description |

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

---

## ⚙️ Environment Configuration

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

### 1. Copy the environment template

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

### 2. Edit the \`.env\` file

\`\`\`bash
# Variable descriptions with example values
VARIABLE_NAME=example_value
\`\`\`

⚠️ **IMPORTANT**:
- Never commit the \`.env\` file with real credentials
- Only the \`.env.example\` should be version controlled
- Change all default passwords and secrets before deployment

---

## 🐳 Docker Setup

### Quick Start with Docker Compose

#### 1. Prerequisites

\`\`\`bash
# Any required network or pre-setup commands
\`\`\`

#### 2. Build and Start Services

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

#### 3. Verify Deployment

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

### Accessing the Application

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

### Docker Compose Commands

| Action | Command |
|--------|---------|
| Start services | \`docker-compose up -d\` |
| Start with rebuild | \`docker-compose up -d --build\` |
| Stop services | \`docker-compose stop\` |
| View status | \`docker-compose ps\` |
| View logs | \`docker-compose logs -f\` |
| Remove containers | \`docker-compose down\` |
| Remove containers and volumes (⚠️) | \`docker-compose down -v\` |

---

## 🔧 Manual Setup (Without Docker)

### Prerequisites
- <Prerequisite 1>
- <Prerequisite 2>

### Setup Steps

#### 1. <Step Title>

\`\`\`bash
<commands>
\`\`\`

#### 2. <Step Title>

\`\`\`bash
<commands>
\`\`\`

---

## 🧪 Testing

### Running Tests

**All Tests:**
\`\`\`bash
<test command>
\`\`\`

**With Coverage:**
\`\`\`bash
<coverage command>
\`\`\`

### Test Structure

\`\`\`
<TestDir>/
├── <category1>/         # Description
├── <category2>/         # Description
└── <category3>/         # Description
\`\`\`

---

## 📚 API Documentation

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

### Authentication Flow

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

### Key Endpoints

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | \`/endpoint\` | Description | No |
| GET | \`/endpoint/{id}\` | Description | Yes |

---

## 🔒 Security Features

### <Security Category>
- **Feature** - Description

---

## 💾 Backup and Restore

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

### Backup

\`\`\`bash
<backup command>
\`\`\`

### Restore

\`\`\`bash
<restore command>
\`\`\`

---

## 🔍 Troubleshooting

### Common Issues

#### <Issue Title>

**Check:**
\`\`\`bash
<diagnostic command>
\`\`\`

**Common causes:**
- Cause 1
- Cause 2

**Solutions:**
- Solution 1
- Solution 2

---

## 📦 Integration

### Using <Project> in Your Application

#### Option 1: <Integration Method>

\`\`\`<language>
// Example code
\`\`\`

---

## 🚀 Deployment

### Development Environment

\`\`\`bash
<dev command>
\`\`\`

### Production Environment

\`\`\`bash
<prod command>
\`\`\`

### Cloud Deployment

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

---

## 🔄 CI/CD

### <CI/CD Platform>

**Workflow triggers:**
- Trigger 1
- Trigger 2

**Workflow steps:**
1. Step 1
2. Step 2

---

## 🧩 Roadmap

### Planned Features

- [ ] **Feature 1** - Description
- [ ] **Feature 2** - Description

---

## 🤝 Contributing

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

### Development Setup

1. Fork the repository
2. Create a feature branch (\`git checkout -b feature/AmazingFeature\`)
3. Make your changes
4. Run tests (\`<test command>\`)
5. Commit your changes (\`git commit -m 'Add some AmazingFeature'\`)
6. Push to the branch (\`git push origin feature/AmazingFeature\`)
7. Open a Pull Request

### Coding Standards

- <Standard 1>
- <Standard 2>

---

## 👨‍💻 Author

Developed by **[Author Name](GitHub URL)**

---

## 📄 License

This project is licensed under the **<License Name>** - see the LICENSE file for details.

---

## 🙏 Acknowledgments

- Built with [Technology 1](URL)
- Powered by [Technology 2](URL)

---

## 📞 Support

- **Issues**: [GitHub Issues](<issues URL>)
- **Discussions**: [GitHub Discussions](<discussions URL>)

---

**⭐ If you find this project useful, please consider giving it a star!**
```

## 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 **mermaid-chart** skill. Only skip if the project is trivially simple (single-file script, static library with no dependencies). The diagram must reflect **real architecture** discovered during analysis — never fabricate components.

14. **Use doc-manager for additional documents**: Any supplementary documentation (architecture decisions, deployment guides, API references, etc.) MUST be created and managed through the **doc-manager** skill, which ensures proper naming (UPPER_SNAKE_CASE) and storage in `docs/`. Always link these documents in the README's "Additional Documentation" section.

15. **Image references**: When embedding the system design PNG in the README, use a relative path (`docs/system-design.png`). Always include the Mermaid source file link as well for editability.

16. **docs/ directory consistency**: All generated artifacts (diagrams, images, additional documents) must be saved in `docs/`. Create the directory if it does not exist.

## 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](https://tomevault.io/claim/emaginebr) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->