agentsclimarketplace

Readme excellence

Skill selamy-labs/agent-skills/skills/readme-excellence

Reusable public SKILL.md workflows for AI agents

Install
npx -y skills add selamy-labs/agent-skills --skill readme-excellence

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

  • 0 stars0 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 creating or auditing a repository README. A README earns its keep — every section answers a real reader question, the quickstart actually runs, and a diagram appears only when it replaces prose.

SKILL.md

3.1 KB, as published. Nobody here has run it

readme-excellence

A README is the repo's first and most-read interface. The bar is clarity that earns its keep, not length: every section answers a real reader question, or it is deleted or linked out. Longer is not better.

The section spine (order; omit optional, never reorder)

  1. Title — matches the repo/package; one-line (<120 char) description of what it is.
  2. What & Why — 2–4 sentences: the problem it solves; who/what consumes it. A reader knows this within the first screen.
  3. Quickstart — the smallest sequence that actually runs end-to-end, with expected output.
  4. Install / Requirements — deps, versions, OS; secrets injected at runtime, never inline.
  5. Usage — common cases with real code blocks + expected output; link large examples out.
  6. Architecture (optional) — only if it earns its keep; this is where a diagram may go (see below).
  7. Configuration — point to the source of truth (flags / --help / config schema); don't duplicate values that will rot.
  8. Development — clone → build → test → lint commands that succeed exactly as written.
  9. Contributing — PR policy, required CI, coverage gate.
  10. License — last.

The "earn its keep" rules

  • Every section answers a real reader question or it is deleted or linked out — don't mix reference, tutorial, and explanation in one README.
  • No filler, no aspirational/un-shipped capabilities, no restating the obvious.
  • A reader reaches a runnable state from Quickstart alone — if they can't, the quickstart is the defect (treat a non-running quickstart like a failing test).
  • Reference detail (full API, design rationale, tutorials) links out; the README stays a reference + one how-to.
  • Badges are real and live (CI, coverage, license, version) — no vanity badges.

Mermaid: when a diagram is justified

A diagram is ONE component, included only when it replaces prose a reader would otherwise reconstruct — system/component architecture, data/request flow, a state machine, a non-obvious cross-service sequence. Skip it when it just restates a list, the repo is a single module, or it would exceed ~15 nodes (split it, or move it to dedicated docs). Use text-based mermaid (renders + reviews in PRs); never commit a diagram image.

DONE means

A reader knows what the repo does and why within the first screen; the quickstart runs as written and shows its output; every section earns its keep with reference detail linked out; config points to the source of truth, not a rot-prone copy; any diagram replaces reconstructable prose and is ≤~15 mermaid nodes; sections follow the spine order. Output of an audit is a section-by-section verdict plus a concrete diff, not commentary.

Sources: standard-readme spec (RichardLitt); makeareadme.com; Diátaxis documentation framework (Procida).

Gives 0 of the 12 instructions most readme changelog skills give

Counted across 471 of the 478 authors here whose files we hold, read 2026-08-06

  • follow the Keep a Changelog formatin 31 of 471, across 26 files
  • omit empty sectionsin 21 of 471
  • Run from the git repository rootin 20 of 471, across 7 files
  • save output directly to CHANGELOG.mdin 20 of 471, across 7 files
  • Group commits into logical categoriesin 19 of 471, across 6 files
  • Review the generated changelog before publishingin 19 of 471, across 6 files
  • Apply changelog guidelines and brand voicein 18 of 471, across 5 files
  • Exclude internal commits like refactoring and testsin 18 of 471, across 5 files
  • Specify date ranges for focused changelogsin 17 of 471, across 4 files
  • Convert technical commits into customer languagein 17 of 471, across 4 files
  • group commits by conventional commit typein 14 of 471
  • insert new entry below unreleased sectionin 14 of 471

Said here and by no other author read

  • Delete or link sections that answer no reader question
  • Make the quickstart run end-to-end
  • Inject secrets at runtime never inline
  • Link out large examples and reference detail
  • Point configuration to its source of truth
  • Write development commands that succeed as written

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.