[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71HEM54NWPB1ADE1YM0NPPE":3,"skill-same:01M71HEM54NWPB1ADE1YM0NPPE":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":35,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":54,"install":55,"resources":68},"01M71HEM54NWPB1ADE1YM0NPPE","readme",null,"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.","JSGforever\u002Fskillguard","JSGforever","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F85541948?v=4","01M71FQD3E132VMR5F4TAYX3YS","01M71FQD4DYW0XJ4XQ4YQH75Y9",2,"MIT","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__baotoq--readme\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"README","write","file","document","use","deployment","for","project documentation","tree","project docs","safe","update","create","documentation","architecture","code","when","main","local","project","2026-11-10 10:12:30",false,"---\nname: readme\ndescription: \"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.\"\nsource: \"https:\u002F\u002Fgithub.com\u002FShpigford\u002Fskills\u002Ftree\u002Fmain\u002Freadme\"\nrisk: safe\nlicense: MIT\nmetadata:\n  version: \"1.0.0\"\n  domain: architecture\n  triggers: README, documentation, project docs, write readme, create readme\n  role: specialist\n  scope: implementation\n  output-format: code\n---\n\n# README Generator\n\nYou 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.\n\n## When to Use This Skill\n\nUse this skill when:\n\n- User wants to create or update a README.md file\n- User says \"write readme\" or \"create readme\"\n- User asks to \"document this project\"\n- User requests \"project documentation\"\n- User asks for help with README.md\n\n## The Three Purposes of a README\n\n1. **Local Development** - Help any developer get the app running locally in minutes\n2. **Understanding the System** - Explain in great detail how the app works\n3. **Production Deployment** - Cover everything needed to deploy and maintain in production\n\n---\n\n## Before Writing\n\n### Step 1: Deep Codebase Exploration\n\nBefore writing a single line of documentation, thoroughly explore the codebase. You MUST understand:\n\n**Project Structure**\n\n- Read the root directory structure\n- Identify the framework\u002Flanguage (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)\n- Find the main entry point(s)\n- Map out the directory organization\n\n**Configuration Files**\n\n- .env.example, .env.sample, or documented environment variables\n- Rails config files (config\u002Fdatabase.yml, config\u002Fapplication.rb, config\u002Fenvironments\u002F)\n- Credentials setup (config\u002Fcredentials.yml.enc, config\u002Fmaster.key)\n- Docker files (Dockerfile, docker-compose.yml)\n- CI\u002FCD configs (.github\u002Fworkflows\u002F, .gitlab-ci.yml, etc.)\n- Deployment configs (config\u002Fdeploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)\n\n**Database**\n\n- db\u002Fschema.rb or db\u002Fstructure.sql\n- Migrations in db\u002Fmigrate\u002F\n- Seeds in db\u002Fseeds.rb\n- Database type from config\u002Fdatabase.yml\n\n**Key Dependencies**\n\n- Gemfile and Gemfile.lock for Ruby gems\n- package.json for JavaScript dependencies\n- Note any native gem dependencies (pg, nokogiri, etc.)\n\n**Scripts and Commands**\n\n- bin\u002F scripts (bin\u002Fdev, bin\u002Fsetup, bin\u002Fci)\n- Procfile or Procfile.dev\n- Rake tasks (lib\u002Ftasks\u002F)\n\n### Step 2: Identify Deployment Target\n\nLook for these files to determine deployment platform and tailor instructions:\n\n- `Dockerfile` \u002F `docker-compose.yml` → Docker-based deployment\n- `vercel.json` \u002F `.vercel\u002F` → Vercel\n- `netlify.toml` → Netlify\n- `fly.toml` → Fly.io\n- `railway.json` \u002F `railway.toml` → Railway\n- `render.yaml` → Render\n- `app.yaml` → Google App Engine\n- `Procfile` → Heroku or Heroku-like platforms\n- `.ebextensions\u002F` → AWS Elastic Beanstalk\n- `serverless.yml` → Serverless Framework\n- `terraform\u002F` \u002F `*.tf` → Terraform\u002FInfrastructure as Code\n- `k8s\u002F` \u002F `kubernetes\u002F` → Kubernetes\n\nIf no deployment config exists, provide general guidance with Docker as the recommended approach.\n\n### Step 3: Ask Only If Critical\n\nOnly ask the user questions if you cannot determine:\n\n- What the project does (if not obvious from code)\n- Specific deployment credentials or URLs needed\n- Business context that affects documentation\n\nOtherwise, proceed with exploration and writing.\n\n---\n\n## README Structure\n\nWrite the README with these sections in order:\n\n### 1. Project Title and Overview\n\n```markdown\n# Project Name\n\nBrief description of what the project does and who it's for. 2-3 sentences max.\n\n## Key Features\n\n- Feature 1\n- Feature 2\n- Feature 3\n```\n\n### 2. Tech Stack\n\nList all major technologies:\n\n```markdown\n## Tech Stack\n\n- **Language**: Ruby 3.3+\n- **Framework**: Rails 7.2+\n- **Frontend**: Inertia.js with React\n- **Database**: PostgreSQL 16\n- **Background Jobs**: Solid Queue\n- **Caching**: Solid Cache\n- **Styling**: Tailwind CSS\n- **Deployment**: [Detected platform]\n```\n\n### 3. Prerequisites\n\nWhat must be installed before starting:\n\n```markdown\n## Prerequisites\n\n- Node.js 20 or higher\n- PostgreSQL 15 or higher (or Docker)\n- pnpm (recommended) or npm\n- A Google Cloud project for OAuth (optional for development)\n```\n\n### 4. Getting Started\n\nThe complete local development guide:\n\n```markdown\n## Getting Started\n\n### 1. Clone the Repository\n\n\\`\\`\\`bash\ngit clone https:\u002F\u002Fgithub.com\u002Fuser\u002Frepo.git\ncd repo\n\\`\\`\\`\n\n### 2. Install Ruby Dependencies\n\nEnsure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):\n\n\\`\\`\\`bash\nbundle install\n\\`\\`\\`\n\n### 3. Install JavaScript Dependencies\n\n\\`\\`\\`bash\nyarn install\n\\`\\`\\`\n\n### 4. Environment Setup\n\nCopy the example environment file:\n\n\\`\\`\\`bash\ncp .env.example .env\n\\`\\`\\`\n\nConfigure the following variables:\n\n| Variable           | Description                  | Example                                    |\n| ------------------ | ---------------------------- | ------------------------------------------ |\n| `DATABASE_URL`     | PostgreSQL connection string | `postgresql:\u002F\u002Flocalhost\u002Fmyapp_development` |\n| `REDIS_URL`        | Redis connection (if used)   | `redis:\u002F\u002Flocalhost:6379\u002F0`                 |\n| `SECRET_KEY_BASE`  | Rails secret key             | `bin\u002Frails secret`                         |\n| `RAILS_MASTER_KEY` | For credentials encryption   | Check `config\u002Fmaster.key`                  |\n\n### 5. Database Setup\n\nStart PostgreSQL (if using Docker):\n\n\\`\\`\\`bash\ndocker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16\n\\`\\`\\`\n\nCreate and set up the database:\n\n\\`\\`\\`bash\nbin\u002Frails db:setup\n\\`\\`\\`\n\nThis runs `db:create`, `db:schema:load`, and `db:seed`.\n\nFor existing databases, run migrations:\n\n\\`\\`\\`bash\nbin\u002Frails db:migrate\n\\`\\`\\`\n\n### 6. Start Development Server\n\nUsing Foreman\u002FOvermind (recommended, runs Rails + Vite):\n\n\\`\\`\\`bash\nbin\u002Fdev\n\\`\\`\\`\n\nOr manually:\n\n\\`\\`\\`bash\n\n# Terminal 1: Rails server\n\nbin\u002Frails server\n\n# Terminal 2: Vite dev server (for Inertia\u002FReact)\n\nbin\u002Fvite dev\n\\`\\`\\`\n\nOpen [http:\u002F\u002Flocalhost:3000](http:\u002F\u002Flocalhost:3000) in your browser.\n```\n\nInclude every step. Assume the reader is setting up on a fresh machine.\n\n### 5. Architecture Overview\n\nThis is where you go absurdly deep:\n\n```markdown\n## Architecture\n\n### Directory Structure\n\n\\`\\`\\`\n├── app\u002F\n│ ├── controllers\u002F # Rails controllers\n│ │ ├── concerns\u002F # Shared controller modules\n│ │ └── api\u002F # API-specific controllers\n│ ├── models\u002F # ActiveRecord models\n│ │ └── concerns\u002F # Shared model modules\n│ ├── jobs\u002F # Background jobs (Solid Queue)\n│ ├── mailers\u002F # Email templates\n│ ├── views\u002F # Rails views (minimal with Inertia)\n│ └── frontend\u002F # Inertia.js React components\n│ ├── components\u002F # Reusable UI components\n│ ├── layouts\u002F # Page layouts\n│ ├── pages\u002F # Inertia page components\n│ └── lib\u002F # Frontend utilities\n├── config\u002F\n│ ├── routes.rb # Route definitions\n│ ├── database.yml # Database configuration\n│ └── initializers\u002F # App initializers\n├── db\u002F\n│ ├── migrate\u002F # Database migrations\n│ ├── schema.rb # Current schema\n│ └── seeds.rb # Seed data\n├── lib\u002F\n│ └── tasks\u002F # Custom Rake tasks\n└── public\u002F # Static assets\n\\`\\`\\`\n\n### Request Lifecycle\n\n1. Request hits Rails router (`config\u002Froutes.rb`)\n2. Middleware stack processes request (authentication, sessions, etc.)\n3. Controller action executes\n4. Models interact with PostgreSQL via ActiveRecord\n5. Inertia renders React component with props\n6. Response sent to browser\n\n### Data Flow\n\n\\`\\`\\`\nUser Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL\n↓\nReact Props ← Inertia Response ←\n\\`\\`\\`\n\n### Key Components\n\n**Authentication**\n\n- Devise\u002FRodauth for user authentication\n- Session-based auth with encrypted cookies\n- `authenticate_user!` before_action for protected routes\n\n**Inertia.js Integration (`app\u002Ffrontend\u002F`)**\n\n- React components receive props from Rails controllers\n- `inertia_render` in controllers passes data to frontend\n- Shared data via `inertia_share` for layout props\n\n**Background Jobs (`app\u002Fjobs\u002F`)**\n\n- Solid Queue for job processing\n- Jobs stored in PostgreSQL (no Redis required)\n- Dashboard at `\u002Fjobs` for monitoring\n\n**Database (`app\u002Fmodels\u002F`)**\n\n- ActiveRecord models with associations\n- Query objects for complex queries\n- Concerns for shared model behavior\n\n### Database Schema\n\n\\`\\`\\`\nusers\n├── id (bigint, PK)\n├── email (string, unique, not null)\n├── encrypted_password (string)\n├── name (string)\n├── created_at (datetime)\n└── updated_at (datetime)\n\nposts\n├── id (bigint, PK)\n├── title (string, not null)\n├── content (text)\n├── published (boolean, default: false)\n├── user_id (bigint, FK → users)\n├── created_at (datetime)\n└── updated_at (datetime)\n\nsolid_queue_jobs (background jobs)\n├── id (bigint, PK)\n├── queue_name (string)\n├── class_name (string)\n├── arguments (json)\n├── scheduled_at (datetime)\n└── ...\n\\`\\`\\`\n```\n\n### 6. Environment Variables\n\nComplete reference for all env vars:\n\n```markdown\n## Environment Variables\n\n### Required\n\n| Variable           | Description                       | How to Get                             |\n| ------------------ | --------------------------------- | -------------------------------------- |\n| `DATABASE_URL`     | PostgreSQL connection string      | Your database provider                 |\n| `SECRET_KEY_BASE`  | Rails secret for sessions\u002Fcookies | Run `bin\u002Frails secret`                 |\n| `RAILS_MASTER_KEY` | Decrypts credentials file         | Check `config\u002Fmaster.key` (not in git) |\n\n### Optional\n\n| Variable            | Description                                       | Default                      |\n| ------------------- | ------------------------------------------------- | ---------------------------- |\n| `REDIS_URL`         | Redis connection string (for caching\u002FActionCable) | -                            |\n| `RAILS_LOG_LEVEL`   | Logging verbosity                                 | `debug` (dev), `info` (prod) |\n| `RAILS_MAX_THREADS` | Puma thread count                                 | `5`                          |\n| `WEB_CONCURRENCY`   | Puma worker count                                 | `2`                          |\n| `SMTP_ADDRESS`      | Mail server hostname                              | -                            |\n| `SMTP_PORT`         | Mail server port                                  | `587`                        |\n\n### Rails Credentials\n\nSensitive values should be stored in Rails encrypted credentials:\n\n\\`\\`\\`bash\n\n# Edit credentials (opens in $EDITOR)\n\nbin\u002Frails credentials:edit\n\n# Or for environment-specific credentials\n\nRAILS_ENV=production bin\u002Frails credentials:edit\n\\`\\`\\`\n\nCredentials file structure:\n\\`\\`\\`yaml\nsecret_key_base: xxx\nstripe:\npublic_key: pk_xxx\nsecret_key: sk_xxx\ngoogle:\nclient_id: xxx\nclient_secret: xxx\n\\`\\`\\`\n\nAccess in code: `Rails.application.credentials.stripe[:secret_key]`\n\n### Environment-Specific\n\n**Development**\n\\`\\`\\`\nDATABASE_URL=postgresql:\u002F\u002Flocalhost\u002Fmyapp_development\nREDIS_URL=redis:\u002F\u002Flocalhost:6379\u002F0\n\\`\\`\\`\n\n**Production**\n\\`\\`\\`\nDATABASE_URL=\u003Cproduction-connection-string>\nRAILS_ENV=production\nRAILS_SERVE_STATIC_FILES=true\n\\`\\`\\`\n```\n\n### 7. Available Scripts\n\n```markdown\n## Available Scripts\n\n| Command                       | Description                                         |\n| ----------------------------- | --------------------------------------------------- |\n| `bin\u002Fdev`                     | Start development server (Rails + Vite via Foreman) |\n| `bin\u002Frails server`            | Start Rails server only                             |\n| `bin\u002Fvite dev`                | Start Vite dev server only                          |\n| `bin\u002Frails console`           | Open Rails console (IRB with app loaded)            |\n| `bin\u002Frails db:migrate`        | Run pending database migrations                     |\n| `bin\u002Frails db:rollback`       | Rollback last migration                             |\n| `bin\u002Frails db:seed`           | Run database seeds                                  |\n| `bin\u002Frails db:reset`          | Drop, create, migrate, and seed database            |\n| `bin\u002Frails routes`            | List all routes                                     |\n| `bin\u002Frails test`              | Run test suite (Minitest)                           |\n| `bundle exec rspec`           | Run test suite (RSpec, if used)                     |\n| `bin\u002Frails assets:precompile` | Compile assets for production                       |\n| `bin\u002Frubocop`                 | Run Ruby linter                                     |\n| `yarn lint`                   | Run JavaScript\u002FTypeScript linter                    |\n```\n\n### 8. Testing\n\n```markdown\n## Testing\n\n### Running Tests\n\n\\`\\`\\`bash\n\n# Run all tests (Minitest)\n\nbin\u002Frails test\n\n# Run all tests (RSpec, if used)\n\nbundle exec rspec\n\n# Run specific test file\n\nbin\u002Frails test test\u002Fmodels\u002Fuser_test.rb\nbundle exec rspec spec\u002Fmodels\u002Fuser_spec.rb\n\n# Run tests matching a pattern\n\nbin\u002Frails test -n \u002Fcreates_user\u002F\nbundle exec rspec -e \"creates user\"\n\n# Run system tests (browser tests)\n\nbin\u002Frails test:system\n\n# Run with coverage (SimpleCov)\n\nCOVERAGE=true bin\u002Frails test\n\\`\\`\\`\n\n### Test Structure\n\n\\`\\`\\`\ntest\u002F # Minitest structure\n├── controllers\u002F # Controller tests\n├── models\u002F # Model unit tests\n├── integration\u002F # Integration tests\n├── system\u002F # System\u002Fbrowser tests\n├── fixtures\u002F # Test data\n└── test_helper.rb # Test configuration\n\nspec\u002F # RSpec structure (if used)\n├── models\u002F\n├── requests\u002F\n├── system\u002F\n├── factories\u002F # FactoryBot factories\n├── support\u002F\n└── rails_helper.rb\n\\`\\`\\`\n\n### Writing Tests\n\n**Minitest example:**\n\\`\\`\\`ruby\nrequire \"test_helper\"\n\nclass UserTest \u003C ActiveSupport::TestCase\ntest \"creates user with valid attributes\" do\nuser = User.new(email: \"test@example.com\", name: \"Test User\")\nassert user.valid?\nend\n\ntest \"requires email\" do\nuser = User.new(name: \"Test User\")\nassert_not user.valid?\nassert_includes user.errors[:email], \"can't be blank\"\nend\nend\n\\`\\`\\`\n\n**RSpec example:**\n\\`\\`\\`ruby\nrequire \"rails_helper\"\n\nRSpec.describe User, type: :model do\ndescribe \"validations\" do\nit \"is valid with valid attributes\" do\nuser = build(:user)\nexpect(user).to be_valid\nend\n\n    it \"requires an email\" do\n      user = build(:user, email: nil)\n      expect(user).not_to be_valid\n      expect(user.errors[:email]).to include(\"can't be blank\")\n    end\n\nend\nend\n\\`\\`\\`\n\n### Frontend Testing\n\nFor Inertia\u002FReact components:\n\n\\`\\`\\`bash\nyarn test\n\\`\\`\\`\n\n\\`\\`\\`typescript\nimport { render, screen } from '@testing-library\u002Freact'\nimport { Dashboard } from '.\u002FDashboard'\n\ndescribe('Dashboard', () => {\nit('renders user name', () => {\nrender(\u003CDashboard user={{ name: 'Josh' }} \u002F>)\nexpect(screen.getByText('Josh')).toBeInTheDocument()\n})\n})\n\\`\\`\\`\n```\n\n### 9. Deployment\n\nTailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal\u002F, etc.):\n\n```markdown\n## Deployment\n\n### Kamal (Recommended for Rails)\n\nIf using Kamal for deployment:\n\n\\`\\`\\`bash\n\n# Setup Kamal (first time)\n\nkamal setup\n\n# Deploy\n\nkamal deploy\n\n# Rollback to previous version\n\nkamal rollback\n\n# View logs\n\nkamal app logs\n\n# Run console on production\n\nkamal app exec --interactive 'bin\u002Frails console'\n\\`\\`\\`\n\nConfiguration lives in `config\u002Fdeploy.yml`.\n\n### Docker\n\nBuild and run:\n\n\\`\\`\\`bash\n\n# Build image\n\ndocker build -t myapp .\n\n# Run with environment variables\n\ndocker run -p 3000:3000 \\\n -e DATABASE_URL=postgresql:\u002F\u002F... \\\n -e SECRET_KEY_BASE=... \\\n -e RAILS_ENV=production \\\n myapp\n\\`\\`\\`\n\n### Heroku\n\n\\`\\`\\`bash\n\n# Create app\n\nheroku create myapp\n\n# Add PostgreSQL\n\nheroku addons:create heroku-postgresql:mini\n\n# Set environment variables\n\nheroku config:set SECRET_KEY_BASE=$(bin\u002Frails secret)\nheroku config:set RAILS_MASTER_KEY=$(cat config\u002Fmaster.key)\n\n# Deploy\n\ngit push heroku main\n\n# Run migrations\n\nheroku run bin\u002Frails db:migrate\n\\`\\`\\`\n\n### Fly.io\n\n\\`\\`\\`bash\n\n# Launch (first time)\n\nfly launch\n\n# Deploy\n\nfly deploy\n\n# Run migrations\n\nfly ssh console -C \"bin\u002Frails db:migrate\"\n\n# Open console\n\nfly ssh console -C \"bin\u002Frails console\"\n\\`\\`\\`\n\n### Render\n\nIf `render.yaml` exists, connect your repo to Render and it will auto-deploy.\n\nManual setup:\n\n1. Create new Web Service\n2. Connect GitHub repository\n3. Set build command: `bundle install && bin\u002Frails assets:precompile`\n4. Set start command: `bin\u002Frails server`\n5. Add environment variables in dashboard\n\n### Manual\u002FVPS Deployment\n\n\\`\\`\\`bash\n\n# On the server:\n\n# Pull latest code\n\ngit pull origin main\n\n# Install dependencies\n\nbundle install --deployment\n\n# Compile assets\n\nRAILS_ENV=production bin\u002Frails assets:precompile\n\n# Run migrations\n\nRAILS_ENV=production bin\u002Frails db:migrate\n\n# Restart application server (e.g., Puma via systemd)\n\nsudo systemctl restart myapp\n\\`\\`\\`\n```\n\n### 10. Troubleshooting\n\n```markdown\n## Troubleshooting\n\n### Database Connection Issues\n\n**Error:** `could not connect to server: Connection refused`\n\n**Solution:**\n\n1. Verify PostgreSQL is running: `pg_isready` or `docker ps`\n2. Check `DATABASE_URL` format: `postgresql:\u002F\u002FUSER:PASSWORD@HOST:PORT\u002FDATABASE`\n3. Ensure database exists: `bin\u002Frails db:create`\n\n### Pending Migrations\n\n**Error:** `Migrations are pending`\n\n**Solution:**\n\\`\\`\\`bash\nbin\u002Frails db:migrate\n\\`\\`\\`\n\n### Asset Compilation Issues\n\n**Error:** `The asset \"application.css\" is not present in the asset pipeline`\n\n**Solution:**\n\\`\\`\\`bash\n\n# Clear and recompile assets\n\nbin\u002Frails assets:clobber\nbin\u002Frails assets:precompile\n\\`\\`\\`\n\n### Bundle Install Failures\n\n**Error:** Native extension build failures\n\n**Solution:**\n\n1. Ensure system dependencies are installed:\n   \\`\\`\\`bash\n\n   # macOS\n\n   brew install postgresql libpq\n\n   # Ubuntu\n\n   sudo apt-get install libpq-dev\n   \\`\\`\\`\n\n2. Try again: `bundle install`\n\n### Credentials Issues\n\n**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`\n\n**Solution:**\nThe master key doesn't match the credentials file. Either:\n\n1. Get the correct `config\u002Fmaster.key` from another team member\n2. Or regenerate credentials: `rm config\u002Fcredentials.yml.enc && bin\u002Frails credentials:edit`\n\n### Vite\u002FInertia Issues\n\n**Error:** `Vite Ruby - Build failed`\n\n**Solution:**\n\\`\\`\\`bash\n\n# Clear Vite cache\n\nrm -rf node_modules\u002F.vite\n\n# Reinstall JS dependencies\n\nrm -rf node_modules && yarn install\n\\`\\`\\`\n\n### Solid Queue Issues\n\n**Error:** Jobs not processing\n\n**Solution:**\nEnsure the queue worker is running:\n\\`\\`\\`bash\nbin\u002Fjobs\n\n# or\n\nbin\u002Frails solid_queue:start\n\\`\\`\\`\n```\n\n### 11. Contributing (Optional)\n\nInclude if open source or team project.\n\n### 12. License (Optional)\n\n---\n\n## Writing Principles\n\n1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.\n\n2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.\n\n3. **Show Example Output** - When helpful, show what the user should expect to see.\n\n4. **Explain the Why** - Don't just say \"run this command,\" explain what it does.\n\n5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.\n\n6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.\n\n7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.\n\n8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.\n\n---\n\n## Output Format\n\nGenerate a complete README.md file with:\n\n- Proper markdown formatting\n- Code blocks with language hints (`bash, `typescript, etc.)\n- Tables where appropriate\n- Clear section hierarchy\n- Linked table of contents for long documents\n\nWrite the README directly to `README.md` in the project root.\n","# README Generator\n\nYou 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.\n\n## When to Use This Skill\n\nUse this skill when:\n\n- User wants to create or update a README.md file\n- User says \"write readme\" or \"create readme\"\n- User asks to \"document this project\"\n- User requests \"project documentation\"\n- User asks for help with README.md\n\n## The Three Purposes of a README\n\n1. **Local Development** - Help any developer get the app running locally in minutes\n2. **Understanding the System** - Explain in great detail how the app works\n3. **Production Deployment** - Cover everything needed to deploy and maintain in production\n\n---\n\n## Before Writing\n\n### Step 1: Deep Codebase Exploration\n\nBefore writing a single line of documentation, thoroughly explore the codebase. You MUST understand:\n\n**Project Structure**\n\n- Read the root directory structure\n- Identify the framework\u002Flanguage (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)\n- Find the main entry point(s)\n- Map out the directory organization\n\n**Configuration Files**\n\n- .env.example, .env.sample, or documented environment variables\n- Rails config files (config\u002Fdatabase.yml, config\u002Fapplication.rb, config\u002Fenvironments\u002F)\n- Credentials setup (config\u002Fcredentials.yml.enc, config\u002Fmaster.key)\n- Docker files (Dockerfile, docker-compose.yml)\n- CI\u002FCD configs (.github\u002Fworkflows\u002F, .gitlab-ci.yml, etc.)\n- Deployment configs (config\u002Fdeploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)\n\n**Database**\n\n- db\u002Fschema.rb or db\u002Fstructure.sql\n- Migrations in db\u002Fmigrate\u002F\n- Seeds in db\u002Fseeds.rb\n- Database type from config\u002Fdatabase.yml\n\n**Key Dependencies**\n\n- Gemfile and Gemfile.lock for Ruby gems\n- package.json for JavaScript dependencies\n- Note any native gem dependencies (pg, nokogiri, etc.)\n\n**Scripts and Commands**\n\n- bin\u002F scripts (bin\u002Fdev, bin\u002Fsetup, bin\u002Fci)\n- Procfile or Procfile.dev\n- Rake tasks (lib\u002Ftasks\u002F)\n\n### Step 2: Identify Deployment Target\n\nLook for these files to determine deployment platform and tailor instructions:\n\n- `Dockerfile` \u002F `docker-compose.yml` → Docker-based deployment\n- `vercel.json` \u002F `.vercel\u002F` → Vercel\n- `netlify.toml` → Netlify\n- `fly.toml` → Fly.io\n- `railway.json` \u002F `railway.toml` → Railway\n- `render.yaml` → Render\n- `app.yaml` → Google App Engine\n- `Procfile` → Heroku or Heroku-like platforms\n- `.ebextensions\u002F` → AWS Elastic Beanstalk\n- `serverless.yml` → Serverless Framework\n- `terraform\u002F` \u002F `*.tf` → Terraform\u002FInfrastructure as Code\n- `k8s\u002F` \u002F `kubernetes\u002F` → Kubernetes\n\nIf no deployment config exists, provide general guidance with Docker as the recommended approach.\n\n### Step 3: Ask Only If Critical\n\nOnly ask the user questions if you cannot determine:\n\n- What the project does (if not obvious from code)\n- Specific deployment credentials or URLs needed\n- Business context that affects documentation\n\nOtherwise, proceed with exploration and writing.\n\n---\n\n## README Structure\n\nWrite the README with these sections in order:\n\n### 1. Project Title and Overview\n\n```markdown\n# Project Name\n\nBrief description of what the project does and who it's for. 2-3 sentences max.\n\n## Key Features\n\n- Feature 1\n- Feature 2\n- Feature 3\n```\n\n### 2. Tech Stack\n\nList all major technologies:\n\n```markdown\n## Tech Stack\n\n- **Language**: Ruby 3.3+\n- **Framework**: Rails 7.2+\n- **Frontend**: Inertia.js with React\n- **Database**: PostgreSQL 16\n- **Background Jobs**: Solid Queue\n- **Caching**: Solid Cache\n- **Styling**: Tailwind CSS\n- **Deployment**: [Detected platform]\n```\n\n### 3. Prerequisites\n\nWhat must be installed before starting:\n\n```markdown\n## Prerequisites\n\n- Node.js 20 or higher\n- PostgreSQL 15 or higher (or Docker)\n- pnpm (recommended) or npm\n- A Google Cloud project for OAuth (optional for development)\n```\n\n### 4. Getting Started\n\nThe complete local development guide:\n\n```markdown\n## Getting Started\n\n### 1. Clone the Repository\n\n\\`\\`\\`bash\ngit clone https:\u002F\u002Fgithub.com\u002Fuser\u002Frepo.git\ncd repo\n\\`\\`\\`\n\n### 2. Install Ruby Dependencies\n\nEnsure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):\n\n\\`\\`\\`bash\nbundle install\n\\`\\`\\`\n\n### 3. Install JavaScript Dependencies\n\n\\`\\`\\`bash\nyarn install\n\\`\\`\\`\n\n### 4. Environment Setup\n\nCopy the example environment file:\n\n\\`\\`\\`bash\ncp .env.example .env\n\\`\\`\\`\n\nConfigure the following variables:\n\n| Variable           | Description                  | Example                                    |\n| ------------------ | ---------------------------- | ------------------------------------------ |\n| `DATABASE_URL`     | PostgreSQL connection string | `postgresql:\u002F\u002Flocalhost\u002Fmyapp_development` |\n| `REDIS_URL`        | Redis connection (if used)   | `redis:\u002F\u002Flocalhost:6379\u002F0`                 |\n| `SECRET_KEY_BASE`  | Rails secret key             | `bin\u002Frails secret`                         |\n| `RAILS_MASTER_KEY` | For credentials encryption   | Check `config\u002Fmaster.key`                  |\n\n### 5. Database Setup\n\nStart PostgreSQL (if using Docker):\n\n\\`\\`\\`bash\ndocker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16\n\\`\\`\\`\n\nCreate and set up the database:\n\n\\`\\`\\`bash\nbin\u002Frails db:setup\n\\`\\`\\`\n\nThis runs `db:create`, `db:schema:load`, and `db:seed`.\n\nFor existing databases, run migrations:\n\n\\`\\`\\`bash\nbin\u002Frails db:migrate\n\\`\\`\\`\n\n### 6. Start Development Server\n\nUsing Foreman\u002FOvermind (recommended, runs Rails + Vite):\n\n\\`\\`\\`bash\nbin\u002Fdev\n\\`\\`\\`\n\nOr manually:\n\n\\`\\`\\`bash\n\n# Terminal 1: Rails server\n\nbin\u002Frails server\n\n# Terminal 2: Vite dev server (for Inertia\u002FReact)\n\nbin\u002Fvite dev\n\\`\\`\\`\n\nOpen [http:\u002F\u002Flocalhost:3000](http:\u002F\u002Flocalhost:3000) in your browser.\n```\n\nInclude every step. Assume the reader is setting up on a fresh machine.\n\n### 5. Architecture Overview\n\nThis is where you go absurdly deep:\n\n```markdown\n## Architecture\n\n### Directory Structure\n\n\\`\\`\\`\n├── app\u002F\n│ ├── controllers\u002F # Rails controllers\n│ │ ├── concerns\u002F # Shared controller modules\n│ │ └── api\u002F # API-specific controllers\n│ ├── models\u002F # ActiveRecord models\n│ │ └── concerns\u002F # Shared model modules\n│ ├── jobs\u002F # Background jobs (Solid Queue)\n│ ├── mailers\u002F # Email templates\n│ ├── views\u002F # Rails views (minimal with Inertia)\n│ └── frontend\u002F # Inertia.js React components\n│ ├── components\u002F # Reusable UI components\n│ ├── layouts\u002F # Page layouts\n│ ├── pages\u002F # Inertia page components\n│ └── lib\u002F # Frontend utilities\n├── config\u002F\n│ ├── routes.rb # Route definitions\n│ ├── database.yml # Database configuration\n│ └── initializers\u002F # App initializers\n├── db\u002F\n│ ├── migrate\u002F # Database migrations\n│ ├── schema.rb # Current schema\n│ └── seeds.rb # Seed data\n├── lib\u002F\n│ └── tasks\u002F # Custom Rake tasks\n└── public\u002F # Static assets\n\\`\\`\\`\n\n### Request Lifecycle\n\n1. Request hits Rails router (`config\u002Froutes.rb`)\n2. Middleware stack processes request (authentication, sessions, etc.)\n3. Controller action executes\n4. Models interact with PostgreSQL via ActiveRecord\n5. Inertia renders React component with props\n6. Response sent to browser\n\n### Data Flow\n\n\\`\\`\\`\nUser Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL\n↓\nReact Props ← Inertia Response ←\n\\`\\`\\`\n\n### Key Components\n\n**Authentication**\n\n- Devise\u002FRodauth for user authentication\n- Session-based auth with encrypted cookies\n- `authenticate_user!` before_action for protected routes\n\n**Inertia.js Integration (`app\u002Ffrontend\u002F`)**\n\n- React components receive props from Rails controllers\n- `inertia_render` in controllers passes data to frontend\n- Shared data via `inertia_share` for layout props\n\n**Background Jobs (`app\u002Fjobs\u002F`)**\n\n- Solid Queue for job processing\n- Jobs stored in PostgreSQL (no Redis required)\n- Dashboard at `\u002Fjobs` for monitoring\n\n**Database (`app\u002Fmodels\u002F`)**\n\n- ActiveRecord models with associations\n- Query objects for complex queries\n- Concerns for shared model behavior\n\n### Database Schema\n\n\\`\\`\\`\nusers\n├── id (bigint, PK)\n├── email (string, unique, not null)\n├── encrypted_password (string)\n├── name (string)\n├── created_at (datetime)\n└── updated_at (datetime)\n\nposts\n├── id (bigint, PK)\n├── title (string, not null)\n├── content (text)\n├── published (boolean, default: false)\n├── user_id (bigint, FK → users)\n├── created_at (datetime)\n└── updated_at (datetime)\n\nsolid_queue_jobs (background jobs)\n├── id (bigint, PK)\n├── queue_name (string)\n├── class_name (string)\n├── arguments (json)\n├── scheduled_at (datetime)\n└── ...\n\\`\\`\\`\n```\n\n### 6. Environment Variables\n\nComplete reference for all env vars:\n\n```markdown\n## Environment Variables\n\n### Required\n\n| Variable           | Description                       | How to Get                             |\n| ------------------ | --------------------------------- | -------------------------------------- |\n| `DATABASE_URL`     | PostgreSQL connection string      | Your database provider                 |\n| `SECRET_KEY_BASE`  | Rails secret for sessions\u002Fcookies | Run `bin\u002Frails secret`                 |\n| `RAILS_MASTER_KEY` | Decrypts credentials file         | Check `config\u002Fmaster.key` (not in git) |\n\n### Optional\n\n| Variable            | Description                                       | Default                      |\n| ------------------- | ------------------------------------------------- | ---------------------------- |\n| `REDIS_URL`         | Redis connection string (for caching\u002FActionCable) | -                            |\n| `RAILS_LOG_LEVEL`   | Logging verbosity                                 | `debug` (dev), `info` (prod) |\n| `RAILS_MAX_THREADS` | Puma thread count                                 | `5`                          |\n| `WEB_CONCURRENCY`   | Puma worker count                                 | `2`                          |\n| `SMTP_ADDRESS`      | Mail server hostname                              | -                            |\n| `SMTP_PORT`         | Mail server port                                  | `587`                        |\n\n### Rails Credentials\n\nSensitive values should be stored in Rails encrypted credentials:\n\n\\`\\`\\`bash\n\n# Edit credentials (opens in $EDITOR)\n\nbin\u002Frails credentials:edit\n\n# Or for environment-specific credentials\n\nRAILS_ENV=production bin\u002Frails credentials:edit\n\\`\\`\\`\n\nCredentials file structure:\n\\`\\`\\`yaml\nsecret_key_base: xxx\nstripe:\npublic_key: pk_xxx\nsecret_key: sk_xxx\ngoogle:\nclient_id: xxx\nclient_secret: xxx\n\\`\\`\\`\n\nAccess in code: `Rails.application.credentials.stripe[:secret_key]`\n\n### Environment-Specific\n\n**Development**\n\\`\\`\\`\nDATABASE_URL=postgresql:\u002F\u002Flocalhost\u002Fmyapp_development\nREDIS_URL=redis:\u002F\u002Flocalhost:6379\u002F0\n\\`\\`\\`\n\n**Production**\n\\`\\`\\`\nDATABASE_URL=\u003Cproduction-connection-string>\nRAILS_ENV=production\nRAILS_SERVE_STATIC_FILES=true\n\\`\\`\\`\n```\n\n### 7. Available Scripts\n\n```markdown\n## Available Scripts\n\n| Command                       | Description                                         |\n| ----------------------------- | --------------------------------------------------- |\n| `bin\u002Fdev`                     | Start development server (Rails + Vite via Foreman) |\n| `bin\u002Frails server`            | Start Rails server only                             |\n| `bin\u002Fvite dev`                | Start Vite dev server only                          |\n| `bin\u002Frails console`           | Open Rails console (IRB with app loaded)            |\n| `bin\u002Frails db:migrate`        | Run pending database migrations                     |\n| `bin\u002Frails db:rollback`       | Rollback last migration                             |\n| `bin\u002Frails db:seed`           | Run database seeds                                  |\n| `bin\u002Frails db:reset`          | Drop, create, migrate, and seed database            |\n| `bin\u002Frails routes`            | List all routes                                     |\n| `bin\u002Frails test`              | Run test suite (Minitest)                           |\n| `bundle exec rspec`           | Run test suite (RSpec, if used)                     |\n| `bin\u002Frails assets:precompile` | Compile assets for production                       |\n| `bin\u002Frubocop`                 | Run Ruby linter                                     |\n| `yarn lint`                   | Run JavaScript\u002FTypeScript linter                    |\n```\n\n### 8. Testing\n\n```markdown\n## Testing\n\n### Running Tests\n\n\\`\\`\\`bash\n\n# Run all tests (Minitest)\n\nbin\u002Frails test\n\n# Run all tests (RSpec, if used)\n\nbundle exec rspec\n\n# Run specific test file\n\nbin\u002Frails test test\u002Fmodels\u002Fuser_test.rb\nbundle exec rspec spec\u002Fmodels\u002Fuser_spec.rb\n\n# Run tests matching a pattern\n\nbin\u002Frails test -n \u002Fcreates_user\u002F\nbundle exec rspec -e \"creates user\"\n\n# Run system tests (browser tests)\n\nbin\u002Frails test:system\n\n# Run with coverage (SimpleCov)\n\nCOVERAGE=true bin\u002Frails test\n\\`\\`\\`\n\n### Test Structure\n\n\\`\\`\\`\ntest\u002F # Minitest structure\n├── controllers\u002F # Controller tests\n├── models\u002F # Model unit tests\n├── integration\u002F # Integration tests\n├── system\u002F # System\u002Fbrowser tests\n├── fixtures\u002F # Test data\n└── test_helper.rb # Test configuration\n\nspec\u002F # RSpec structure (if used)\n├── models\u002F\n├── requests\u002F\n├── system\u002F\n├── factories\u002F # FactoryBot factories\n├── support\u002F\n└── rails_helper.rb\n\\`\\`\\`\n\n### Writing Tests\n\n**Minitest example:**\n\\`\\`\\`ruby\nrequire \"test_helper\"\n\nclass UserTest \u003C ActiveSupport::TestCase\ntest \"creates user with valid attributes\" do\nuser = User.new(email: \"test@example.com\", name: \"Test User\")\nassert user.valid?\nend\n\ntest \"requires email\" do\nuser = User.new(name: \"Test User\")\nassert_not user.valid?\nassert_includes user.errors[:email], \"can't be blank\"\nend\nend\n\\`\\`\\`\n\n**RSpec example:**\n\\`\\`\\`ruby\nrequire \"rails_helper\"\n\nRSpec.describe User, type: :model do\ndescribe \"validations\" do\nit \"is valid with valid attributes\" do\nuser = build(:user)\nexpect(user).to be_valid\nend\n\n    it \"requires an email\" do\n      user = build(:user, email: nil)\n      expect(user).not_to be_valid\n      expect(user.errors[:email]).to include(\"can't be blank\")\n    end\n\nend\nend\n\\`\\`\\`\n\n### Frontend Testing\n\nFor Inertia\u002FReact components:\n\n\\`\\`\\`bash\nyarn test\n\\`\\`\\`\n\n\\`\\`\\`typescript\nimport { render, screen } from '@testing-library\u002Freact'\nimport { Dashboard } from '.\u002FDashboard'\n\ndescribe('Dashboard', () => {\nit('renders user name', () => {\nrender(\u003CDashboard user={{ name: 'Josh' }} \u002F>)\nexpect(screen.getByText('Josh')).toBeInTheDocument()\n})\n})\n\\`\\`\\`\n```\n\n### 9. Deployment\n\nTailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal\u002F, etc.):\n\n```markdown\n## Deployment\n\n### Kamal (Recommended for Rails)\n\nIf using Kamal for deployment:\n\n\\`\\`\\`bash\n\n# Setup Kamal (first time)\n\nkamal setup\n\n# Deploy\n\nkamal deploy\n\n# Rollback to previous version\n\nkamal rollback\n\n# View logs\n\nkamal app logs\n\n# Run console on production\n\nkamal app exec --interactive 'bin\u002Frails console'\n\\`\\`\\`\n\nConfiguration lives in `config\u002Fdeploy.yml`.\n\n### Docker\n\nBuild and run:\n\n\\`\\`\\`bash\n\n# Build image\n\ndocker build -t myapp .\n\n# Run with environment variables\n\ndocker run -p 3000:3000 \\\n -e DATABASE_URL=postgresql:\u002F\u002F... \\\n -e SECRET_KEY_BASE=... \\\n -e RAILS_ENV=production \\\n myapp\n\\`\\`\\`\n\n### Heroku\n\n\\`\\`\\`bash\n\n# Create app\n\nheroku create myapp\n\n# Add PostgreSQL\n\nheroku addons:create heroku-postgresql:mini\n\n# Set environment variables\n\nheroku config:set SECRET_KEY_BASE=$(bin\u002Frails secret)\nheroku config:set RAILS_MASTER_KEY=$(cat config\u002Fmaster.key)\n\n# Deploy\n\ngit push heroku main\n\n# Run migrations\n\nheroku run bin\u002Frails db:migrate\n\\`\\`\\`\n\n### Fly.io\n\n\\`\\`\\`bash\n\n# Launch (first time)\n\nfly launch\n\n# Deploy\n\nfly deploy\n\n# Run migrations\n\nfly ssh console -C \"bin\u002Frails db:migrate\"\n\n# Open console\n\nfly ssh console -C \"bin\u002Frails console\"\n\\`\\`\\`\n\n### Render\n\nIf `render.yaml` exists, connect your repo to Render and it will auto-deploy.\n\nManual setup:\n\n1. Create new Web Service\n2. Connect GitHub repository\n3. Set build command: `bundle install && bin\u002Frails assets:precompile`\n4. Set start command: `bin\u002Frails server`\n5. Add environment variables in dashboard\n\n### Manual\u002FVPS Deployment\n\n\\`\\`\\`bash\n\n# On the server:\n\n# Pull latest code\n\ngit pull origin main\n\n# Install dependencies\n\nbundle install --deployment\n\n# Compile assets\n\nRAILS_ENV=production bin\u002Frails assets:precompile\n\n# Run migrations\n\nRAILS_ENV=production bin\u002Frails db:migrate\n\n# Restart application server (e.g., Puma via systemd)\n\nsudo systemctl restart myapp\n\\`\\`\\`\n```\n\n### 10. Troubleshooting\n\n```markdown\n## Troubleshooting\n\n### Database Connection Issues\n\n**Error:** `could not connect to server: Connection refused`\n\n**Solution:**\n\n1. Verify PostgreSQL is running: `pg_isready` or `docker ps`\n2. Check `DATABASE_URL` format: `postgresql:\u002F\u002FUSER:PASSWORD@HOST:PORT\u002FDATABASE`\n3. Ensure database exists: `bin\u002Frails db:create`\n\n### Pending Migrations\n\n**Error:** `Migrations are pending`\n\n**Solution:**\n\\`\\`\\`bash\nbin\u002Frails db:migrate\n\\`\\`\\`\n\n### Asset Compilation Issues\n\n**Error:** `The asset \"application.css\" is not present in the asset pipeline`\n\n**Solution:**\n\\`\\`\\`bash\n\n# Clear and recompile assets\n\nbin\u002Frails assets:clobber\nbin\u002Frails assets:precompile\n\\`\\`\\`\n\n### Bundle Install Failures\n\n**Error:** Native extension build failures\n\n**Solution:**\n\n1. Ensure system dependencies are installed:\n   \\`\\`\\`bash\n\n   # macOS\n\n   brew install postgresql libpq\n\n   # Ubuntu\n\n   sudo apt-get install libpq-dev\n   \\`\\`\\`\n\n2. Try again: `bundle install`\n\n### Credentials Issues\n\n**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`\n\n**Solution:**\nThe master key doesn't match the credentials file. Either:\n\n1. Get the correct `config\u002Fmaster.key` from another team member\n2. Or regenerate credentials: `rm config\u002Fcredentials.yml.enc && bin\u002Frails credentials:edit`\n\n### Vite\u002FInertia Issues\n\n**Error:** `Vite Ruby - Build failed`\n\n**Solution:**\n\\`\\`\\`bash\n\n# Clear Vite cache\n\nrm -rf node_modules\u002F.vite\n\n# Reinstall JS dependencies\n\nrm -rf node_modules && yarn install\n\\`\\`\\`\n\n### Solid Queue Issues\n\n**Error:** Jobs not processing\n\n**Solution:**\nEnsure the queue worker is running:\n\\`\\`\\`bash\nbin\u002Fjobs\n\n# or\n\nbin\u002Frails solid_queue:start\n\\`\\`\\`\n```\n\n### 11. Contributing (Optional)\n\nInclude if open source or team project.\n\n### 12. License (Optional)\n\n---\n\n## Writing Principles\n\n1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.\n\n2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.\n\n3. **Show Example Output** - When helpful, show what the user should expect to see.\n\n4. **Explain the Why** - Don't just say \"run this command,\" explain what it does.\n\n5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.\n\n6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.\n\n7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.\n\n8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.\n\n---\n\n## Output Format\n\nGenerate a complete README.md file with:\n\n- Proper markdown formatting\n- Code blocks with language hints (`bash, `typescript, etc.)\n- Tables where appropriate\n- Clear section hierarchy\n- Linked table of contents for long documents\n\nWrite the README directly to `README.md` in the project root.\n",{"name":5,"risk":28,"source":43,"license":14,"metadata":44,"description":7},"https:\u002F\u002Fgithub.com\u002FShpigford\u002Fskills\u002Ftree\u002Fmain\u002Freadme",{"role":45,"scope":46,"domain":32,"version":47,"triggers":48,"output-format":33},"specialist","implementation","1.0.0","README, documentation, project docs, write readme, create readme","f2ec4b3b9133d34eeaf9b38e4b0a97e8e5705a7f","benchmarks\u002Ffinal\u002Fskills\u002Fasset1__baotoq--readme",0,"https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard","https:\u002F\u002Fgithub.com\u002FJSGforever","2026-08-29 18:27:56",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add JSGforever\u002Fskillguard --skill readme",{"tool":61,"command":62},"bunx","bunx skills add JSGforever\u002Fskillguard --skill readme",{"tool":64,"command":65},"pnpm","pnpm dlx skills add JSGforever\u002Fskillguard --skill readme","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__baotoq--readme\u002FSKILL.md",true,[],[70,101,116,143,164,185],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":74,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":82,"publishedAt":38},"01M71HY2SNXBA9Q00WZDTZQ31Z","skillguard-codex-scanner","Hybrid deterministic+LLM agent-skill security scanner. Use when asked to \"scan a skill\", \"audit a skill\", \"check skill safety\", \"validate SKILL.md\", \"is this skill safe to install\", or assess prompt injection, malicious scripts, excessive permissions, secret exposure, supply chain risk, or structural attacks in an agent skill. Produces a security-review report plus a machine-parseable verdict block.","GPL-3.0","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fsrc\u002Fskillguard\u002Fstatic_scanner\u002Fskillguard-codex-scanner\u002FSKILL.md",[77],{"categoryNo":78,"categoryName":79,"taxonomyType":80,"taxonomyTypeDesc":81},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[83,84,85,86,87,88,89,90,91,92,93,94,34,95,96,97,98,99,100,28],"scanner","skillguard codex scanner","skillguard","codex","chain","skill security","security-review","review report","structural","secret","prompt injection","security scanner","review","malicious","permissions","exposure","audit","scripts",{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":112,"publishedAt":38},"01M71HY0SPKTT3S27BC2HPAC5M","data-exfiltrator","Analyzes data files","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Fsmoke-one-skill\u002Fasset1__cisco-ai-defense--data-exfiltrator\u002FSKILL.md",[107],{"categoryNo":108,"categoryName":109,"taxonomyType":110,"taxonomyTypeDesc":111},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[113,114,115],"data","data exfiltrator","files",{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":74,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":38},"01M71HXVS9EMN44BGDW215FZ72","real-time-collaboration-engine","Build real-time collaborative editing with WebSockets, OT\u002FCRDT conflict resolution, and presence awareness. Implements cursor tracking, optimistic updates, and offline sync. Use for collaborative editors, whiteboards, video editing. Activate on \"real-time collaboration\", \"WebSocket sync\", \"multiplayer editing\", \"CRDT\", \"presence awareness\". NOT for simple chat, request-response APIs, or single-user apps.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--real-time-collaboration-engine\u002FSKILL.md",[],[123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142],"time","real time collaboration engine","real time collaboration","collaboration","engine","real time","Video","reliability","video editing","performance","conflict resolution","presence","access","apps","updates","Bash","activate","optimizer","react","streaming",{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":74,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":152,"publishedAt":38},"01M71HXP6CTY4KFN0QVMMN0V7J","react-performance-optimizer","Optimize React apps for 60fps performance. Implements memoization, virtualization, code splitting, bundle optimization. Use for slow renders, large lists, bundle bloat. Activate on \"React performance\", \"slow render\", \"useMemo\", \"bundle size\", \"virtualization\". NOT for backend optimization, non-React frameworks, or premature optimization.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--react-performance-optimizer\u002FSKILL.md",[149],{"categoryNo":150,"categoryName":151,"taxonomyType":80,"taxonomyTypeDesc":81},"01JBSEEDCAT000000000000009","前端开发",[132,153,140,141,154,155,156,157,158,159,123,160,161,136,138,33,139,142,162,163],"react performance optimizer","react performance","performance optimizer","app","nextjs","expert","re","render","2025","router","strategies",{"skillNo":165,"name":166,"nameZh":6,"description":167,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":74,"licenseFileUrl":6,"sourceHtmlUrl":168,"categories":169,"keywords":171,"publishedAt":38},"01M71HXH7QXSQB4QTDZ7SP7YXQ","llm-streaming-response-handler","Build production LLM streaming UIs with Server-Sent Events, real-time token display, cancellation, error recovery. Handles OpenAI\u002FAnthropic\u002FClaude streaming APIs. Use for chatbots, AI assistants, real-time text generation. Activate on \"LLM streaming\", \"SSE\", \"token stream\", \"chat UI\", \"real-time AI\". NOT for batch processing, non-streaming APIs, or WebSocket bidirectional chat.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--llm-streaming-response-handler\u002FSKILL.md",[170],{"categoryNo":150,"categoryName":151,"taxonomyType":80,"taxonomyTypeDesc":81},[172,142,173,174,175,176,132,123,177,178,179,138,139,140,180,141,181,182,183,184],"llm streaming response handler","handler","error","processing","retry","chat ui","error recovery","critical","batch","display","text","server","read",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":74,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":198,"publishedAt":38},"01M71HXCB0E1YRKYW1Y8T0Y106","github-actions-pipeline-builder","Build production CI\u002FCD pipelines with GitHub Actions. Implements matrix builds, caching, deployments, testing, security scanning. Use for automated testing, deployments, release workflows. Activate on \"GitHub Actions\", \"CI\u002FCD\", \"workflow\", \"deployment pipeline\", \"automated testing\". NOT for Jenkins\u002FCircleCI, manual deployments, or non-GitHub repositories.","https:\u002F\u002Fgithub.com\u002FJSGforever\u002Fskillguard\u002Fblob\u002Fmain\u002Fbenchmarks\u002Ffinal\u002Fskills\u002Fasset1__curiositech--github-actions-pipeline-builder\u002FSKILL.md",[191,194,197],{"categoryNo":192,"categoryName":193,"taxonomyType":80,"taxonomyTypeDesc":81},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":195,"categoryName":196,"taxonomyType":80,"taxonomyTypeDesc":81},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":78,"categoryName":79,"taxonomyType":80,"taxonomyTypeDesc":81},[199,200,201,202,203,204,205,130,158,206,207,208,139,163,209,184,210,19,211,212],"github actions pipeline builder","actions","github actions","pipeline builder","github","builder","pipeline","testing","ci","workflows","run","release","edit","git"]