prulloac/readme-updater

README Updater

This skill helps maintain a consistent and up-to-date README.md file for your repository. It automates the process of extracting information from the project's codebase to ensure documentation is always in sync with implementation.

Features

1. Project Overview Synchronization: Updates the project description and features list based on the latest implementation.
2. Installation & Setup Tracking: Automatically detects project type (Node.js, Python, Rust, etc.) and updates setup/installation commands.
3. Usage Examples Generator: Scrapes code examples from test suites or examples/ directory and integrates them into the README.
4. Version and Changelog Linking: Keeps the current version and links to the CHANGELOG.md updated.
5. Dependency Visualization: Optionally generates or updates a list of main dependencies or a simple architecture overview.

Workflow

Step 1: Analyze the Workspace

Before updating, the agent must gather context about the project's current state.

• Check root files: Look for package.json, requirements.txt, Cargo.toml, go.mod, setup.py, etc.
• Determine project type: Identify the primary language and frameworks used
• Locate entry points: Find the main script or binary that users will interact with
• Extract metadata: Parse version, name, description from configuration files
• Discover dependencies: List main dependencies and development dependencies
• Find examples: Look for examples/, demo/, or test/ directories with usage samples

Step 2: Identify Update Scope

Determine what needs updating:

• README exists? If not, create from standard template
• Which sections? Analyze current README and identify stale sections
• Version changed? Compare README version with actual version in package.json, Cargo.toml, etc.
• Features updated? Check if new features need to be documented
• Dependencies changed? Verify dependency list is current
• Examples stale? Check if example code matches current API

Step 3: Extract Current Information

Build a profile of the project:

1. Project metadata: Name, description, version, repository URL
2. Installation instructions: Commands needed to set up the project
3. Usage examples: Working code examples from tests or examples directory
4. Configuration: Environment variables, config files, custom options
5. Dependencies: List of critical or main dependencies
6. Supported platforms: OS, Node versions, Python versions, etc.

Step 4: Update README Content

For each section that needs updating:

1. Project Overview (Top section):

   • Update project title and description
   • Add/update feature list
   • Add badges (downloads, version, license, build status)

2. Installation Section:

   • Update prerequisite list
   • Provide correct install commands for detected project type
   • Include multiple installation methods if applicable

3. Usage Section:

   • Add quick start example
   • Update command syntax if changed
   • Include common flags or options

4. Examples Section:

   • Extract or update code examples
   • Ensure examples actually work with current version
   • Add multiple usage scenarios

5. Configuration Section:

   • Document all environment variables
   • List configuration file locations and formats
   • Provide example configurations

6. Footer Sections:

   • Update Contributing link if CONTRIBUTING.md exists
   • Keep License reference current
   • Update version and changelog links

Step 5: Validation & Verification

Always verify the README's correctness after an update:

• ✅ All links are valid and pointing to correct files
• ✅ All commands are correct, tested, and up-to-date
• ✅ Installation steps match actual project requirements
• ✅ Code examples are syntactically correct and runnable
• ✅ Version numbers match across README and package.json/manifest files
• ✅ Tone remains consistent with original documentation
• ✅ No broken markdown syntax (proper formatting)
• ✅ Badge URLs and shields are current

Step 6: Summary & Report

Generate comprehensive update summary showing:

• What sections were modified
• What metadata was discovered and used
• Any detected issues or recommendations
• Before/after comparison of key sections

Concrete Examples

Example 1: Node.js Project Update

Project Type Detected: Node.js / TypeScript Files Scanned: package.json (v2.1.0), README.md (old, v1.5.0)

Before:

# my-awesome-cli

Command-line tool for development tasks.

## Installation

```bash
npm install -g my-awesome-cli

Usage

my-awesome-cli help

Features

• Task automation

**After:**
```markdown
# my-awesome-cli

[![npm version](https://img.shields.io/npm/v/my-awesome-cli.svg)](https://npmjs.org/package/my-awesome-cli)
[![npm downloads](https://img.shields.io/npm/dm/my-awesome-cli.svg)](https://npmjs.org/package/my-awesome-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/user/my-awesome-cli/blob/main/LICENSE)

Advanced command-line tool for automating development workflows with TypeScript support and interactive configuration.

## Features

- **Task Automation**: Easily define and run complex development tasks
- **TypeScript Support**: First-class TypeScript configuration and plugins
- **Interactive Config**: Interactive setup wizard for project configuration
- **Watch Mode**: Automatic task re-run on file changes
- **Plugin System**: Extend functionality with custom plugins

## Installation

### Prerequisites

- Node.js 16.0 or higher
- npm 7.0 or higher (or yarn/pnpm)

### Quick Start

```bash
# Install globally
npm install -g my-awesome-cli

# Or use npx (no installation required)
npx my-awesome-cli --version

Usage

Basic Commands

# Show help
my-awesome-cli help

# Initialize project
my-awesome-cli init

# Run a task
my-awesome-cli run build

# Watch mode
my-awesome-cli run build --watch

Examples

Initialize a new project:

my-awesome-cli init
# Follow the interactive prompts to set up your project

Create a custom task:

# Edit .myawesomerc.json
{
  "tasks": {
    "build": {
      "commands": ["npm run compile", "npm run bundle"]
    }
  }
}

Run with TypeScript:

my-awesome-cli run build --ts

Configuration

Environment Variables

• MY_AWESOME_CONFIG: Path to custom config file (default: .myawesomerc.json)
• MY_AWESOME_LOG_LEVEL: Logging level (debug, info, warn, error) (default: info)

Config File Format

Create .myawesomerc.json in your project root:

{
  "version": "1.0",
  "tasks": {
    "build": {
      "commands": ["npm run compile"]
    },
    "test": {
      "commands": ["npm test"]
    }
  },
  "plugins": ["@my-awesome-cli/typescript"]
}

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

License

This project is licensed under the MIT License - see LICENSE for details.

**Update Summary:**

═══════════════════════════════════════════════════════════ README UPDATE SUMMARY ═══════════════════════════════════════════════════════════

Project: my-awesome-cli Type: Node.js / TypeScript Status: ✅ SUCCESSFULLY UPDATED

─────────────────────────────────────────────────────────── CHANGES MADE ───────────────────────────────────────────────────────────

✅ Version Updated Old: v1.5.0 → New: v2.1.0 Source: package.json

✅ Badges Added

• npm version badge
• npm downloads badge
• MIT license badge

✅ Features Section Expanded Old: 2 features → New: 5 features with descriptions

✅ Installation Section Updated

• Added prerequisites section
• Included npx alternative
• Clearer quick start

✅ Usage Section Enhanced

• Reorganized commands
• Added watch mode flag
• TypeScript examples

✅ Examples Section Created

• Project initialization example
• Custom task configuration
• TypeScript usage example

✅ Configuration Section Added

• Environment variables documented
• Config file format with example
• Plugin system noted

✅ Contributing & License Links Updated

• Verified files exist
• Links are current

─────────────────────────────────────────────────────────── METADATA EXTRACTED ───────────────────────────────────────────────────────────

Name: my-awesome-cli Version: 2.1.0 Description: Advanced command-line tool for automating development workflows... Main Dependencies:

• commander@^11.0.0
• chalk@^5.0.0
• ora@^7.0.0

Dev Dependencies: @types/node, typescript, jest

Entry Point: bin/cli.ts

Supported Node Versions: >=16.0.0

═══════════════════════════════════════════════════════════

### Example 2: Python Project Update

**Project Type Detected**: Python / PyPI Package
**Files Scanned**: `pyproject.toml` (v0.3.0), `README.md` (v0.2.0)

**Before:**
```markdown
# my-python-lib

Python library for data processing.

## Installation

pip install my-python-lib

## Usage

from my_python_lib import process
result = process(data)

After:

# my-python-lib

[![PyPI version](https://img.shields.io/pypi/v/my-python-lib)](https://pypi.org/project/my-python-lib/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

High-performance data processing library for machine learning and data science workflows.

## Features

- **Fast Processing**: Optimized algorithms for large datasets
- **Type Hints**: Full type annotations for better IDE support
- **Async Support**: Built-in async/await support for concurrent operations
- **Comprehensive Logging**: Detailed logging for debugging and monitoring
- **Pandas Compatible**: Works seamlessly with pandas DataFrames

## Installation

### Requirements

- Python 3.8 or higher
- pip or conda

### From PyPI

```bash
pip install my-python-lib

From Conda

conda install -c conda-forge my-python-lib

Development Installation

git clone https://github.com/user/my-python-lib.git
cd my-python-lib
pip install -e ".[dev]"

Quick Start

from my_python_lib import DataProcessor

# Initialize processor
processor = DataProcessor(batch_size=1000)

# Process data
results = processor.transform(data, normalize=True)

# Get statistics
stats = processor.get_stats()
print(f"Processed {stats['count']} items in {stats['time']:.2f}s")

Usage Examples

Basic Data Processing

import pandas as pd
from my_python_lib import DataProcessor

# Load data
df = pd.read_csv('data.csv')

# Create processor
processor = DataProcessor()

# Process
result = processor.fit_transform(df)

Async Processing

import asyncio
from my_python_lib import AsyncDataProcessor

async def process_large_dataset():
    processor = AsyncDataProcessor(workers=4)
    results = await processor.transform(large_data)
    return results

# Run async processor
asyncio.run(process_large_dataset())

Custom Transformations

from my_python_lib import DataProcessor, transforms

processor = DataProcessor(
    transforms=[
        transforms.Normalize(),
        transforms.Impute(strategy='mean'),
        transforms.FeatureScale()
    ]
)

Configuration

Environment Variables

• MY_PYTHON_LIB_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR) (default: INFO)
• MY_PYTHON_LIB_WORKERS: Number of worker threads (default: CPU count)
• MY_PYTHON_LIB_CACHE_DIR: Directory for caching processed data (default: ~/.cache/my-python-lib)

Configuration via Code

from my_python_lib import config

config.set_log_level('DEBUG')
config.set_workers(8)
config.enable_caching(cache_dir='/tmp/cache')

API Reference

See API_REFERENCE.md for complete API documentation.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

Licensed under Apache License 2.0 - see LICENSE for details.

**Update Summary:**

═══════════════════════════════════════════════════════════ README UPDATE SUMMARY ═══════════════════════════════════════════════════════════

Project: my-python-lib Type: Python / PyPI Package Status: ✅ SUCCESSFULLY UPDATED

─────────────────────────────────────────────────────────── CHANGES MADE ───────────────────────────────────────────────────────────

✅ Version Updated Old: v0.2.0 → New: v0.3.0 Source: pyproject.toml

✅ Badges Added

• PyPI version badge
• Python 3.8+ requirement badge
• Apache 2.0 license badge

✅ Features Section Expanded Old: 1 feature → New: 5 features with descriptions

✅ Installation Section Restructured

• Added requirements section
• PyPI installation method
• Conda installation method
• Development installation steps

✅ Quick Start Section Added

• Simple example code
• Realistic use case

✅ Usage Examples Section Expanded

• Basic data processing example
• Async processing example
• Custom transformations example

✅ Configuration Section Added

• Environment variables documented
• Code-based configuration examples

✅ API Reference Link Added

• Points to docs/API_REFERENCE.md

─────────────────────────────────────────────────────────── METADATA EXTRACTED ───────────────────────────────────────────────────────────

Name: my-python-lib Version: 0.3.0 Description: High-performance data processing library for machine learning... Python Version: >=3.8 License: Apache-2.0

Main Dependencies:

• numpy>=1.20.0
• pandas>=1.3.0

Dev Dependencies:

• pytest
• black
• mypy
• sphinx

PyPI URL: https://pypi.org/project/my-python-lib/

═══════════════════════════════════════════════════════════

## Output Format Example

When the skill completes an update, it should provide a summary of changes:

### README Update Summary

- ✅ **Installation**: Updated installation section with new Python requirements
- ✅ **Usage**: Added async processing and custom configuration examples
- ✅ **Version**: Updated from v0.2.0 to v0.3.0 to match `pyproject.toml`
- ✅ **Features**: Expanded from 1 to 5 features with detailed descriptions
- ✅ **Badges**: Added PyPI, Python version, and license badges
- ✅ **Configuration**: Added environment variables and code-based setup guide

## References

- [README Template](references/readme_template.md) - Standard layout for project documentation.
- [Project Discovery Patterns](references/discovery_patterns.md) - How to find project info across different languages.