Skills

1---
2name: readme
3description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment.
4context: fork
5metadata:
6  author: Shpigford
7  version: "1.0"
8---
9 
10# README Generator
11 
12You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.
13 
14## The Three Purposes of a README
15 
161. **Local Development** - Help any developer get the app running locally in minutes
172. **Understanding the System** - Explain in great detail how the app works
183. **Production Deployment** - Cover everything needed to deploy and maintain in production
19 
20---
21 
22## Before Writing
23 
24### Step 1: Deep Codebase Exploration
25 
26Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
27 
28**Project Structure**
29- Read the root directory structure
30- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
31- Find the main entry point(s)
32- Map out the directory organization
33 
34**Configuration Files**
35- .env.example, .env.sample, or documented environment variables
36- Rails config files (config/database.yml, config/application.rb, config/environments/)
37- Credentials setup (config/credentials.yml.enc, config/master.key)
38- Docker files (Dockerfile, docker-compose.yml)
39- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
40- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
41 
42**Database**
43- db/schema.rb or db/structure.sql
44- Migrations in db/migrate/
45- Seeds in db/seeds.rb
46- Database type from config/database.yml
47 
48**Key Dependencies**
49- Gemfile and Gemfile.lock for Ruby gems
50- package.json for JavaScript dependencies
51- Note any native gem dependencies (pg, nokogiri, etc.)
52 
53**Scripts and Commands**
54- bin/ scripts (bin/dev, bin/setup, bin/ci)
55- Procfile or Procfile.dev
56- Rake tasks (lib/tasks/)
57 
58### Step 2: Identify Deployment Target
59 
60Look for these files to determine deployment platform and tailor instructions:
61 
62- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
63- `vercel.json` / `.vercel/` → Vercel
64- `netlify.toml` → Netlify
65- `fly.toml` → Fly.io
66- `railway.json` / `railway.toml` → Railway
67- `render.yaml` → Render
68- `app.yaml` → Google App Engine
69- `Procfile` → Heroku or Heroku-like platforms
70- `.ebextensions/` → AWS Elastic Beanstalk
71- `serverless.yml` → Serverless Framework
72- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
73- `k8s/` / `kubernetes/` → Kubernetes
74 
75If no deployment config exists, provide general guidance with Docker as the recommended approach.
76 
77### Step 3: Ask Only If Critical
78 
79Only ask the user questions if you cannot determine:
80- What the project does (if not obvious from code)
81- Specific deployment credentials or URLs needed
82- Business context that affects documentation
83 
84Otherwise, proceed with exploration and writing.
85 
86---
87 
88## README Structure
89 
90Write the README with these sections in order:
91 
92### 1. Project Title and Overview
93 
94```markdown
95# Project Name
96 
97Brief description of what the project does and who it's for. 2-3 sentences max.
98 
99## Key Features
100 
101- Feature 1
102- Feature 2
103- Feature 3
104```
105 
106### 2. Tech Stack
107 
108List all major technologies:
109 
110```markdown
111## Tech Stack
112 
113- **Language**: Ruby 3.3+
114- **Framework**: Rails 7.2+
115- **Frontend**: Inertia.js with React
116- **Database**: PostgreSQL 16
117- **Background Jobs**: Solid Queue
118- **Caching**: Solid Cache
119- **Styling**: Tailwind CSS
120- **Deployment**: [Detected platform]
121```
122 
123### 3. Prerequisites
124 
125What must be installed before starting:
126 
127```markdown
128## Prerequisites
129 
130- Node.js 20 or higher
131- PostgreSQL 15 or higher (or Docker)
132- pnpm (recommended) or npm
133- A Google Cloud project for OAuth (optional for development)
134```
135 
136### 4. Getting Started
137 
138The complete local development guide:
139 
140```markdown
141## Getting Started
142 
143### 1. Clone the Repository
144 
145\`\`\`bash
146git clone https://github.com/user/repo.git
147cd repo
148\`\`\`
149 
150### 2. Install Ruby Dependencies
151 
152Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):
153 
154\`\`\`bash
155bundle install
156\`\`\`
157 
158### 3. Install JavaScript Dependencies
159 
160\`\`\`bash
161yarn install
162\`\`\`
163 
164### 4. Environment Setup
165 
166Copy the example environment file:
167 
168\`\`\`bash
169cp .env.example .env
170\`\`\`
171 
172Configure the following variables:
173 
174| Variable | Description | Example |
175|----------|-------------|---------|
176| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
177| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
178| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
179| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
180 
181### 5. Database Setup
182 
183Start PostgreSQL (if using Docker):
184 
185\`\`\`bash
186docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
187\`\`\`
188 
189Create and set up the database:
190 
191\`\`\`bash
192bin/rails db:setup
193\`\`\`
194 
195This runs `db:create`, `db:schema:load`, and `db:seed`.
196 
197For existing databases, run migrations:
198 
199\`\`\`bash
200bin/rails db:migrate
201\`\`\`
202 
203### 6. Start Development Server
204 
205Using Foreman/Overmind (recommended, runs Rails + Vite):
206 
207\`\`\`bash
208bin/dev
209\`\`\`
210 
211Or manually:
212 
213\`\`\`bash
214# Terminal 1: Rails server
215bin/rails server
216 
217# Terminal 2: Vite dev server (for Inertia/React)
218bin/vite dev
219\`\`\`
220 
221Open [http://localhost:3000](http://localhost:3000) in your browser.
222```
223 
224Include every step. Assume the reader is setting up on a fresh machine.
225 
226### 5. Architecture Overview
227 
228This is where you go absurdly deep:
229 
230```markdown
231## Architecture
232 
233### Directory Structure
234 
235\`\`\`
236├── app/
237│   ├── controllers/         # Rails controllers
238│   │   ├── concerns/        # Shared controller modules
239│   │   └── api/             # API-specific controllers
240│   ├── models/              # ActiveRecord models
241│   │   └── concerns/        # Shared model modules
242│   ├── jobs/                # Background jobs (Solid Queue)
243│   ├── mailers/             # Email templates
244│   ├── views/               # Rails views (minimal with Inertia)
245│   └── frontend/            # Inertia.js React components
246│       ├── components/      # Reusable UI components
247│       ├── layouts/         # Page layouts
248│       ├── pages/           # Inertia page components
249│       └── lib/             # Frontend utilities
250├── config/
251│   ├── routes.rb            # Route definitions
252│   ├── database.yml         # Database configuration
253│   └── initializers/        # App initializers
254├── db/
255│   ├── migrate/             # Database migrations
256│   ├── schema.rb            # Current schema
257│   └── seeds.rb             # Seed data
258├── lib/
259│   └── tasks/               # Custom Rake tasks
260└── public/                  # Static assets
261\`\`\`
262 
263### Request Lifecycle
264 
2651. Request hits Rails router (`config/routes.rb`)
2662. Middleware stack processes request (authentication, sessions, etc.)
2673. Controller action executes
2684. Models interact with PostgreSQL via ActiveRecord
2695. Inertia renders React component with props
2706. Response sent to browser
271 
272### Data Flow
273 
274\`\`\`
275User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
276                                                        ↓
277                                       React Props ← Inertia Response ←
278\`\`\`
279 
280### Key Components
281 
282**Authentication**
283- Devise/Rodauth for user authentication
284- Session-based auth with encrypted cookies
285- `authenticate_user!` before_action for protected routes
286 
287**Inertia.js Integration (`app/frontend/`)**
288- React components receive props from Rails controllers
289- `inertia_render` in controllers passes data to frontend
290- Shared data via `inertia_share` for layout props
291 
292**Background Jobs (`app/jobs/`)**
293- Solid Queue for job processing
294- Jobs stored in PostgreSQL (no Redis required)
295- Dashboard at `/jobs` for monitoring
296 
297**Database (`app/models/`)**
298- ActiveRecord models with associations
299- Query objects for complex queries
300- Concerns for shared model behavior
301 
302### Database Schema
303 
304\`\`\`
305users
306├── id (bigint, PK)
307├── email (string, unique, not null)
308├── encrypted_password (string)
309├── name (string)
310├── created_at (datetime)
311└── updated_at (datetime)
312 
313posts
314├── id (bigint, PK)
315├── title (string, not null)
316├── content (text)
317├── published (boolean, default: false)
318├── user_id (bigint, FK → users)
319├── created_at (datetime)
320└── updated_at (datetime)
321 
322solid_queue_jobs (background jobs)
323├── id (bigint, PK)
324├── queue_name (string)
325├── class_name (string)
326├── arguments (json)
327├── scheduled_at (datetime)
328└── ...
329\`\`\`
330```
331 
332### 6. Environment Variables
333 
334Complete reference for all env vars:
335 
336```markdown
337## Environment Variables
338 
339### Required
340 
341| Variable | Description | How to Get |
342|----------|-------------|------------|
343| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
344| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
345| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
346 
347### Optional
348 
349| Variable | Description | Default |
350|----------|-------------|---------|
351| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
352| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
353| `RAILS_MAX_THREADS` | Puma thread count | `5` |
354| `WEB_CONCURRENCY` | Puma worker count | `2` |
355| `SMTP_ADDRESS` | Mail server hostname | - |
356| `SMTP_PORT` | Mail server port | `587` |
357 
358### Rails Credentials
359 
360Sensitive values should be stored in Rails encrypted credentials:
361 
362\`\`\`bash
363# Edit credentials (opens in $EDITOR)
364bin/rails credentials:edit
365 
366# Or for environment-specific credentials
367RAILS_ENV=production bin/rails credentials:edit
368\`\`\`
369 
370Credentials file structure:
371\`\`\`yaml
372secret_key_base: xxx
373stripe:
374  public_key: pk_xxx
375  secret_key: sk_xxx
376google:
377  client_id: xxx
378  client_secret: xxx
379\`\`\`
380 
381Access in code: `Rails.application.credentials.stripe[:secret_key]`
382 
383### Environment-Specific
384 
385**Development**
386\`\`\`
387DATABASE_URL=postgresql://localhost/myapp_development
388REDIS_URL=redis://localhost:6379/0
389\`\`\`
390 
391**Production**
392\`\`\`
393DATABASE_URL=<production-connection-string>
394RAILS_ENV=production
395RAILS_SERVE_STATIC_FILES=true
396\`\`\`
397```
398 
399### 7. Available Scripts
400 
401```markdown
402## Available Scripts
403 
404| Command | Description |
405|---------|-------------|
406| `bin/dev` | Start development server (Rails + Vite via Foreman) |
407| `bin/rails server` | Start Rails server only |
408| `bin/vite dev` | Start Vite dev server only |
409| `bin/rails console` | Open Rails console (IRB with app loaded) |
410| `bin/rails db:migrate` | Run pending database migrations |
411| `bin/rails db:rollback` | Rollback last migration |
412| `bin/rails db:seed` | Run database seeds |
413| `bin/rails db:reset` | Drop, create, migrate, and seed database |
414| `bin/rails routes` | List all routes |
415| `bin/rails test` | Run test suite (Minitest) |
416| `bundle exec rspec` | Run test suite (RSpec, if used) |
417| `bin/rails assets:precompile` | Compile assets for production |
418| `bin/rubocop` | Run Ruby linter |
419| `yarn lint` | Run JavaScript/TypeScript linter |
420```
421 
422### 8. Testing
423 
424```markdown
425## Testing
426 
427### Running Tests
428 
429\`\`\`bash
430# Run all tests (Minitest)
431bin/rails test
432 
433# Run all tests (RSpec, if used)
434bundle exec rspec
435 
436# Run specific test file
437bin/rails test test/models/user_test.rb
438bundle exec rspec spec/models/user_spec.rb
439 
440# Run tests matching a pattern
441bin/rails test -n /creates_user/
442bundle exec rspec -e "creates user"
443 
444# Run system tests (browser tests)
445bin/rails test:system
446 
447# Run with coverage (SimpleCov)
448COVERAGE=true bin/rails test
449\`\`\`
450 
451### Test Structure
452 
453\`\`\`
454test/                        # Minitest structure
455├── controllers/             # Controller tests
456├── models/                  # Model unit tests
457├── integration/             # Integration tests
458├── system/                  # System/browser tests
459├── fixtures/                # Test data
460└── test_helper.rb           # Test configuration
461 
462spec/                        # RSpec structure (if used)
463├── models/
464├── requests/
465├── system/
466├── factories/               # FactoryBot factories
467├── support/
468└── rails_helper.rb
469\`\`\`
470 
471### Writing Tests
472 
473**Minitest example:**
474\`\`\`ruby
475require "test_helper"
476 
477class UserTest < ActiveSupport::TestCase
478  test "creates user with valid attributes" do
479    user = User.new(email: "test@example.com", name: "Test User")
480    assert user.valid?
481  end
482 
483  test "requires email" do
484    user = User.new(name: "Test User")
485    assert_not user.valid?
486    assert_includes user.errors[:email], "can't be blank"
487  end
488end
489\`\`\`
490 
491**RSpec example:**
492\`\`\`ruby
493require "rails_helper"
494 
495RSpec.describe User, type: :model do
496  describe "validations" do
497    it "is valid with valid attributes" do
498      user = build(:user)
499      expect(user).to be_valid
500    end
501 
502    it "requires an email" do
503      user = build(:user, email: nil)
504      expect(user).not_to be_valid
505      expect(user.errors[:email]).to include("can't be blank")
506    end
507  end
508end
509\`\`\`
510 
511### Frontend Testing
512 
513For Inertia/React components:
514 
515\`\`\`bash
516yarn test
517\`\`\`
518 
519\`\`\`typescript
520import { render, screen } from '@testing-library/react'
521import { Dashboard } from './Dashboard'
522 
523describe('Dashboard', () => {
524  it('renders user name', () => {
525    render(<Dashboard user={{ name: 'Josh' }} />)
526    expect(screen.getByText('Josh')).toBeInTheDocument()
527  })
528})
529\`\`\`
530```
531 
532### 9. Deployment
533 
534Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
535 
536```markdown
537## Deployment
538 
539### Kamal (Recommended for Rails)
540 
541If using Kamal for deployment:
542 
543\`\`\`bash
544# Setup Kamal (first time)
545kamal setup
546 
547# Deploy
548kamal deploy
549 
550# Rollback to previous version
551kamal rollback
552 
553# View logs
554kamal app logs
555 
556# Run console on production
557kamal app exec --interactive 'bin/rails console'
558\`\`\`
559 
560Configuration lives in `config/deploy.yml`.
561 
562### Docker
563 
564Build and run:
565 
566\`\`\`bash
567# Build image
568docker build -t myapp .
569 
570# Run with environment variables
571docker run -p 3000:3000 \
572  -e DATABASE_URL=postgresql://... \
573  -e SECRET_KEY_BASE=... \
574  -e RAILS_ENV=production \
575  myapp
576\`\`\`
577 
578### Heroku
579 
580\`\`\`bash
581# Create app
582heroku create myapp
583 
584# Add PostgreSQL
585heroku addons:create heroku-postgresql:mini
586 
587# Set environment variables
588heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
589heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
590 
591# Deploy
592git push heroku main
593 
594# Run migrations
595heroku run bin/rails db:migrate
596\`\`\`
597 
598### Fly.io
599 
600\`\`\`bash
601# Launch (first time)
602fly launch
603 
604# Deploy
605fly deploy
606 
607# Run migrations
608fly ssh console -C "bin/rails db:migrate"
609 
610# Open console
611fly ssh console -C "bin/rails console"
612\`\`\`
613 
614### Render
615 
616If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
617 
618Manual setup:
6191. Create new Web Service
6202. Connect GitHub repository
6213. Set build command: `bundle install && bin/rails assets:precompile`
6224. Set start command: `bin/rails server`
6235. Add environment variables in dashboard
624 
625### Manual/VPS Deployment
626 
627\`\`\`bash
628# On the server:
629 
630# Pull latest code
631git pull origin main
632 
633# Install dependencies
634bundle install --deployment
635 
636# Compile assets
637RAILS_ENV=production bin/rails assets:precompile
638 
639# Run migrations
640RAILS_ENV=production bin/rails db:migrate
641 
642# Restart application server (e.g., Puma via systemd)
643sudo systemctl restart myapp
644\`\`\`
645```
646 
647### 10. Troubleshooting
648 
649```markdown
650## Troubleshooting
651 
652### Database Connection Issues
653 
654**Error:** `could not connect to server: Connection refused`
655 
656**Solution:**
6571. Verify PostgreSQL is running: `pg_isready` or `docker ps`
6582. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
6593. Ensure database exists: `bin/rails db:create`
660 
661### Pending Migrations
662 
663**Error:** `Migrations are pending`
664 
665**Solution:**
666\`\`\`bash
667bin/rails db:migrate
668\`\`\`
669 
670### Asset Compilation Issues
671 
672**Error:** `The asset "application.css" is not present in the asset pipeline`
673 
674**Solution:**
675\`\`\`bash
676# Clear and recompile assets
677bin/rails assets:clobber
678bin/rails assets:precompile
679\`\`\`
680 
681### Bundle Install Failures
682 
683**Error:** Native extension build failures
684 
685**Solution:**
6861. Ensure system dependencies are installed:
687   \`\`\`bash
688   # macOS
689   brew install postgresql libpq
690 
691   # Ubuntu
692   sudo apt-get install libpq-dev
693   \`\`\`
6942. Try again: `bundle install`
695 
696### Credentials Issues
697 
698**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`
699 
700**Solution:**
701The master key doesn't match the credentials file. Either:
7021. Get the correct `config/master.key` from another team member
7032. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
704 
705### Vite/Inertia Issues
706 
707**Error:** `Vite Ruby - Build failed`
708 
709**Solution:**
710\`\`\`bash
711# Clear Vite cache
712rm -rf node_modules/.vite
713 
714# Reinstall JS dependencies
715rm -rf node_modules && yarn install
716\`\`\`
717 
718### Solid Queue Issues
719 
720**Error:** Jobs not processing
721 
722**Solution:**
723Ensure the queue worker is running:
724\`\`\`bash
725bin/jobs
726# or
727bin/rails solid_queue:start
728\`\`\`
729```
730 
731### 11. Contributing (Optional)
732 
733Include if open source or team project.
734 
735### 12. License (Optional)
736 
737---
738 
739## Writing Principles
740 
7411. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.
742 
7432. **Use Code Blocks Liberally** - Every command should be copy-pasteable.
744 
7453. **Show Example Output** - When helpful, show what the user should expect to see.
746 
7474. **Explain the Why** - Don't just say "run this command," explain what it does.
748 
7495. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.
750 
7516. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.
752 
7537. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.
754 
7558. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.
756 
757---
758 
759## Output Format
760 
761Generate a complete README.md file with:
762- Proper markdown formatting
763- Code blocks with language hints (```bash, ```typescript, etc.)
764- Tables where appropriate
765- Clear section hierarchy
766- Linked table of contents for long documents
767 
768Write the README directly to `README.md` in the project root.
769