README Generator
Agent

Point an AI agent at any project and generate a complete README.md with installation, usage, API docs, and examples. Built with OpenCode in under 15 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

You'll also need: A project to document — any folder with code in it works.

What You'll Build

By the end of this guide, you'll have a command-line tool that can analyze any project and produce a professional README.md. It will:

  • Scan project files to understand the tech stack, structure, and purpose
  • Generate a project description from the code itself -- no manual writing
  • Create installation instructions by detecting package managers, dependencies, and config files
  • Write usage examples based on entry points, CLI args, and public functions
  • Produce API documentation from docstrings, type hints, and function signatures
  • Add a features list, contributing section, and license info

You describe the task to OpenCode, it writes the script, you point it at a project and get a polished README. Then you iterate on the output until it matches your style.

1

Create Your Project

Set up a project folder with an AGENTS.md file that tells OpenCode what kind of tool you're building.

mkdir -p ~/projects/readme-generator
cd ~/projects/readme-generator
mkdir -p ~/projects/readme-generator
cd ~/projects/readme-generator

Now create an AGENTS.md file. This is the context file that OpenCode reads to understand your project:

# README Generator Agent

## Project Type
Python CLI tool

## Description
A command-line tool that analyzes a project directory and generates a
complete, professional README.md file. It scans source files, config
files, and directory structure to produce documentation automatically.

## Tech Stack
- Python 3.8+ (standard library only, no external deps)
- pathlib for file system traversal
- argparse for CLI interface

## Conventions
- Use type hints
- Keep it in a single file for simplicity
- Output markdown formatted for GitHub rendering
- Support Python, JavaScript, and general projects

Save this as AGENTS.md in your project folder. You can create it manually or use OpenCode:

opencode
Why AGENTS.md?
OpenCode reads this file automatically when you start it in the project directory. It gives the AI context about your project's purpose, tech stack, and conventions -- so every response is more relevant and accurate.
2

Build the README Generator

With OpenCode running in your project folder, give it the task. One prompt builds the whole thing.

Type this into OpenCode:

Analyze this project and generate a professional README.md with: project description, features list, installation instructions, usage examples, and a contributing section

Wait -- that prompt works if you already have code and want a README for this project. To build a reusable generator tool, use this prompt instead:

Create a Python script called readme_gen.py that takes a project
directory path as an argument and generates a complete README.md.

The script should:
1. Scan the directory for source files, package.json, requirements.txt,
   setup.py, pyproject.toml, Makefile, Dockerfile, etc.
2. Detect the programming language and framework
3. Read docstrings and comments from main entry points
4. Generate these sections:
   - Project title and description
   - Features list (inferred from code structure)
   - Installation instructions (based on detected package manager)
   - Usage examples (based on CLI args or main functions)
   - API reference (from public functions/classes with docstrings)
   - Contributing guidelines
   - License
5. Output the README.md to the project directory

Include a --dry-run flag that prints to stdout instead of writing a file.

OpenCode will generate a complete Python script. You'll see it write the file in real time. When it's done, you'll have a working readme_gen.py in your project folder.

What OpenCode Generates

The output will typically include:

  • A ProjectAnalyzer class that scans files and detects project type
  • Template strings for each README section with placeholder logic
  • Detection for Python (pip/poetry), JavaScript (npm/yarn), and general projects
  • A --dry-run flag so you can preview before writing
  • Markdown output formatted for GitHub with proper headings, code blocks, and lists
3

Run and Iterate

Point the generator at a real project, review the output, and improve it with follow-up prompts.

Run your generator against any project on your machine:

python3 readme_gen.py ~/projects/some-existing-project --dry-run

You should see a complete README printed to your terminal. Review it -- are the installation instructions right? Does the description make sense? Are the usage examples accurate?

When you're happy with the preview, drop the --dry-run flag to write the file:

python3 readme_gen.py ~/projects/some-existing-project

Iterate with OpenCode

Found something you want to change? Go back to OpenCode and ask. The AI remembers your project context from AGENTS.md.

# Example iteration prompts:
The installation section should detect whether to use pip, poetry,
or npm and give the right command for each.

Add a --style flag that lets me choose between "minimal",
"detailed", and "enterprise" README styles.

Parse Python type hints and generate a proper API reference table
with parameter types and return types.
Version control tip
Initialize a git repo with git init and commit after each working version. Store it on GitHub for free. That way you can always roll back if an iteration breaks something.

Example Prompts to Try

Once your basic README generator works, try these prompts to extend it. Each one is a separate prompt you can copy and paste into OpenCode:

Add a badges section with build status and license
Generate API documentation from the code
Add a table of contents
Create a changelog from git history
Add a "screenshots" section placeholder with instructions for
adding images to a docs/ folder
Detect CI/CD config files (GitHub Actions, GitLab CI) and
add a deployment section to the README

Each prompt builds on the existing code. OpenCode reads the current state of readme_gen.py and modifies it in place.

What's Next?

You've built a working README generator. Here's where to go from here:

  • Use it on all your projects: Run it against every repo you maintain. Edit the output, commit it, and you've got docs in minutes instead of hours.
  • Make it a CLI tool: Add a setup.py or pyproject.toml so you can install it globally with pip install -e . and run readme-gen from anywhere.
  • Deploy it: Wrap it in a simple web interface with Flask and host it for free on Cloudflare Pages.
  • Try another agent: The setup is the same -- only the task changes. Pick your next project:

Ready for the Next Agent?

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build Meeting Notes Summarizer All Guides