mirror of https://github.com/bitsocialnet/5chan.git synced 2026-08-03 07:41:04 +02:00

Files

T

Tommaso Casaburi 21bbc5f07c fix(ai skills): correct stale branch names, rg flags, and commit scope rules

Fixes deslop diffing against nonexistent main, an invalid rg --type tsx flag
in fix-merge-conflicts, a Codex-specific phrase leaking into the Claude/Cursor
inspect-elements description, and aligns commit-format with the required-scope
convention the commit skill and git history already use. Rewrites the readme
skill from 764 lines of Rails-specific guidance to a lean version matching
this Vite/Capacitor/Electron repo.

2026-07-03 13:58:34 +07:00

4.3 KiB

Raw Blame History

name, description

name	description
readme	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. Produces thorough, verified documentation covering local setup, architecture, and distribution.

README Generator

You are an expert technical writer. Write (or update) a README.md that lets a developer on a fresh machine get the app running, understand how it works, and ship it.

The Three Purposes of a README

Local Development - Help any developer get the app running locally in minutes
Understanding the System - Explain how the app is put together and why
Distribution - Cover how the project is built, released, and deployed

Before Writing

If a README.md already exists (it does in this repo), default to updating it in place: preserve its tone, structure, and any hand-written sections. Only restructure wholesale if the user asks for a rewrite.

Step 1: Explore the codebase — never document from memory

Every claim in the README must be verifiable in the repo. Check:

Manifest and scripts: package.json (name, scripts, engines, packageManager), lockfile, .nvmrc
Entry points and build: index.html, vite.config.js, src/ layout, tsconfig.json
Platform targets: capacitor.config.ts + android/ (mobile), electron/ + forge.config.js (desktop), vercel.json (web hosting), fastlane/ (store releases)
CI/CD: .github/workflows/
Repo docs that already answer questions: AGENTS.md, DESIGN.md, PRODUCT.md, CHANGELOG.md, docs/
Helper scripts: scripts/ — document the ones a contributor actually needs

For this repo specifically: it is a Yarn 4 (Corepack) + Vite + React 19 SPA that also ships as an Android app (Capacitor) and desktop app (Electron Forge). Package-manager commands in the README must use yarn, never npm.

Step 2: Ask only if critical

If something can be discovered from the repo, discover it. Ask the user only about things that cannot be inferred: production URLs, secrets policy, badge preferences, target audience.

README Structure

Include the sections that apply; skip ones that don't. Suggested order:

Title + one-paragraph overview — what it is, who it's for, links to the live app/stores
Key features — short bullet list, user-facing
Tech stack — table of major dependencies with one-line roles
Prerequisites — runtime versions (from engines/.nvmrc), corepack enable, platform SDKs only for the platform sections that need them
Getting started — clone, corepack yarn install, yarn start, expected dev URL; every command copy-pasteable and tested
Architecture overview — directory map with one-line descriptions, data flow, where state lives, how the P2P/backendless parts work (if applicable)
Configuration — env vars/flags as a table (name, required?, default, purpose)
Available scripts — table of the package.json scripts a contributor will actually use
Testing — how to run unit/e2e tests, what CI runs
Building and releasing — per-platform build commands (web, Android, Electron), release process pointers
Troubleshooting — only real, observed failure modes with fixes; don't invent generic ones
Contributing / License — link AGENTS.md/docs rather than duplicating policy

Writing Principles

Verify every command — run it or confirm it exists in package.json before documenting it
Copy-pasteable code blocks with language hints; show expected output where it helps
Explain the why, not just the what
Assume a fresh machine for setup sections
Tables for reference material — env vars, scripts, options
Match the project's package manager — yarn here; never write npm install for a Yarn repo
Table of contents for READMEs over ~200 lines
Don't duplicate other repo docs — link to AGENTS.md, DESIGN.md, PRODUCT.md, playbooks instead of restating them; duplicated policy drifts

Output

Write directly to README.md in the project root. After public-facing English content changes in this repo, run yarn llms:generate and commit any resulting public/llms*.txt changes (see AGENTS.md Task Router).

4.3 KiB Raw Blame History