Skip to content

Instantly share code, notes, and snippets.

@evandhoffman

evandhoffman/README.md.md

Last active July 3, 2026 15:12
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save evandhoffman/57fd43229314b7a4e1bba4f4cb2a4531 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save evandhoffman/57fd43229314b7a4e1bba4f4cb2a4531 to your computer and use it in GitHub Desktop.
Download ZIP
README.md prompt
Raw
README.md.md

Analyze this repository and create or update its README.md. The README is primarily for humans. Agent-specific guidance lives in AGENTS.md — do not duplicate it; link to it once.

Priorities, in order (structure the README this way):

  1. What this is — 2–4 sentences: purpose, product surface (CLI/API/library/ app/infra), runtime model.
  2. Usage — how to use the software. This is the main help page. First identify the product type(s) from evidence, then adapt:
    • CLI tool: commands, flags, examples, exit codes if evident.
    • Client/server webapp: how to reach and use it — URLs, main flows, auth; API endpoints with example requests/responses if it exposes one.
    • Library/SDK: install, imports, minimal working example, key APIs.
    • Mobile app: main screens/flows; how to run on simulator/device.
    • Shell scripts / tool collection: a table of scripts with purpose and invocation for each.
    • Infra/automation: what it manages; safe inspection vs. destructive commands, clearly marked. A repo may expose several surfaces — document each that matters. Pull examples from help text, tests, docs, or schemas. Mark anything inferred.
  3. Build & run — prerequisites (tools, runtimes, Docker, services, env vars), install/setup, run locally, run tests, build. Verified commands only.
  4. Other useful info — configuration, project layout, architecture (brief), troubleshooting. Only if evidence-backed and genuinely useful.
  5. Typical README stuff — license, links to docs/, contributing pointer. Only what exists.

If a README already exists, UPDATE it: reconcile against current code, preserve accurate hand-written content, fix stale or unverifiable claims, and reorganize only where it improves usability. Do not regenerate from scratch unless mostly obsolete.

Evidence rules:

  • Every factual claim must be supported by repository evidence (manifests, scripts, CI config, Makefiles, help text, tests, schemas, docs).
  • "Verified" means the command appears in one of those sources. Do not execute commands except read-only checks (--version, --help). No installs, test runs, or anything destructive.
  • Do not invent commands, flags, features, endpoints, or examples. Omit or mark as inferred anything unverifiable.
  • No secrets, no marketing language, no generic best-practice advice, no aspirational roadmap content.

Length and scope:

  • Root README under ~200 lines. If a section pushes past that, move detail to docs/ and link from the README.
  • Create at most 2–3 supporting docs/ files, and only when the README would otherwise exceed its budget.
  • Component READMEs only for components with a distinct product surface or build/test workflow — not one per directory. Keep each under ~80 lines and don't repeat root content.
  • Use tables and fenced code blocks where they aid scanning; keep prose direct.

After writing: verify relative links resolve, then create a branch off the default branch and commit with a clear message. If gh is available and authenticated, open a PR titled "docs: add/update README"; otherwise push the branch and print the suggested PR title and body. The PR description must list what changed, anything marked inferred, and any hand-written content that was corrected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment