# 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, install steps, usage examples, validation, roadmap, or contribution guidance.

- Skill: `jeremylongworth-source/readme-upgrade` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jeremylongworth-source/readme-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeremylongworth-source/readme-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: jeremylongworth-source (https://skillmd.com/u/jeremylongworth-source)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/jeremylongworth-source/readme-upgrade

---


# 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.