majiayu000 README Generation
Generate self-contained README files that enable developers to instantly understand any directory without reading parent or child documentation.
Temporary persona: Senior engineering manager with expertise in developer experience and technical onboarding.
When to Use This Skill
- Creating README for a new directory
- Updating existing README after structural changes
- Ensuring consistent documentation across repository
Core Philosophy
READMEs are entry points, not manuals.
| Principle | Implication |
|---|---|
| Self-contained | Stands alone - no need to read parent first |
| 30-second test | Purpose clear within 30 seconds of scanning |
| Context flows down | Provides context, links to children for details |
| Loose coupling | If directory moves, README still makes sense |
What Makes a README Effective
Good README:
- First 3 lines answer "What is this and why does it exist?"
- Structure visible at a glance (scannable headers)
- Links OUT to details, doesn't duplicate them
- Works as standalone landing page
Anti-patterns:
- Requires reading parent README to understand context
- Buries purpose below directory structure
- Duplicates content from other files
- Documents subdirectory internals (violates loose coupling)
- Over 100 lines (too much for quick orientation)
Documenting Patterns (Large/Flat Directories)
For directories with many similarly-named files, consider documenting the naming pattern instead of listing every file. This reduces maintenance when files are added or removed.
Example pattern table:
| Pattern | Purpose |
|---|---|
[type]-[tech-and-description].md |
Guides categorized by type |
[skill-name]/ |
Skill directories with standard structure |
Use your judgment - patterns work well for consistent naming conventions, explicit lists work better for small or varied collections.
Asset Resolution
- Check
./assets/readme-template.mdfor README template - If not found, search
**/readme-template.mdin repository - If still not found, use minimal structure from this skill
Directory Exploration
Preferred: Use tree command for hierarchical view (may not be installed on all systems):
tree -L 2 [directory] # 2-level depth
tree -L 1 --dirsfirst # Directories first, 1 level
Fallback: Use ls or IDE file listing for flat view.
Git Operations (Read-Only)
Setup: Pipe all git commands to cat to avoid interactive mode.
Safe commands: git status | cat, git ls-files | cat, git log --oneline -5 | cat
Forbidden: git commit, push, pull, merge, rebase, add, reset, clean, stash
Process
Step 1: Understand Context
- Read root README.md and parent README.md (if nested)
- Use
treeor list files at THIS level only (non-recursive) - Identify: What problem does this directory solve?
- Look for naming patterns in files/subdirectories
Step 2: Write with 30-Second Test in Mind
Structure for scannability:
- Title + metadata - identity
- Overview - what and why (most critical - first thing devs read)
- Directory structure or patterns - what's here (this level only)
- Quick links - where to go next
- Prerequisites/Getting Started - how to use (if operational)
- References - additional context
Step 3: Validate Self-Containment
Ask: "If a dev lands here with zero context, do they understand in 30 seconds?"
- Purpose clear without reading parent?
- No broken assumptions about prior knowledge?
- Links provide escape hatches to details?
Output Format
Present README in markdown following template structure. Target ~50 lines, max 100.
Constraints
- Self-contained: README makes sense without parent context
- 30-second rule: Purpose clear at first scan
- Non-recursive: Document THIS level only, link to subdirectory READMEs
- Pattern over listing: Consider documenting naming patterns for large directories
- Link to README.md: Use
[Dir](../dir/README.md)not../dir/ - KISS and DRY: Say it once, link elsewhere
- Characters: QWERTY keyboard typeable only - no em-dashes, smart quotes, emojis, or special Unicode
README Generation Skill v2.1.0 - KemingHe/common-devx