readme-best-practices

name	readme-best-practices
description	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.
license	MIT
compatibility	Requires access to the repository file tree. Works with Claude Code, OpenCode, and similar agents. Network access recommended for shields.io badge validation.
metadata	{"author":"d-oit","version":"1.0","tags":"readme documentation github badges svg-logo markdown"}

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:

• 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 <div align="center"> closing tag