Readme Best Practices

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](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: `` in README

Use the template at [assets/logo-template.svg](assets/logo-template.svg) as starting point.

3. Write README sections (in order)

Follow this exact section order:

1.   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](references/STRUCTURE.md) for full copy-paste templates.

4. Add shields.io badges

See [references/BADGES.md](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 `` header, on one line, max 6-8 badges.

5. Quality checklist

Before finalising, verify:

• [ ] Logo renders in both light and dark GitHub themes
• [ ] All badge image URLs are valid (no 404s)
• [ ] Quick Start works with zero API keys / credentials
• [ ] All fenced code blocks have a language specifier ( `bash , `python , etc.)
• [ ] All internal links (CONTRIBUTING.md, LICENSE, docs/) exist in the repo
• [ ] Table of Contents anchor links match actual heading text
• [ ] No broken image src references
• [ ] Repo name in README matches github.com/owner/repo exactly (no old aliases)
• [ ] README description matches the GitHub repo "About" field
• [ ] Installation section has commands for every supported interface

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 `` closing tag

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: d-oit
• Source: d-oit/do-web-doc-resolver
• License: MIT
• Homepage: https://web-eight-ivory-29.vercel.app/

Install and usage instructions live in the source repository linked above.