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

- **Type:** Skill
- **Install:** `agentstack add skill-landim32-awesome-ai-skills-readme-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [landim32](https://agentstack.voostack.com/s/landim32)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [landim32](https://github.com/landim32)
- **Source:** https://github.com/landim32/awesome-ai-skills/tree/main/skills/readme-generator

## Install

```sh
agentstack add skill-landim32-awesome-ai-skills-readme-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Overview

**** is . Built using ****.

---

## 🚀 Features

- 🔐 **Feature 1** - Brief description
- 🔑 **Feature 2** - Brief description
- 🔄 **Feature 3** - Brief description

---

## 🛠️ Technologies Used

### Core Framework
- **** - Brief description

### Database
- **** - Brief description

### Security
- **** - Brief description

### Additional Libraries
- **** - Brief description

### Testing
- **** - Brief description

### DevOps
- **** - Brief description

---

## 📁 Project Structure

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

### Ecosystem

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

#### Dependency graph

\`\`\`

\`\`\`

---

## 🏗️ System Design

The following diagram illustrates the high-level architecture of ****:

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

---

## 📖 Additional Documentation

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

---

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

### Setup Steps

#### 1. 

\`\`\`bash

\`\`\`

#### 2. 

\`\`\`bash

\`\`\`

---

## 🧪 Testing

### Running Tests

**All Tests:**
\`\`\`bash

\`\`\`

**With Coverage:**
\`\`\`bash

\`\`\`

### Test Structure

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

---

## 📚 API Documentation

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

### 
- **Feature** - Description

---

## 💾 Backup and Restore

### Backup

\`\`\`bash

\`\`\`

### Restore

\`\`\`bash

\`\`\`

---

## 🔍 Troubleshooting

### Common Issues

#### 

**Check:**
\`\`\`bash

\`\`\`

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

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

---

## 📦 Integration

### Using  in Your Application

#### Option 1: 

\`\`\`
// Example code
\`\`\`

---

## 🚀 Deployment

### Development Environment

\`\`\`bash

\`\`\`

### Production Environment

\`\`\`bash

\`\`\`

### Cloud Deployment

---

## 🔄 CI/CD

### 

**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 (\`\`)
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

- 
- 

---

## 👨‍💻 Author

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

---

## 📄 License

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

---

## 🙏 Acknowledgments

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

---

## 📞 Support

- **Issues**: [GitHub Issues]()
- **Discussions**: [GitHub Discussions]()

---

**⭐ 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [landim32](https://github.com/landim32)
- **Source:** [landim32/awesome-ai-skills](https://github.com/landim32/awesome-ai-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-landim32-awesome-ai-skills-readme-generator
- Seller: https://agentstack.voostack.com/s/landim32
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.