readme-optimization skill (samber): audit and rewrite a repository README

• Asks thirteen questions one at a time; questions 1 to 4 gate the rewrite.

  Answers 11 to 13 (date, one-off or compounding, ceiling) re-rank the fixes and can delete the terminal demo or enterprise signals.

  Interview

• Writes the audience on the scorecard and checks the README is the real bottleneck.

  If traffic is low it points you to launch or distribution work instead of a prose rewrite.

  Step 1 - Declare the audience

• Prints mechanical facts about the README and checks relative links.

  Shadowed copies, size warnings, heading tree, section count, words before the first code block, badges in the first 40 lines, empty alt text, raw HTML tags, broken relative links, content-category headings and leftover placeholders. The body runs wc, awk, grep, sed, sort, uniq and file-existence tests.

  Runs code · scripts/readme-audit.sh <repo-root>

• Scores five blocking checks (Band A) and eight two-point checks (Band B).

  The rewrite starts only after you agree with the diagnosis.

  Step 3 - Score the current README

• Checks each command, flag and path in the README against its source of truth.

  It then runs the documented install command and first example exactly as written from a clean state, and repeats until no undocumented step remains.

  Runs code · Step 4 - Verify every claim

• Picks a skeleton for what the reader decides and drafts three one-liner candidates.

  It rewrites section by section with approval, replaces unfalsifiable claims with checkable ones, and states what the project does not do.

  Write · Step 5 - Choose a shape and rewrite

• Keeps badges backed by a third-party check and fixes description, topics and rendering.

  It cites an ICSE 2018 study of npm packages; the cap of four is a working default, not a published figure.

  Step 6 and 7 - Badges and furniture

• Adds enterprise trust signals only if the audience calls for them, then re-scores.

  Pass means all five blocking checks and at least 14 of 16 scored points, plus a five-question, 60-second cold-reader test.

  Step 8 and 9 - Trust signals and cold-reader test

Watch out for

• It runs your documented install command

  Step 4 has the agent execute the install command and first example exactly as written, repeat until the path works, and fold each gap back into the README. Our advice: do it in a container or an empty directory and read each command before it runs. github.com

• It rewrites your README

  The rewrite follows only after you agree with the scorecard, section by section. Our advice: review the diff before you commit, since SKILL.md has the agent replace unverifiable claims. github.com

• It may open your package-registry page

  Step 2 says that if the environment can browse the web, the agent opens the project's package-registry page and compares it with the code-host render. Browsing depends on your tool's setup. github.com

• The Claude app route is left out of the install box

  The skill reads and runs things in a repository on your machine, so the install box has no Claude app upload tab for it. github.com

• It may keep notes in devrel-context.md

  SKILL.md tells the agent to store a few details about the current task or project, and to use a file called devrel-context.md when its memory lives in a file. Our advice: open that file before you commit or share the folder. github.com

• The plugin route installs the whole collection

  The README's plugin and extension routes add every skill in the repo; its git tree holds 93. The repo has no hooks, agents, commands or MCP server files, and 14 of its skills bundle a script. Our advice: use the skills CLI command for this skill if you want only it. github.com

Security advisories