# Readme Writing Readme Files

> README quality standards for engaging, accessible, scannable content including problem-solution hooks, plain language (no unexplained jargon), acronym context, paragraph limits (≤5 lines), benefits-focused language, visual hierarchy, and progressive disclosure. Essential for creating effective README files that welcome and guide users.

- Skill: `wahidyankf/readme-writing-readme-files` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds add wahidyankf/readme-writing-readme-files`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wahidyankf/readme-writing-readme-files/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wahidyankf (https://skillmd.com/u/wahidyankf)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wahidyankf/readme-writing-readme-files

---


# Writing README Files

## Purpose

This Skill provides comprehensive guidance for writing **high-quality README files** that are engaging, accessible, and scannable. READMEs serve as the entry point for repositories, projects, and directories, requiring special attention to clarity, structure, and user experience.

**When to use this Skill:**

- Creating repository README.md files
- Writing project/package README files
- Creating directory README files for navigation
- Updating existing READMEs for clarity
- Reviewing READMEs for quality standards

## Core README Principles

See [Core README Principles](./reference/core-readme-principles.md) for the six principles (problem-solution hook, plain language, paragraph length, benefits-focused language, visual hierarchy, progressive disclosure) with ✅/❌ before/after examples.

## Standard README Structure

See [Standard README Structure](./reference/standard-readme-structure.md) for the full README template (Overview, Key Benefits, Quick Start, Installation, Usage, Documentation, Contributing, License).

## Common Mistakes

### ❌ Mistake 1: Starting with features, not benefits

**Wrong**: Lists features without context
**Right**: Shows problem, solution, and benefits first

### ❌ Mistake 2: Unexplained acronyms

**Wrong**: "Supports WCAG, ARIA, WAI"
**Right**: "Supports WCAG (Web Content Accessibility Guidelines), ARIA (Accessible Rich Internet Applications), and WAI (Web Accessibility Initiative) standards"

### ❌ Mistake 3: Wall of text paragraphs

**Wrong**: 10+ line paragraphs that are hard to scan
**Right**: Max 5 lines per paragraph, use lists and headings

### ❌ Mistake 4: Missing context for jargon

**Wrong**: "Uses Nx monorepo with affected builds"
**Right**: "Uses **Nx** (a monorepo build system) to manage multiple apps. The 'affected' feature only rebuilds changed projects, saving time."

### ❌ Mistake 5: No quick start section

**Wrong**: Jumps directly into detailed installation
**Right**: Provides "Quick Start" with minimal steps, then detailed installation

## Quick Quality Checklist

- [ ] Problem-solution hook in first 2-3 paragraphs
- [ ] All acronyms explained on first use
- [ ] All jargon explained in plain language
- [ ] No paragraphs exceed 5 lines
- [ ] Benefits emphasized over features
- [ ] Clear visual hierarchy (headings, lists, formatting)
- [ ] Quick start section with minimal steps
- [ ] Code blocks properly formatted with language
- [ ] Links to detailed documentation
- [ ] Professional, welcoming tone

## References

**Primary Convention**: [README Quality Convention](../../../repo-governance/conventions/writing/readme-quality.md)

**Related Conventions**:

- [Content Quality Principles](../../../repo-governance/conventions/writing/quality.md) - Universal markdown standards
- [Accessibility First Principle](../../../repo-governance/principles/content/accessibility-first.md) - Accessibility requirements

**Related Skills**:

- `docs-applying-content-quality` - Universal content quality standards

---

This Skill packages README quality standards for creating engaging, accessible, scannable entry points for repositories and projects. For comprehensive details, consult the primary convention document.

```

```