README.md Update Skill

This skill synchronizes an existing README.md with the latest code changes.

When to Use This Skill

•Refreshing README.md after code changes
•Checking README.md accuracy before PR/MR
•Updating docs after dependency/script updates
•Updating badges/text after version changes

Prerequisites

•README.md exists in the project root
•Changes are tracked in a Git repository

Step-by-Step Workflows

Workflow 1: Diff-Based Update

•
Check change diff
- •Use #changes to get Git diffs (staged/unstaged)
- •Classify changed files
•
Impact analysis
- •Decide whether README updates are needed using the matrix below
•
Load existing README
- •Use #readFile to inspect current section structure/content
- •Record section start/end lines
•
Update by section
- •Update only impacted sections
- •Do not change other sections
- •Use #editFiles to edit only target sections
•
Consistency checks
- •Validate badge URLs
- •Confirm commands in code blocks are up to date
- •Validate internal links (anchors/file links)
•
Report results
- •Output a summary of updated section diffs

Workflow 2: Full Review Update

•Read current full README.md with #readFile
•Analyze latest project state with document.readme.analyze
•Compare each section against current project state
•Identify outdated/misaligned sections
•Apply section-level updates

Impact Matrix

Impact by Changed File Type

Changed File	Impacted README Sections
`package.json` (dependencies)	Installation, Prerequisites
`package.json` (scripts)	Usage, Testing, Development
`package.json` (version)	Badges
`tsconfig.json` / build config	Installation, Development
`.github/workflows/*`	Badges (CI status)
`Dockerfile` / `docker-compose.yml`	Installation, Deployment
`.env.example`	Configuration (environment vars)
Source code under `src/`	Usage, API Reference
`LICENSE`	License
Added/removed directories	Directory Structure
New Agent/Skill/Prompt	Features, Usage, Directory Structure

Impact by Change Type

Change Type	README Update Needed
Comments/JSDoc only	❌
Formatting/indentation	❌
Type annotation changes	❌
Internal refactoring (no external interface change)	❌
Dependency add/remove	✅
npm script changes	✅
CLI command changes	✅
API endpoint additions/changes	✅
Environment variable additions/changes	✅
New feature added	✅
Directory structure changes	✅
License changes	✅
Version changes	✅

Section Update Templates

Version / Badge Update

markdown

<!-- Before -->
[![npm version](https://badge.fury.io/js/package%40old-version.svg)]()

<!-- After -->
[![npm version](https://badge.fury.io/js/package%40new-version.svg)]()

Environment Variable Section Update

When a new environment variable is detected from diffs:

markdown

## ⚙️ Configuration

| Environment Variable | Description | Default | Required |
|----------------------|-------------|---------|:--------:|
| `EXISTING_VAR` | Existing variable | `default` | ✅ |
| `NEW_VAR` | **New** - Description | - | ✅ |

Directory Structure Update

When new directories/files are added:

markdown

## 📁 Directory Structure

\```
project/
├── src/
├── tests/
├── new-directory/    # <- newly added
└── README.md
\```

Update Log

When README is updated, append this comment format at the end (optional):

markdown

<!-- README last updated: YYYY-MM-DD -->
<!-- Updated sections: Installation, Environment Variables -->

Troubleshooting

Problem	Solution
Unsure which sections to update	Use impact matrix
Changes are too broad	Consider full rewrite with `readme.generate`
README does not exist	Create new one with `readme.generate`
Broken badge URLs	Regenerate URLs via shields.io
Markdown syntax errors	Validate with markdownlint