readme-writing-readme-fileslisted

# 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 ### Problem-Solution Hook **Start with WHY**: Begin with a clear problem-solution hook that immediately shows value. ✅ **Good opening**: ```markdown # Project Name **Problem**: Managing enterprise Shariah-compliant rules is complex and time-consuming. **Solution**: Open Sharia Enterprise provides automated, validated rule management. ``` ❌ **Weak opening**: ```markdown # Project Name This is a project that does things. ``` ### Plain Language Requirement **Avoid unexplained jargon**: Use plain language and explain technical terms on first use. ✅ **Good**: ```markdown Uses **Nx** (a monorepo build system) to manage multiple applications. ``` ❌ **Bad**: ```markdown Uses Nx for the monorepo. ← What's Nx? What's a monorepo? ``` **Acronym Context**: Define acronyms on first use. ✅ **Good**: `WCAG (Web Content Accessibility Guidelines)` ❌ **Bad**: `WCAG compliance required` ### Paragraph Length