update-readme

When to Use

• Updating existing README.md files
• Detecting outdated documentation
• Maintaining project documentation
• User asks to "update README" or "check documentation"

Instructions

When to Update

Trigger Events

Update the README when:

1. Before release - New version, feature, or fix
2. API changes - New functions, removed methods, signature changes
3. Dependency updates - Major version bumps (e.g., Node.js 18 → 20)
4. Breaking changes - Configuration, behavior, or API changes
5. Monthly review - Scheduled maintenance
6. After feedback - Users report confusion

Warning Signs

• "Requires Node.js 12+" but project uses Node 20
• Installation command doesn't work
• Examples throw errors
• API documentation doesn't match code
• Broken badges (red/404)

Step 1: Detect What Needs Updating

Use references/detection/ to find outdated content:

1. detect-changes.md - Compare code vs README
2. compare-sections.md - Section-by-section verification
3. outdated-detection.md - Common outdated patterns

Step 2: Update Sections

See references/sections-update/ for each section:

• installation.md - Package manager commands
• usage.md - Code examples
• api.md - Function signatures
• features.md - Feature list
• badges.md - Status badges
• requirements.md - Version requirements

Step 3: Use Checklist

Always verify with references/checklist.md:

• Installation commands work
• Usage examples run without errors
• API documentation matches code
• Badges show current status
• Requirements are current

Step 4: Automate Updates

Set up references/automation/ for continuous maintenance:

• github-actions.md - Auto-update workflows
• dynamic-badges.md - Live stats badges
• readme-lint.md - Automated checking

Commands

# Check package.json version
cat package.json | grep '"version"'

# Check required Node.js
cat package.json | grep '"engines"'

# List all dependencies
npm list --depth=0

# Check if badges work
curl -I https://img.shields.io/npm/v/package-name

# Check for outdated dependencies
npm outdated

# Check for broken links in README
npx markdown-link-check README.md

# Lint README
npx markdownlint README.md

Quick Detection Checklist

Run these commands to detect issues:

# Check package.json version
cat package.json | grep '"version"'

# Check required Node.js
cat package.json | grep '"engines"'

# List all dependencies
npm list --depth=0

# Check if badges work
curl -I https://img.shields.io/npm/v/package-name

Common Issues

See references/common-issues.md for solutions to:

• Outdated version numbers
• Broken installation commands
• Non-working code examples
• Missing API methods
• Incorrect badges
• Old requirements

Integration with create-readme

Use create-readme to:

1. Initial creation - Generate a new README
2. Major changes - Regenerate entire README
3. New project types - Different templates

Use this skill (update-readme) for:

1. Incremental updates - Keep current
2. Verification - Check accuracy
3. Automation - Set up auto-updates

Best Practices

Always

• Test installation commands
• Run code examples
• Verify API matches implementation
• Check badge URLs
• Update version numbers

Never

• Copy-paste without testing
• Trust old documentation
• Ignore broken badges
• Skip version bumps
• Leave outdated requirements

Automation

1. Set up GitHub Actions for stats
2. Use dynamic badges
3. Add README linter to CI
4. Schedule monthly reviews
5. Monitor for feedback

Resources

• Detection - Find outdated content
• Sections Update - Update specific sections
• Automation - Auto-update setup
• Checklist - Verification list
• Common Issues - Problem solutions