Readme best practices

Skill d-oit/do-web-doc-resolver/.agents/skills/readme-best-practices

LLM-ready web documentation resolver: Python cascade skill + web + Rust CLI (wdr) with semantic cache, multi-provider routing, and quality synthesis

Install

npx -y skills add d-oit/do-web-doc-resolver --skill readme-best-practices

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

1 stars1 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

Create, audit, and improve GitHub README.md files following 2026 best practices. Use this skill when a user asks to write, rewrite, or review a README.md for a GitHub repository, add shields.io badges, create a project SVG logo, improve documentation structure, or make a repository more discoverable and professional.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

5.6 KB, as published. Nobody here has run it

README Best Practices (2026)

This skill guides you through creating a best-practice GitHub README.md for 2026, including a custom SVG logo and shields.io badges.

When to activate

User asks to "write a README", "improve README", "add badges", or "create a logo"
User asks to analyze or audit an existing README.md
User wants to make a repository more professional or discoverable
User asks about GitHub documentation best practices

Step-by-step workflow

1. Analyze the repository

Before writing anything, gather context:

# Detect tech stack
cat package.json 2>/dev/null | head -20
cat Cargo.toml 2>/dev/null | head -20
cat pyproject.toml 2>/dev/null | head -20
ls -1
find . -name "*.md" -maxdepth 2

Identify:

Primary language(s) and tech stack
What the project does (one sentence)
Key features (5-10 bullet points)
Installation method(s)
Whether a live demo/deployment exists
License type
CI/CD system (GitHub Actions workflows)
Existing screenshots or assets

2. Create the SVG logo

See references/LOGO.md for the full logo creation guide.

Quick pattern:

ViewBox: 0 0 320 80 at width="320"
Dark background pill (#0f172a to #1e293b gradient, rx="14")
Domain-specific icon on the left
Project acronym in indigo→cyan gradient (#6366f1 to #06b6d4)
Thin divider line below acronym
Full project name as subtitle (#94a3b8)
Tech stack chips on the right (colored pills)
Save to: assets/logo.svg
Reference: <img src="assets/logo.svg" alt="..." width="320"/> in README

Use the template at assets/logo-template.svg as starting point.

3. Write README sections (in order)

Follow this exact section order:

1.  <div align="center"> header block
    - Logo image
    - Project title (h1)
    - One-line tagline (bold) + secondary sentence
    - Shields.io badge row (CI | Release | License | Languages | Demo)
    - Navigation links: Demo · Docs · Report Bug · Request Feature

2.  "Why [project]?" — 3-4 value-proposition bullets

3.  Table of Contents (for READMEs > 100 lines)

4.  Quick Start — copy-paste, zero-config first

5.  Architecture — ASCII or Mermaid diagram if applicable

6.  Features — table: Feature | Description

7.  Installation — per interface/language with fenced code blocks

8.  Configuration — env vars table: Variable | Required | Default | Notes

9.  Usage — per interface with realistic, runnable examples

10. Testing — unit, integration, e2e commands

11. Repository Structure — annotated tree

12. Contributing — numbered steps

13. License

See references/STRUCTURE.md for full copy-paste templates.

4. Add shields.io badges

See references/BADGES.md for the complete badge catalog.

Required badges (always include):

CI/CD status (github/actions/workflows/ci.yml/badge.svg)
Latest release version (shields.io/github/v/release/...)
License
Primary language(s)

Recommended additions:

Live demo (Vercel / Netlify)
PRs Welcome
Code coverage (if Codecov/Coveralls configured)

Badge placement: All in the <div align="center"> header, on one line, max 6-8 badges.

5. Quality checklist

Before finalising, verify:

Key principles

First 3 seconds rule: Logo + tagline + badges must communicate value immediately
Zero-config first: Always show the no-API-key usage first in Quick Start
Copy-paste ready: Every code block must be directly runnable without editing
Consistent naming: Use the exact repo slug throughout — never an internal alias
Progressive detail: Overview → Quick Start → Full docs (do not front-load everything)
No lorem ipsum: Every section must contain accurate, real information

Common mistakes to avoid

Using a stale project name that differs from the current repo slug
Placing Installation before a "Why use this?" value pitch
Missing Table of Contents on READMEs longer than 100 lines
Broken badge URLs pointing to non-existent CI workflow files
No language specifier on fenced code blocks
Image paths that work locally but break on GitHub (always use paths from repo root)
More than 8 badges (becomes noise)
Forgetting <div align="center"> closing tag

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.