Readme Generator

README Generator

Generate high-quality README documents from codebase evidence, with clear structure, runnable commands, and maintenance rules.

Core Rules

• Base every statement on repository evidence (files, code, scripts, workflows, configs).
• If key information is missing, write Not found in repo instead of guessing.
• Exclude local/private tooling folders by default (for example .codex/) unless explicitly requested.
• Keep naming/paths accurate and consistent with real repository layout.
• Prefer concise sections, bullet lists, and short command blocks.
• Keep internal workflow reporting out of README body by default. Evidence maps, scorecards, and verification-state reporting belong in the assistant response unless the user explicitly asks for them in the document.
• Treat top-level README.md as a user-facing homepage first and a maintainer reference second, unless the user explicitly wants an internal-only README.

Quick Reference

| When you need to… | Jump to | |---|---| | Generate README from scratch | §Pre-Generation Gates → §Project Type Routing → §Generation Workflow | | Update an existing README | §README Update Triggers + load references/checklist.md | | Chinese or bilingual output | §Chinese / Bilingual README Guidelines + load references/bilingual-guidelines.md | | Monorepo project | §Monorepo Rules + load references/monorepo-rules.md | | Lightweight / small project | §Lightweight Mode | | Calibrate ToC and navigation | §README Navigation Rule | | Check output quality | §README Quality Scorecard (3-Tier) | | Validate evidence mapping | §Evidence Mapping Output | | Check/avoid README anti-patterns | See §Anti-Examples for top failure; full catalog in references/anti-examples.md |

Pre-Generation Gates (Mandatory)

1) Audience and Language Gate

Before drafting, determine:

• target readers: contributors, operators, API consumers, or end users
• output language: Chinese / English / bilingual

If unspecified, default to:

• primary language follows existing repo docs
• keep audience assumptions in working notes; only state them in README when they materially help readers

2) Project Type Routing

Classify repository and choose template path:

• Service/backend app
• Library/SDK
• CLI tool
• Monorepo (multiple apps/packages)

If uncertain, state assumption explicitly in README.

3) Evidence Completeness Gate

Before drafting, verify minimum evidence has been collected:

• At least one entry point identified (main.go, cmd/, package.json, executable script)
• Project type determined (service/library/CLI/monorepo/lightweight)
• Command source located (Makefile, package.json, go.mod, or none)

If the discovery script is available, run it first:

bash "/scripts/discover_readme_needs.sh"

If minimum evidence is insufficient (no entry point found, no build system detected):

• Output a degraded README with only Project Overview + "Not found in repo" sections
• Mark the output as degraded: true in the assistant response
• List exactly what evidence is missing and suggest how to resolve

4) Badge Detection Gate (Mandatory)

Badge generation is mandatory for every README generation. Before drafting, scan for badge evidence:

• CI workflow files (.github/workflows/*.yml)
• Coverage config (codecov, coveralls, Makefile cover target)
• Language version (go.mod, package.json engines, pyproject.toml)
• License file (LICENSE, LICENSE.md)

If evidence exists, add badges. If no evidence exists for any badge type, skip that badge — do not fabricate. Document badge decisions in the Output Contract (badges_added field).

5) Command Verifiability Gate

Do not fabricate command verification or health-check results.

• If commands were executed, you may say so in the assistant response.
• If commands were not executed, do not inject Verified / Not verified in this environment labels into README body by default.
• In README itself, prefer evidence-backed install/run commands plus prerequisites.
• Only add explicit verification-state wording inside the README when the user requests it or the repository clearly uses that style for internal docs.

> Hard rule: verification-state phrases such as "not executed in this environment", "not verified", "Commands are derived from the Makefile and have not been executed" must never appear inside the README.md file itself. These belong exclusively in the assistant response (Output Contract). Even when the Scorecard checks H2, that check refers to the README file — keep all process language out of it.

Badge Strategy

Add badges at the top of README when evidence exists. Detection order:

1. CI status: detect from .github/workflows/*.yml → ``
2. Coverage: detect from coverage config (codecov, coveralls) or Makefile cover target
3. Go version / Language version: detect from go.mod, package.json engines, pyproject.toml
4. License: detect from LICENSE file → ``
5. Release/tag: detect from git tags or release workflow

Badge ordering: CI → Coverage → Language version → License → Release

Rules:

• Only add badges with real URLs derivable from repo evidence.
• Do not add placeholder badges with fake URLs.
• If repo is private and badges won't render, note this and skip.

Private-repo fallback (recommended wording):

Badge note: repository is private; external badge URLs may not render outside authorized viewers.

Community and Governance Files

Detect and reference these files when present:

| File | README Action | |------|--------------| | LICENSE | Add License section or badge | | CONTRIBUTING.md | Add "Contributing" section linking to it | | CODE_OF_CONDUCT.md | Reference in Contributing section | | SECURITY.md | Add "Security" section linking to it | | CHANGELOG.md | Reference in Release/Versioning section |

If LICENSE is missing, add a note: License: Not found in repo — consider adding a LICENSE file.

Key Evidence Targets

Always scan these high-signal files before drafting or refactoring:

• Entrypoints: main.go, cmd/*, executable scripts, package.json
• Build/test hubs: Makefile, go.mod, pyproject.toml, package.json
• CI and release: .github/workflows/*
• Runtime/config: .env.example, config/*, application.yml, docker-compose.yml
• Governance: LICENSE, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md
• Existing docs: README*.md, docs/*

If any of these are absent, record Not found in repo instead of filling the gap with assumptions.

Command Priority

When multiple command sources exist, apply Command Priority in this order:

1. Makefile target when it exists and is clearly maintained
2. Language-native manifest (go.mod, package.json, pyproject.toml, Cargo.toml)
3. CI workflow commands when they confirm the maintained path
4. Direct tool invocation only when no stronger source exists

If sources conflict, load references/command-priority.md and resolve the conflict before drafting commands.

Structure Policy

Use required + optional sections, not one rigid template.

Required Sections

1. Badges (when evidence exists)
2. Project overview
3. Prerequisites (CLI / Service types)
4. Quick start
5. Code/project structure
6. Common commands
7. Configuration and environment
8. Testing and quality checks
9. Documentation maintenance note

For public/open-source homepage-style READMEs, prefer this top order when evidence exists:

1. Value proposition
2. Highlights / key capabilities
3. Prerequisites
4. Install
5. Quick start
6. End-to-end example
7. Reference sections (structure, configuration, commands, testing, docs)

Prerequisites section format (CLI / Service types): list required runtime dependencies first, then optional ones. Each entry should state version constraint, purpose, and a setup link when non-trivial. Example:

## Prerequisites

- Go `>= 1.21` ([download](https://go.dev/dl/))
- A GitHub Personal Access Token with `repo` read permission ([create one](https://github.com/settings/tokens))
- _(Optional)_ An OpenAI API key — required only for the AI summary feature
- _(Optional)_ Docker — required only for `make docker-build`

Optional Sections (include only when evidence exists)

• Architecture / data flow
• Deployment / operations
• API usage examples
• Release/versioning
• Contributing guide (link to CONTRIBUTING.md if present)
• License
• Security notes (link to SECURITY.md if present)
• Contact and support (optional; no forced SLA field)

If a section is not applicable, omit it or mark N/A (reason).

Lightweight Template Mode

Use lightweight mode when repository scope is small and a full template would create noise.

Trigger conditions (any 2):

• fewer than 5 top-level functional directories
• no deployment/ops workflows in repo
• no public API/SDK surface
• README target is internal contributors only

Lightweight required sections:

1. Project overview
2. Quick start
3. Common commands
4. Project structure (short)
5. Testing and quality checks
6. Documentation maintenance note

In lightweight mode, skip optional heavy sections unless explicitly requested.

Chinese / Bilingual README Guidelines

Apply this section when the repository or user request indicates Chinese or bilingual output.

• Keep English for package names, command names, file paths, environment variables, and precise technical identifiers.
• Translate headings and explanatory prose to match the target audience language.
• Do not use double-language headings like ## Quick Start / 快速开始.
• In bilingual mode, use Chinese as the primary prose and keep English technical terms inline.
• Prefer exact Chinese headings such as ## 快速开始, ## 项目结构, and ## 常用命令.

Example heading style:

````markdown

快速开始

先安装依赖，再运行服务：

make install-tools
make run-api

````

README Navigation Rule

For long READMEs, navigation is part of usability.

• If the README has many major sections or reads like a long-form reference doc, keep a compact table of contents with major sections only.
• Do not remove an existing useful table of contents solely to reduce length.
• If the README is short enough to scan without scrolling effort, a table of contents can be omitted.

ToC size calibration: ToC length should match project complexity. A simple CLI or single-purpose library should have 7–10 ToC entries at most. Inflating the ToC by listing every section creates noise and obscures the user's actual navigation path.

Exclude from ToC by default (keep in document body for those who scroll):

• Architecture / data flow internals (downgrade to ### subsection under Project Structure)
• Contributor-only sections (Testing/CI details, Common Commands reference tables, Docker build steps)
• Any section that is not a direct action step for the primary audience

ToC label / heading consistency rule: the display text of every ToC entry must exactly match the ## heading it links to. If you shorten a ToC label for readability, you must rename the section heading to match. Mismatches disorient readers who click a link and land on a differently-titled section.

Monorepo Rules

When the detected project type is monorepo:

• Use a repository overview table instead of a deep tree dump.
• Link to submodule READMEs instead of duplicating every module's internal details.
• Document shared root commands only; module-specific commands belong in each module README.
• If LICENSE is missing, say Not found in repo at the root rather than guessing package-level license inheritance.

Load references/monorepo-rules.md before drafting or calibrating a monorepo README.

End-to-End Example Rule

For CLI tools, converters, generators, and similar products, prefer at least one end-to-end example that shows:

1. the user input command or API call
2. the resulting file name, status line, or response shape
3. a short excerpt of the generated output when evidence exists

This is usually more useful than showing an isolated output snippet alone.

No-fabrication constraint: if actual output cannot be derived from repository evidence (no sample output files, no test fixtures, no documented response format), show only the invocation and describe the destination generically — do not invent output content.

schema-gen generate --format json --output ./schemas ./internal/models
# → writes schema file(s) to ./schemas/

Never write a fabricated JSON/YAML body as if it were real output when no evidence exists for the exact shape.

Anti-Examples (BAD / GOOD Markdown Pairs)

Most common failure — process-state labels in README body:

BAD:

````markdown

Testing — Status: Not verified in this environment

| Command | Verified | |---------|----------| | make test | ⚠️ Not verified | | make lint | ✅ Verified |

````

GOOD:

````markdown

Testing

make test
make lint

````

This applies to all process-state language: Verified, Not verified in this environment, PASS/FAIL — these belong in the assistant response, not the README body.

When refactoring an existing README that may contain low-frequency anti-patterns (fabricated badges, guessed config values, monorepo tree dumps, double-language headings, output-without-input snippets): → Load references/anti-examples.md for the full BAD/GOOD catalog with correction guidance for each pattern.

Generation Workflow

1. Detect audience — decide whether the README is for end users, contributors, operators, or mixed readers.
2. Detect language — choose English, Chinese, or bilingual output before drafting.
3. Discover repository facts — run scripts/discover_readme_needs.sh if available.
4. Collect key evidence targets — read main.go, Makefile, go.mod, .github/workflows, config files, and existing README/docs.
5. Route project type — choose Template A/B/C/D/E based on repo structure.
6. Choose command source — apply Command Priority and resolve command conflicts before copying commands.
7. Select supporting references — load template, checklist, golden example, bilingual guidance, or monorepo rules only when needed.
8. Draft sections — build the README from evidence, keeping homepage-first reader flow.
9. Calibrate structure — add or trim ToC, badges, end-to-end examples, and optional sections based on project complexity.
10. Polish language — remove internal process wording, duplicated headings, guessed configuration, and filler prose.
11. Verify evidence mapping — ensure each non-trivial section maps back to repo files.
12. Return output contract — include the evidence mapping, scorecard, degraded flag, and omitted sections in the assistant response.

Output Style

• Short, direct prose. Fenced blocks for trees and commands.
• No internal rubric language (scorecard, pass/fail, verified) in README body unless requested.

Evidence Mapping Output (Required)

After generating or refactoring README, output an evidence mapping table in the assistant response, not inside the README itself, unless the user explicitly asks for an in-document appendix:

| README Section | Evidence File(s) | Evidence Snippet/Reason | |---|---|---| | Quick Start | Makefile, go.mod | target/command exists | | Configuration | .env.example, config/* | variables defined | | Testing | Makefile, CI workflow | test/lint commands present |

Rules:

• Every non-trivial section should map to at least one evidence source.
• If evidence is missing, map the section to Not found in repo.
• Keep mapping concise (one line per section is enough).

README Update Triggers

When these changes occur, the corresponding README sections should be updated:

| Repository Change | README Sections to Update | |------------------|--------------------------| | New cmd/*/main.go entrypoint added | Project Structure, Common Commands, Quick Start | | Environment variable added/

…

Source & license

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

• Author: johnqtcg
• Source: johnqtcg/awesome-skills
• License: MIT
• Homepage: https://johnqtcg.github.io/awesome-skills/

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