readme-conventions

What I do

• •Guide the structure and content of README.md files
• •Enforce minimalist documentation principles
• •Provide templates and examples for different project types

When to use me

Use this skill when writing or reviewing README.md files. It ensures consistency and quality across projects.

Principles

1. •

   One screen rule -- A README should fit on one screen when possible. If it needs scrolling, you're writing too much.

2. •

   Copy-paste quickstart -- A new developer should be able to copy-paste the quickstart commands and have the project running in under 2 minutes.

3. •

   No aspirational content -- Document what exists, not what you plan to build. Use GitHub issues for the roadmap.

4. •

   Link, don't inline -- If detailed docs exist elsewhere (wiki, /docs, external site), link to them. Don't duplicate content.

5. •

   Version-aware prerequisites -- Always specify minimum versions for prerequisites when it matters.

Structure Template

# Project Name

One sentence describing what this project does.

## Prerequisites

- [Runtime](https://link) >= version
- [Tool](https://link)

## Quickstart

\```bash
git clone <repo-url>
cd <project>
<install-command>
<run-command>
\```

## License

MIT

Anti-patterns to Avoid

• •Badge walls -- Rows of status badges that nobody reads
• •Table of contents -- If you need one, your README is too long
• •Screenshots of text -- Use actual text and code blocks
• •Changelog in README -- Use GitHub releases
• •TODO lists -- Use GitHub issues
• •Exhaustive API docs -- Belong in dedicated docs, not README
• •"Coming soon" sections -- Either it exists or it doesn't
• •Duplicate info -- Don't repeat what's in package.json or the code

Per-language Conventions

JavaScript/TypeScript

## Prerequisites
- [Node.js](https://nodejs.org) >= 18
- [pnpm](https://pnpm.io) (or npm/yarn/bun)

## Quickstart
\```bash
pnpm install
pnpm dev
\```

Go

## Prerequisites
- [Go](https://go.dev) >= 1.21

## Quickstart
\```bash
go mod download
go run .
\```

Python

## Prerequisites
- [Python](https://python.org) >= 3.10

## Quickstart
\```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
\```

Rust

## Prerequisites
- [Rust](https://rustup.rs) (stable)

## Quickstart
\```bash
cargo build
cargo run
\```

README Workflow

Analysis Approach

When analyzing a project for README generation, examine:

1. •Package manifests -- package.json, go.mod, Cargo.toml, pyproject.toml, requirements.txt, pom.xml, build.gradle
2. •Entry points -- main.*, index.*, app.*, src/
3. •Build/run scripts -- Makefile, Dockerfile, docker-compose.yml, scripts/
4. •Existing documentation -- current README, CONTRIBUTING, docs/
5. •Git history -- recent activity and project direction
6. •CI configuration -- .github/workflows/, .gitlab-ci.yml

Agent Integration

• •Focus exclusively on README.md files for documentation.
• •When generating README, follow the minimalist structure template above.
• •When validating README, check against the actual project state. Identify stale instructions, missing prerequisites, or broken commands.
• •Do not add TODO comments or task lists to README. Delegate TODOs to GitHub issues via @git-ops.