readme-updates
Maintain README files with setup instructions, features, tech stack, and usage examples. Use when updating project documentation, adding new features, or improving onboarding.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- GitHub stars: 12
- Updated: 2025-12-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: readme-updates
description: Maintain README files with setup instructions, features, tech stack, and usage examples. Use when updating project documentation, adding new features, or improving onboarding.
allowed-tools: Read, Edit, Write, Bash, Grep, Glob
---
# README Updates Skill
This skill helps you create and maintain high-quality README files across the monorepo.
## When to Use This Skill
- Creating README for new packages
- Updating project features
- Documenting setup instructions
- Adding usage examples
- Updating tech stack information
- Adding badges and shields
- Improving documentation clarity
- Onboarding new contributors
## README Structure
### Root README.md
```markdown
# SG Cars Trends
[](LICENSE)
[](https://github.com/sgcarstrends/sgcarstrends/actions)
[](https://codecov.io/gh/sgcarstrends/sgcarstrends)
> Platform for accessing Singapore vehicle registration and COE bidding data
## Features
- 📊 **Comprehensive Data**: Access car registration and COE bidding data
- 🔄 **Real-time Updates**: Automated daily data updates from LTA DataMall
- 📝 **AI-Generated Blog**: Automated insights using Google Gemini
- 🔗 **Social Media**: Auto-post updates to Discord, LinkedIn, Telegram, Twitter
- 📈 **Interactive Charts**: Visualize trends with Recharts
- 🚀 **Modern Stack**: Next.js 16, Hono, SST v3, PostgreSQL, Redis
## Quick Start
```bash
# Clone repository
git clone https://github.com/sgcarstrends/sgcarstrends.git
cd sgcarstrends
# Install dependencies
pnpm install
# Set up environment variables
cp .env.example .env
# Run database migrations
pnpm db:migrate
# Start development servers
pnpm dev
\```
## Documentation
- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines
## Tech Stack
### Frontend
- **Next.js 16** - React framework with App Router
- **HeroUI** - React UI component library
- **Recharts** - Data visualization
- **Tailwind CSS** - Utility-first CSS
### Backend
- **Hono** - Fast web framework for Edge
- **Drizzle ORM** - TypeScript ORM
- **PostgreSQL** - Relational database
- **Upstash Redis** - Caching layer
### Infrastructure
- **SST v3** - Serverless framework
- **AWS Lambda** - Serverless compute
- **Cloudflare** - DNS and SSL
- **Vercel Blob** - File storage
### AI & Automation
- **Google Gemini** - AI blog generation
- **QStash** - Workflow engine
- **Better Auth** - Authentication
## Project Structure
```
sgcarstrends/
├── apps/
│ ├── api/ # Hono API service
│ ├── web/ # Next.js web app
│ └── admin/ # Admin panel
├── packages/
│ ├── database/ # Drizzle ORM schemas
│ ├── types/ # Shared TypeScript types
│ ├── ui/ # UI component library
│ ├── utils/ # Shared utilities
│ └── logos/ # Car logo management
└── infra/ # SST infrastructure
\```
## Development
```bash
# Start all development servers
pnpm dev
# Start specific service
pnpm -F @sgcarstrends/api dev
pnpm -F @sgcarstrends/web dev
# Run tests
pnpm test
# Build for production
pnpm build
# Lint and format
pnpm biome check --write .
\```
## Deployment
```bash
# Deploy to staging
pnpm deploy:staging
# Deploy to production
pnpm deploy:prod
\```
See deployment documentation for details.
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
[MIT](LICENSE) © SG Cars Trends
## Support
- **Issues**: [GitHub Issues](https://github.com/sgcarstrends/sgcarstrends/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sgcarstrends/sgcarstrends/discussions)
```
### Package README Template
```markdown
# @sgcarstrends/database
Database schema and migrations for SG Cars Trends using Drizzle ORM.
## Installation
```bash
pnpm add @sgcarstrends/database
\```
## Usage
```typescript
import { db } from "@sgcarstrends/database";
import { cars } from "@sgcarstrends/database/schema";
// Query cars
const allCars = await db.query.cars.findMany();
// Insert car
await db.insert(cars).values({
make: "Toyota",
model: "Corolla",
month: "2024-01",
number: 150,
});
\```
## Schema
### Cars Table
| Column | Type | Description |
|--------|------|-------------|
| `id` | `uuid` | Primary key |
| `make` | `text` | Car manufacturer |
| `model` | `text` | Car model |
| `month` | `text` | Registration month (YYYY-MM) |
| `number` | `integer` | Number of registrations |
## Migrations
```bash
# Generate migration
pnpm db:generate
# Run migrations
pnpm db:migrate
# Push schema (dev only)
pnpm db:push
\```
## Development
```bash
# Run tests
pnpm test
# Type check
pnpm tsc --noEmit
\```
## License
MIT
```
## README Components
### Badges
```markdown
<!-- License -->
[](LICENSE)
<!-- CI Status -->
[](https://github.com/user/repo/actions)
<!-- Coverage -->
[](https://codecov.io/gh/user/repo)
<!-- npm version -->
[](https://www.npmjs.com/package/@sgcarstrends/database)
<!-- Downloads -->
[](https://www.npmjs.com/package/@sgcarstrends/database)
<!-- TypeScript -->
[](https://www.typescriptlang.org/)
```
### Table of Contents
```markdown
## Table of Contents
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Development](#development)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [License](#license)
```
### Code Examples
```markdown
## Usage
### Basic Example
```typescript
import { db } from "@sgcarstrends/database";
const cars = await db.query.cars.findMany();
console.log(cars);
\```
### Advanced Example
```typescript
import { db } from "@sgcarstrends/database";
import { cars } from "@sgcarstrends/database/schema";
import { eq, desc } from "drizzle-orm";
// Get Toyota cars from January 2024
const toyotaCars = await db.query.cars.findMany({
where: eq(cars.make, "Toyota"),
orderBy: [desc(cars.number)],
limit: 10,
});
\```
```
### Screenshots
```markdown
## Screenshots
### Homepage
### Dashboard
```
### Features List
```markdown
## Features
- ✅ **Feature 1**: Description of feature 1
- ✅ **Feature 2**: Description of feature 2
- 🚧 **Upcoming**: Description of planned feature
- ❌ **Not Supported**: Description of unsupported feature
```
## Best Practices
### 1. Clear Project Description
```markdown
# ❌ Unclear
This is a project for cars.
# ✅ Clear
> Platform for accessing Singapore vehicle registration and COE bidding data with AI-generated insights
```
### 2. Installation Instructions
```markdown
# ❌ Incomplete
Install dependencies
# ✅ Complete
## Installation
\```bash
# Clone repository
git clone https://github.com/sgcarstrends/sgcarstrends.git
cd sgcarstrends
# Install dependencies
pnpm install
# Set up environment variables
cp .env.example .env
# Edit .env with your credentials
# Run migrations
pnpm db:migrate
# Start development server
pnpm dev
\```
```
### 3. Working Examples
```markdown
# ❌ Non-working example
\```typescript
import { db } from "database";
const data = await db.query();
\```
# ✅ Working example
\```typescript
import { db } from "@sgcarstrends/database";
import { cars } from "@sgcarstrends/database/schema";
const allCars = await db.query.cars.findMany();
console.log(`Found ${allCars.length} cars`);
\```
```
### 4. Links to Documentation
```markdown
# ❌ No documentation links
See docs for more info
# ✅ Linked documentation
For detailed documentation, see:
- [README](README.md) - Project overview
- [CLAUDE.md](CLAUDE.md) - Development guidelines
- [Contributing](CONTRIBUTING.md) - Contribution guidelines
```
## Maintaining README Files
### Update Checklist
- [ ] Update features list when new features added
- [ ] Update tech stack when dependencies change
- [ ] Update setup instructions when process changes
- [ ] Update badges (CI, coverage, version)
- [ ] Update screenshots for UI changes
- [ ] Update links (check for broken links)
- [ ] Update examples for API changes
- [ ] Add new sections as needed
### Check for Broken Links
```bash
# Install markdown-link-check
pnpm add -g markdown-link-check
# Check README for broken links
markdown-link-check README.md
# Check all README files
find . -name "README.md" -exec markdown-link-check {} \;
```
### Validate Markdown
```bash
# Install markdownlint
pnpm add -D markdownlint-cli
# Lint README
pnpm markdownlint README.md
# Fix issues automatically
pnpm markdownlint --fix README.md
```
## Template for New Packages
```markdown
# @sgcarstrends/[package-name]
> Brief description of what this package does
## Installation
\```bash
pnpm add @sgcarstrends/[package-name]
\```
## Usage
\```typescript
import { functionName } from "@sgcarstrends/[package-name]";
// Example usage
const result = functionName();
\```
## API
### `functionName(param: string): ReturnType`
Description of function.
**Parameters:**
- `param` (string): Description of parameter
**Returns:**
- `ReturnType`: Description of return value
**Example:**
\```typescript
const result = functionName("example");
\```
## Development
\```bash
# Run tests
pnpm test
# Build
pnpm build
# Type check
pnpm tsc --noEmit
\```
## License
MIT
```
## Common Sections
### Prerequisites
```markdown
## Prerequisites
Before you begin, ensure you have:
- **Node.js** 20 or later
- **pnpm** 8 or later
- **PostgreSQL** 14 or later
- **Redis** (via Upstash account)
```
### Environment Variables
```markdown
## Environment Variables
Create a `.env` file in the root directory:
\```env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/sgcarstrends
# Redis
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token
# API Keys
LTA_API_KEY=your-lta-api-key
GEMINI_API_KEY=your-gemini-api-key
\```
```
### Troubleshooting
```markdown
## Troubleshooting
### Database Connection Error
**Issue:** Cannot connect to database
**Solution:**
1. Verify DATABASE_URL is correct
2. Ensure PostgreSQL is running
3. Check firewall settings
### Build Fails
**Issue:** Build fails with TypeScript errors
**Solution:**
\```bash
# Clear caches
rm -rf node_modules .turbo dist
pnpm install
pnpm build
\```
```
## Automation
### Update Version Badge
```bash
# Get current version
VERSION=$(node -p "require('./package.json').version")
# Update badge in README
sed -i "s/version-[0-9.]*-blue/version-$VERSION-blue/" README.md
```
### Generate Table of Contents
```bash
# Install markdown-toc
pnpm add -g markdown-toc
# Generate TOC
markdown-toc -i README.md
```
## References
- Awesome README: https://github.com/matiassingers/awesome-readme
- Shields.io: https://shields.io (for badges)
- markdown-link-check: https://github.com/tcort/markdown-link-check
- markdownlint: https://github.com/DavidAnson/markdownlint
- Related files:
- `README.md` - Root README
- `packages/*/README.md` - Package READMEs
- Root CLAUDE.md - Documentation guidelines
## Best Practices Summary
1. **Clear Description**: Concise, clear project description at the top
2. **Quick Start**: Immediate value with quick start section
3. **Working Examples**: Provide copy-paste ready code examples
4. **Visual Aids**: Use screenshots, diagrams, and badges
5. **Complete Instructions**: Step-by-step setup and usage
6. **Link Documentation**: Link to comprehensive docs
7. **Keep Updated**: Regularly update when features change
8. **Check Links**: Regularly check for broken links