Readme hardening

Skill yeaight7/agent-powerups/skills/readme-hardening

Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Antigravity CLI, Cursor and more

Install

npx -y skills add yeaight7/agent-powerups --skill readme-hardening

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when a README cannot be followed verbatim -- setup or test commands fail or are vague, environment requirements are unstated, or a new engineer or agent cannot bootstrap the project quickly.

SKILL.md

3.1 KB, as published. Nobody here has run it

Purpose

A good README is an executable contract, not a marketing page. It must allow an agent or a new engineer to clone the repository and run tests within 3 minutes.

When to Use

Onboarding feedback says setup instructions fail or are ambiguous
The project's scripts, dependencies, or env requirements changed
Before publishing the repo or handing it to another team or agent

Inputs

The current README and the repo it claims to describe
The actual scripts and tooling (package manifest, Makefile, CI config)

Workflow

Verify commands. Extract every shell command from the README (npm install, docker-compose up, cargo test) and check each against repo evidence — then run them in a clean environment where possible. If they fail, fix the README:
```
rg -n "^( {4}|\t)\S|^\$ " README.md            # command lines in the README
rg -n "\"scripts\"" -A 20 package.json         # do documented npm scripts exist?
```
Remove ambiguity. Replace "Install dependencies" with the exact command (npm ci). Replace "Run the app" with the exact script (npm run start:dev).
Environment checklist. Clearly list required environment variables in an env-example block — do not just say "set up your environment." Cross-check against what the code actually reads:
```
rg -no "process\.env\.[A-Z0-9_]+" src/ | sort -u
```
Architecture pointers. Provide exact file paths for entry points (e.g., "Main API routing is in src/routes.ts") to save agents from searching the entire tree.

Cover the minimum outline — confirm each section exists and is accurate:

# Project name + one-line purpose
## Install         # exact commands
## Run             # exact commands, expected output
## Test            # exact commands
## Configuration   # env vars with example values
## Architecture    # entry points by path
## Troubleshooting # the 2-3 most common failures and their fixes

Output

A README whose every command was verified against the repo (or actually run)
An env-var block matching what the code actually reads
Entry-point paths for the main flows

Verification

Every README command exists in scripts/tooling or ran successfully
No vague instructions remain ("install dependencies" without the command)
Env-var list cross-checked against the code's actual reads
Entry-point file paths verified to exist
Outline covered: install, run, test, configuration, architecture, troubleshooting

Failure Modes

Marketing-page drift — features and badges grow while install instructions rot.
Untested commands — a command transcribed from memory instead of verified against the scripts.
Hidden environment — the app reads six env vars and the README names two.
Path-free architecture prose — "the API layer handles routing" helps nobody; name the file.