wahidyankf 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 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 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
Related Conventions:
- Content Quality Principles - Universal markdown standards
- Accessibility First Principle - 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.