readme-upgrade

Improve README files for open-source projects, libraries, tools, and skill repositories. Use when Codex is asked to rewrite, audit, restructure, or strengthen a README with clearer positioning, instal

SKILL.md

GitHub

README Upgrade

Core Workflow

  1. Identify the audience, project purpose, install path, first successful use, and trust proof the README must convey.
  2. Audit current README gaps: unclear positioning, stale commands, missing prerequisites, weak examples, missing validation, or noisy structure.
  3. Reorder content so a new user can understand value, install, verify, and use the project quickly.
  4. Keep host, vendor, and platform-specific setup in linked docs when possible.
  5. Add concise examples, links to deeper docs, and contribution or support paths only when they help the reader act.
  6. Preserve accurate commands and avoid unsupported claims.

Safety Rules

  • Do not invent install commands, compatibility claims, badges, stars, download counts, roadmap commitments, or performance numbers.
  • Verify current commands from repo files before documenting them.
  • Keep marketing claims subordinate to concrete behavior and evidence.

Deliverable Shape

For README upgrades, provide:

  • Audience and README goal
  • Recommended structure
  • Edited README section or full rewrite
  • Commands and links checked
  • Removed ambiguity or stale content
  • Follow-up docs needed

References

  • Read references/readme-upgrade-checklist.md when upgrading or reviewing a README.