# Readme > Generate a README and GitHub repo description from the actual codebase, always in English, Japanese, Simplified Chinese and Hong Kong Traditional Chinese, in the marketing variant or the --variant assessment variant. - Skill: `gufranco/readme` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx get-skill add gufranco/readme` - Raw SKILL.md: https://api.skillmd.com/api/skills/gufranco/readme/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: gufranco (https://skillmd.com/u/gufranco) - Updated: 2026-11-14 - Page: https://skillmd.com/skills/gufranco/readme --- ## Overview Generate a README and GitHub repository description grounded in the actual codebase. Every run writes four files: the English README plus its Japanese, Simplified Chinese and Hong Kong Traditional Chinese translations. Two variants are supported: marketing (default) and assessment (`--variant assessment`). The marketing variant is for a public repository: what the project is, how to install it, how to use it, and where to get help, in that order. The assessment variant reads like an engineering memo: tables for every section and design decisions written as narrative paragraphs. Every claim in both variants is grounded in the actual codebase, and every file the skill writes passes the slop gate in Phase 5. Never invent features. ## When to use - When starting a new project that needs a professional README. - When a project has outgrown its initial README and needs a rewrite. - When preparing a project for public release or portfolio showcase. - When the README is stale and no longer reflects the codebase. - When you want the project to stand out on GitHub. ## When NOT to use - For minor README tweaks like fixing a typo or adding one section. - When the project has no code yet, just a plan. ## Arguments This skill accepts optional arguments after `/readme`: - No arguments: generate a full README and repo description by scanning the entire project. Uses the marketing-grade structure documented in this file. - `--variant `: pick the README structure variant. Default `marketing`. Currently supported variants: | Variant | When to use | Template source | |---------|-------------|-----------------| | `marketing` | Public release, portfolio, open source. Hero, usage example, quick start, badges. Default | The structure documented inline in this file | | `assessment` | Take-home assessments, interview submissions, pre-submission audits, architecture reviews. Technical and explanatory tone. Tables and concrete examples. Design decisions as narrative paragraphs | [`template-assessment.md`](template-assessment.md) in this directory. Also invoked by `/assessment` step 12 | - `--about-only`: generate only the GitHub repo description and topics, skip README. - `--section `: regenerate a specific section (e.g., `--section quick-start`). - `--diff`: update the existing README based on what changed since it was last written. Each translation is updated from the English diff since that translation file's own last commit. - `--languages `: extra translations to write beyond the fixed set, as a comma-separated list of BCP 47 tags such as `es`. The fixed set is always written and never asked about: English, `ja`, `zh-Hans` and `zh-HK`. A tag in the flag that is already in the fixed set changes nothing. When `--variant assessment` is passed, read [`template-assessment.md`](template-assessment.md) for the full structure and rules. The Deep Scan in Phase 1 still runs because the assessment variant also benefits from grounded data, but the structure, tone, and section list come from the assessment template instead of the marketing structure below. ## Steps ### Phase 1: Deep Scan Read the project thoroughly. Run these **in parallel**: 1. **Project identity**: read `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`, or equivalent to get the project name, version, description, dependencies, and scripts. 2. **Infrastructure and config**: read Terraform files, Docker files, CI/CD configs, `docker-compose.yml`, and deployment configs to understand the infrastructure. 3. **Source code structure**: map the directory tree, `ls -R` or glob to understand the project layout, modules, and organization. 4. **Existing README**: read the current [`README.md`](../../README.md) if it exists, to understand what the user already had and what to improve. 5. **Environment and setup**: read `.env.example`, setup scripts, and Makefile targets to document prerequisites and setup steps. 6. **Git context**: run `git remote -v` and `git log --oneline -10` to get the repo URL, recent activity, and contributor count. 7. **Visual assets**: check for logo files like `logo.png`, `logo.svg`, `banner.png`, `.github/assets/`, or `docs/images/`, and existing screenshots or demos. 8. **License and metadata**: read `LICENSE`, `.github/FUNDING.yml`, badges in existing README. 9. **Community health files**: check for `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md`, `CITATION.cff`, `CODEOWNERS`, and `.github/ISSUE_TEMPLATE/`. GitHub scores the same list in its community profile. A public repo missing all of them reads as unmaintained to anyone evaluating it for adoption. 10. **Release and versioning signals**: run `git tag --list --sort=-v:refname | head -5` and `GH_TOKEN=$(gh auth token --user ) gh release list --limit 5`. Read the version field from the manifest. Decide whether the tag history follows semantic versioning, calendar versioning, or no scheme at all. ### Phase 2: Architecture and Identity Analysis From the scan results, build a project profile: - **Type**: library, CLI tool, web app, API service, infrastructure, monorepo, dotfiles, or combination. - **Stack**: languages, frameworks, databases, cloud services, CI/CD tools. - **Scale signals**: multi-region, microservices, event-driven, serverless, multi-tenant, monorepo with N packages, etc. - **Differentiators**: what makes this project stand out? Look for unique combinations, unusual scale, well-solved hard problems, or opinionated design choices. - **Personality**: infer the project's tone from existing docs, comments, and commit messages. Technical and serious? Fun and playful? Opinionated and sharp? Match it. - **Metrics inventory**: count concrete numbers: modules, services, endpoints, tests, config files, CLI commands, supported platforms, dependencies, lines of code by language. These become the quantified summary. ### Phase 3: Generate README Write the English README following the structure and style guide below. Every section must be grounded in what was found in Phase 1. If a section doesn't apply, skip it. The goal is a README a developer can act on within a minute: what the project is, how to install it, how to use it, and where to get help, the four questions [GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) names for a README. ### Phase 3b: Translate Always. Translate the finished English README into `ja`, `zh-Hans` and `zh-HK`, plus any tag passed with `--languages`, following section 7f. Translate from the English file every time, never from another translation. With `--section` or `--diff`, the same sections change in every translation in the same run, so no translation falls behind the English file. ### Phase 4: Generate GitHub About Generate a concise repo description, max 350 characters, and a list of topic tags. See the "GitHub About" section below. ### Phase 5: Present and Apply Before presenting, write the English draft to a scratch file and run the slop gate on it: ```bash python3 ~/.claude/tools/slop-scan.py ``` Exit 0 is required, and the scan runs again on the written file after approval. The detectors read English only, so read each translation against the same shapes in [`standards/anti-slop.md`](../../standards/anti-slop.md) by hand. Then apply the deletion test from that standard to every paragraph of the English file: a paragraph whose removal changes nothing about what the reader does next is cut. 1. Show the full README, and every translation, to the user for review. 2. Show the GitHub About description and topics. 3. Ask if they want changes before writing. 4. **Resolve account** per [`standards/multi-account-cli.md`](../../standards/multi-account-cli.md) before applying GitHub About: map the owner in `git remote get-url origin` to an authenticated account. Every `gh` call carries `GH_TOKEN=$(gh auth token --user )` inline, and the global active account is never switched. 5. After approval: - Write the English README and each `README..md`. - Apply the GitHub About using `GH_TOKEN=$(gh auth token --user ) gh repo edit --description ""` and `GH_TOKEN=$(gh auth token --user ) gh repo edit --add-topic ` commands. ## README Structure Use this structure as a guide. Skip sections that don't apply. Reorder if it makes more sense for the project. ### 1. Hero Section The first thing anyone sees. It must create instant visual identity and communicate what the project does in under 5 seconds. The 5-second test is the explicit acceptance criterion: a developer scrolling fast should know what the project is, that it works, and how to try it without reading a single paragraph. **Light and dark mode logo via ``.** This is the canonical pattern as of late 2023. The older `#gh-dark-mode-only` fragment hack is deprecated. Drizzle, tRPC, Vite, Supabase, and Next.js all use this form. The `` line is the tagline: one line, confident, specific. The badge block below it is the one [`tools/readme-badges.py`](../../tools/readme-badges.py) writes, per the Badges section. ```html
Project Name

What it does, concretely, in one sentence.

[![ci](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/owner/repo/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/owner/repo?style=flat-square&label=release)](https://github.com/owner/repo/releases/latest) [![license](https://img.shields.io/github/license/owner/repo?style=flat-square&label=license)](LICENSE)

Docs | Discord | Twitter | Contributing | Issues

``` The **navigation pill row** under the badges is the pattern Bun, Zod, and Astro use. Zero scroll cost, gives the reader an escape hatch to the deeper docs and the community channels. Skip channels that do not exist for the project. When the project has only one logo, use a single `` and skip the `` wrapper. Never use a placeholder. If no logo exists, omit the image entirely and lead with the bold tagline. After the hero, one plain sentence may state the project's scope in numbers that answer a reader's question, each counted from the source in this run: ```markdown Nine Terraform modules deploy 31 AWS services across six regions, covered by 214 tests. ``` Never a decorative bar of bolded figures separated by dots, never an approximate `30+` or `~30 min` that was not measured, and never a number that only sounds large. A project with no meaningful count skips the sentence. **Demo immediately.** The hero stack ends with one of three demo elements: an animated GIF for visual tools, an asciinema cast for CLI tools, or a 5-line code snippet for libraries. Place this within the first scroll. The "demo first" pattern is now baseline. Hyperfine opens with a GIF. Hono opens with a 4-line code example. Zod opens with a `z.object` schema definition. ### 2. Usage A code block of the most common use, near the top and before the reference sections. [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) requires a Usage section. A CLI shows its common commands with real output. A library shows the import and one call. The block is the feature list's evidence: a reader who sees the call does not need a sentence claiming it is easy. Never a grid of feature squares. An HTML table of titled cells, each selling one feature, is the layout readers now name as a sign of a generated README, alongside emoji headings and ASCII diagrams, in [this Hacker News thread](https://hn.nuxt.dev/item/47528683). Capabilities that need listing go in the section 5 table, one row each, with the command or option that provides them. ### 3. Comparison With Alternatives, Optional Include it only when a reader is likely choosing between this project and a named alternative, and only with facts checked against that alternative's current documentation in this run. Skip any "The Problem" or "The Solution" story. A README that argues why the reader should use it reads as a sales pitch, and readers in the same Hacker News thread said that is where they stop reading. One sentence on what the project does that the alternatives do not, followed by the table, is enough. Use plain `Yes` and `No` text instead of emoji to keep the table accessible to screen readers and consistent in fixed-width contexts: ```markdown | Capability | This Project | Alternative A | Alternative B | |:-----------|:------------:|:-------------:|:-------------:| | Feature 1 | Yes | Yes | No | | Feature 2 | Yes | No | Yes | | Feature 3 | Yes | No | No | ``` For richer tables, replace `Yes` with a short capability descriptor like "Built-in" or "Plugin" or "Partial" so the cell content tells the reader more than a binary. Never rely on color alone to communicate; screen readers ignore color, and red/green is invisible to about 8% of male readers. ### 4. Architecture Mermaid diagrams for projects with enough complexity to warrant them. Use the diagram type that best fits: - **Flowchart**, `graph LR` or `graph TD`: system architecture, data flow between components. - **Sequence diagram**: request/response flows, multi-service interactions. - **C4 Context**: high-level system boundaries for larger projects. ````markdown ```mermaid graph LR A[Client] --> B[API Gateway] B --> C[Service A] B --> D[Service B] C --> E[(Database)] D --> F[(Cache)] ``` ```` **Diagram rules:** - Max 15-20 nodes per diagram. Split into multiple if needed. - Use descriptive labels, not single letters. - Include the data flow direction. - For multi-layer architectures, use `subgraph` to group related components. - Skip this section entirely for simple projects such as CLIs, or small libraries. ### 5. What's Included Categorized feature list. Group by domain, not by file. Use tables with two columns: feature and description. ```markdown ### Category Name | Feature | Description | |:--------|:------------| | Feature A | What it does, concretely | | Feature B | What it does, concretely | ``` Categories come from the project's actual domains: Infrastructure, Security, Data Layer, Monitoring, CLI Commands, Components, etc. ### 6. Demo / Screenshots If the project has visual output such as a web app, CLI with TUI, or desktop app, include the screenshots or recordings the repository already has. If none exist, skip the section and list the missing screenshot as a follow-up. A placeholder image or an empty section is never written. **For CLI tools**, show terminal output in a code block or reference an asciinema recording: ```markdown [![asciicast](https://asciinema.org/a/XXXXX.svg)](https://asciinema.org/a/XXXXX) ``` **For web apps**, use a screenshot with a subtle border: ```html
App screenshot
``` **For GitHub light/dark mode support**, when the project has both variants: ```html App screenshot ``` ### 7. Quick Start The most important section after the hero. It must be prominent, copy-pasteable, and verifiable. A reader should go from zero to running in under 60 seconds. ````markdown ## Quick Start ### Prerequisites | Tool | Version | Install | |:-----|:--------|:--------| | Node.js | >= 20 | [nodejs.org](https://nodejs.org) | | Docker | >= 24 | [docker.com](https://docker.com) | ### Setup ```bash git clone https://github.com/user/repo.git cd repo pnpm install cp .env.example .env pnpm dev ``` ### Verify ```bash curl http://localhost:3000/health ``` Expected output: ```json {"status":"ok"} ``` ```` **Rules:** - Prerequisites in a table, not a bullet list. - Setup commands numbered only if order matters, otherwise a single code block. - Always end with a verification step that proves it works. - Include the expected output of the verification command. ### 7b. For Contributors and Reviewers This subsection lowers the cost of contribution and pre-empts PR review back-and-forth. Include it when the project expects external contributors or when the project has more than one regular contributor. The generated section has five parts. **Reproducing a bug.** Concrete steps from clone to running a minimal reproducer. Reuse the same commands as the Quick Start verification step, plus any seed scripts or fixture files needed. A reviewer who cannot reproduce a reported bug pushes back harder. ````markdown ### Reproducing a bug ```bash git clone https://github.com/user/repo.git cd repo pnpm install cp .env.example .env pnpm db:seed pnpm dev ``` To reproduce reported bugs, follow the steps above and then read the bug report's "Steps to reproduce" section. ```` **Running the tests.** The command that runs the suite, plus one line per suite naming what it covers. A contributor who cannot tell the unit suite from the end-to-end suite runs the slowest one every time, or runs none of them. ```markdown ### Running the tests | Suite | Command | Covers | |:------|:--------|:-------| | Unit | `pnpm test:unit` | Pure functions and domain logic | | Integration | `pnpm test:integration` | Real database and queue, no mocks | | End to end | `pnpm test:e2e` | Full user flows through the HTTP layer | | Lint and format | `pnpm lint` | Style and static analysis gates | ``` Take the suite names and commands from the manifest scripts, the Makefile targets, or the CI job matrix found in Phase 1. Never invent a suite the project does not have. When the project ships a single undifferentiated `test` script, show one row and skip the table header ceremony. **Project conventions.** A table listing concrete conventions detected from the codebase. Surfacing these in the README pre-empts review comments that would otherwise litigate style. ```markdown ### Project conventions | Convention | Source | |------------|--------| | Commit format | [Conventional Commits](https://www.conventionalcommits.org/) | | Branch naming | `feature/`, `bugfix/`, `hotfix/`, `chore/` prefixes | | Lint configuration | [.eslintrc.json](.eslintrc.json) | | Code style | [Prettier](https://prettier.io/) with [prettier.config.mjs](prettier.config.mjs) | | Review process | One human reviewer + CodeRabbit. Expect first response within 1 business day | ``` **Non-obvious decisions.** A short list of 3 to 5 architectural choices the project made deliberately, with one-line rationale each. These are the choices that reviewers would otherwise spend a thread asking about. This subsection cannot be auto-generated reliably; `/readme` prompts the user with: "Name 3 to 5 architectural choices that newcomers ask about. One sentence each." ```markdown ### Non-obvious decisions - Single-writer Postgres without sharding. The data fits and the operational cost of sharding outweighs the latency benefit at this scale. - Synchronous email sending in the request path. The volume is low enough that the queue overhead would dominate. - Branded `UserId` and `OrderId` types. Mixed-up IDs were the source of two production bugs last year. ``` **Issue tracker.** Link to where bugs and feature requests get filed. Deferred items from PR reviews land here. ```markdown ### Issue tracker Bugs and feature requests live in [GitHub Issues](https://github.com/user/repo/issues). Please file before opening a PR. ``` #### How /readme produces this subsection Phase 1 Deep Scan gains these scans: 1. **Detect commit format.** Read recent commits via `git log --oneline -20`. Match against Conventional Commits patterns or any other recognizable format. Record the result for the Project conventions table. 2. **Detect lint and style configs.** Look for `.eslintrc.*`, `prettier.config.*`, `.editorconfig`, `pyproject.toml [tool.ruff]`, `clippy.toml`, `golangci.yml`. Cite the discovered files in the table. 3. **Detect AI review bots.** Look for `.coderabbit.yml`, `.coderabbit.yaml`, `.greptile.yml`, `.cursorrules`, `.cursor/`, `.sourcery.yaml`, `korbit.yml`. List the discovered bots in the conventions table. 4. **Detect issue tracker.** Read repo metadata via `GH_TOKEN=$(gh auth token --user ) gh repo view --json hasIssuesEnabled,url`. If issues are disabled, look for `ISSUE_TEMPLATE/` or `BUG_REPORT.md` template files. If neither, omit the section and leave a comment recommending the user add one. 5. **Detect testing instructions.** Look for `make test`, `pnpm test`, `pytest`, `go test ./...`, or equivalent. Enumerate every test-related script or target, not only the aggregate one, so the Running the tests table can name each suite and what it covers. The reproducing-a-bug instructions reuse the same command. #### Skip conditions If the project is a small CLI tool or a personal dotfiles repo with no expected reviewers, skip the entire "For Contributors and Reviewers" subsection. The signal for skipping: no recent PRs in the repo, or no recent contributors other than the author. ### 7c. GitHub Alerts for Critical Callouts GitHub-flavored Markdown supports five alert types as of late 2023. Use them sparingly for content that genuinely deserves a visual break. Overuse turns the README into a wall of colored boxes and dilutes their effect. ```markdown > [!NOTE] > Useful information that users should know, even when skimming content. > [!TIP] > Helpful advice for doing things better or more easily. > [!IMPORTANT] > Key information users need to know to achieve their goal. > [!WARNING] > Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] > Advises about risks or negative outcomes of certain actions. ``` When to use each: | Alert | Use for | |-------|---------| | `NOTE` | Behavior the reader might miss, like a default value or a non-obvious fallback | | `TIP` | An optimization or shortcut that improves the experience but is not required | | `IMPORTANT` | A required step or constraint that the reader must internalize, like a peer dependency or minimum runtime version | | `WARNING` | A footgun or breaking-change announcement that risks production impact | | `CAUTION` | A destructive operation like database drops, force-pushes, or irreversible config changes | Two alerts in the entire README is healthy. Five is too many. Reserve them for callouts that would otherwise hide inside a paragraph. ### 7d. Sponsors and Backers Sustainable open source funding is now expected for projects that ask for serious adoption. The pattern from pnpm, Biome, tRPC, and TanStack Query is a tiered sponsor section with logos rendered at size proportional to the contribution tier. ```markdown ## Sponsors ### Platinum Sponsor Name ### Gold Sponsor Name ### Silver Sponsor Name ### Backers Backers ``` When to include the section: - The project has a `FUNDING.yml` file in [`.github/`](../../.github). - The project is on Open Collective, GitHub Sponsors, or Polar. - The project has at least one existing sponsor or is actively soliciting one. When to skip: - Personal projects, dotfiles, internal-only repos. - New projects with no sponsors and no immediate plans to ask. Render sponsor logos from a controlled directory like `assets/sponsors/` so the file paths stay stable. Update the section in the same PR that adds the sponsor. ### 7e. AI Companion Files Modern READMEs ship with companion files that help AI agents and assistants navigate the repo. Two conventions are emerging. **`llms.txt` at the site root** for documentation sites. Plain-text Markdown file that summarizes the project for LLM consumption. Required structure: H1 with project name, blockquote summary, optional paragraphs, then H2 sections containing markdown links of the form `[name](url): optional notes`. Original spec at `llmstxt.org`. Adoption is around 10% of sites overall, near-100% among developer-facing SaaS. Cursor, Windsurf, Claude Code, and similar IDE agents fetch `/llms.txt` and `/llms-full.txt` when pointed at a documentation domain. ```markdown # Project Name > One-paragraph summary of what the project does and who it is for. ## Docs - [Quick Start](https://example.com/docs/quick-start): get running in 60 seconds - [API Reference](https://example.com/docs/api): full type signatures and examples ## Examples - [Basic Example](https://example.com/examples/basic): the 5-line demo - [Advanced Example](https://example.com/examples/advanced): full-stack walkthrough ``` Generate `llms.txt` when the project has a documentation site distinct from the GitHub README. Skip when the README is the only documentation. **`AGENTS.md` at the repo root** for in-repo AI agent context. Emerged mid-2025 from a Sourcegraph, OpenAI, Google, and Cursor collaboration, now maintained by the Agentic AI Foundation under the Linux Foundation. Single Markdown file that AI coding agents read for project context: dev commands, conventions, deploy notes, code map. Distinct from `llms.txt`, which is a web standard, and distinct from per-tool files like [`CLAUDE.md`](../../CLAUDE.md) or `.cursor/rules`. Generate `AGENTS.md` when the project will be touched by AI coding agents. Include: project overview, common commands, test conventions, where to find what, and any non-obvious constraints. Match the tone of a senior engineer briefing a new hire on day one. ### 7f. Multilingual Variants English is always the source and keeps the plain README file name. Each translation is a separate file named with its [BCP 47](https://www.rfc-editor.org/info/bcp47) tag, the convention [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) specifies. | Language | Tag | File | Switcher label | Written | |:---------|:----|:-----|:---------------|:--------| | English | `en` | README, unchanged | English | Always | | Japanese | `ja` | `README.ja.md` | 日本語 | Always | | Chinese, Simplified | `zh-Hans` | `README.zh-Hans.md` | 简体中文 | Always | | Chinese, Traditional, Hong Kong | `zh-HK` | `README.zh-HK.md` | 繁體中文 (香港) | Always | | Spanish | `es` | `README.es.md` | Español | With `--languages es` | Any other BCP 47 tag passed to `--languages` follows the same file pattern. **Language switcher.** It sits inside the centered header block, on its own line directly under the bold tagline and above the badges. It lists every language in its own name, in the table's order, separated by a plain ` | `: one space, a pipe, one space. The current language is plain text and every other one is a link. The line is plain Markdown at the normal text size, never wrapped in `` or ``, and a blank line is the only gap above and below it: ```markdown What it does, concretely, in one sentence. English | [日本語](README.ja.md) | [简体中文](README.zh-Hans.md) | [繁體中文 (香港)](README.zh-HK.md) [![ci](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/owner/repo/actions/workflows/ci.yml) ``` The Hong Kong label is copied byte for byte: `繁體中文`, one ASCII space, then `(香港)` in ASCII parentheses. The full-width punctuation rule for Chinese body text does not apply to the switcher, so never write `（香港）`. Never put `
` spacers around the switcher, and never wrap it in `` or ``: it keeps the body text size with a single blank line on each side. Never use ` | ` as the separator, here or in the navigation row. Written with spaces around it, as it always is, each side renders a non-breaking space plus an ordinary one, so the reader sees two spaces on each side of every pipe. GitHub does not negotiate `Accept-Language`, so the reader always picks from this line. **What a translation keeps unchanged.** Code blocks, commands, flags, file paths, identifiers, environment variable names, URLs, badge images and Mermaid node identifiers. Mermaid labels are translated. Headings are translated, as standard-readme requires, and every file keeps the English section order, so the files can be compared section by section. **Per-language rules.** | Tag | Rules | |:----|:------| | `es` | Neutral Spanish, which Microsoft publishes its own [style guide](https://aka.ms/spanish-neutral-styleguide) for, avoiding vocabulary specific to one country. One form of address throughout the file. Opening `¿` and `¡` on every question and exclamation | | `ja` | Polite `です・ます` style throughout, which the [JTF style guide](https://www.ospn.jp/osc2013-spring/pdf/osc2013spring_jtf_style_guide.pdf) says manuals for general readers use. Full-width `、` and `。`, never a period or comma as Japanese punctuation. Half-width letters and digits, full-width symbols, and no space between half-width and full-width characters, all per the same guide | | `zh-Hans` | Mainland vocabulary. A half-width space between Chinese and Latin characters, full-width punctuation, and no space between a Latin character and a full-width punctuation mark, per the [Chinese technical documentation style guide](https://github.com/ruanyf/document-style-guide) | | `zh-HK` | Traditional characters with Hong Kong vocabulary and standard written Chinese, never Cantonese colloquial forms. Translated from English, never converted from the Simplified file: automated conversion produces wrong characters and keeps mainland or Taiwan vocabulary, such as 軟體 where Hong Kong writes 軟件. Microsoft publishes one [Traditional Chinese style guide](https://aka.ms/chinese-traditional-styleguide), written for Taiwan, so Hong Kong vocabulary needs a reviewer who reads it natively | **Keeping translations current.** A translation's last commit is its sync point. In `--diff` mode, `git log -1 --format=%H -- README..md` gives that commit and `git diff -- README.md` gives the English changes to carry over. A section that cannot be translated yet keeps the new English text rather than stale translated text, because an outdated translation misleads where English only slows the reader down. **Before writing any translation, check parity with the English file:** the same number of headings at each level, the same number of code blocks, byte-identical code blocks, and the same link targets. ### 8. Project Structure Directory tree with one-line descriptions. For large projects, wrap in a collapsible section. ```html
Project structure `` ` src/ api/ REST endpoints and middleware services/ Business logic models/ Database models and schemas utils/ Shared utilities tests/ Test suites infra/ Terraform modules `` `
``` For smaller projects with under 10 directories, show the tree directly without collapsing. ### 9. Development Commands Tables grouped by category. Only include if the project has a Makefile, scripts, or task runner. ```markdown ### Development | Command | Description | |:--------|:------------| | `pnpm dev` | Start development server with hot reload | | `pnpm test` | Run test suite with coverage | | `pnpm lint` | Lint and format check | ### Infrastructure | Command | Description | |:--------|:------------| | `make deploy` | Deploy to staging | | `make tf-plan` | Preview infrastructure changes | ``` When the project deploys to a live environment, the Infrastructure group must name the deploy command, the target environment, and the rollback command. A documented deploy path with no documented rollback is a gap; report it as a follow-up rather than leaving the reader to guess. ### 10. Configuration / Environment Variables Tables with variable name, description, required/optional, and default value. ```markdown | Variable | Description | Required | Default | |:---------|:------------|:--------:|:--------| | `DATABASE_URL` | PostgreSQL connection string | Yes |, | | `PORT` | Server port | No | `3000` | | `LOG_LEVEL` | Logging verbosity | No | `info` | ``` ### 11. API Reference For projects with APIs, include endpoint tables. For large APIs, link to external docs and show only the most important endpoints. ```markdown | Method | Endpoint | Description | |:-------|:---------|:------------| | `GET` | `/api/users` | List all users (paginated) | | `POST` | `/api/users` | Create a new user | | `GET` | `/api/users/:id` | Get user by ID | ``` ### 12. FAQ 4-6 questions a newcomer would ask. Use collapsible sections to keep the page clean. ```html
How do I configure X?
Direct, useful answer with a code example if applicable.
Why did you choose Y over Z?
Honest, technical answer explaining the trade-off.
``` ### 12b. Versioning and Releases One short block that answers "can I depend on this?". Libraries, CLIs, SDKs, and anything published to a registry must carry it. Applications and internal services may skip it. ```markdown ## Versioning This project follows [Semantic Versioning](https://semver.org/). Every release is tagged. See [releases](https://github.com/user/repo/releases) for the changelog and upgrade notes. ``` Rules: - Name the scheme and link its spec. Semantic versioning, calendar versioning, and an explicit "no stability guarantee before 1.0" statement are all acceptable answers. Silence is not. - Link the releases page or the tag list. Never inline a changelog; the "What NOT to Include" rule against changelogs in the README still holds. - When the manifest version is `0.x`, say what that means for breaking changes. A `0.x` library that breaks on minor releases must say so where a reader will see it before installing. - Name the supported range when the project maintains more than one line, for example security fixes on the previous major. - Skip the section when Phase 1 found no tags and no releases. A versioning promise with nothing published behind it is a claim the repo cannot back. ### 12c. Maintainers, Support, and Community Health Three questions this block answers: who owns this, where do I ask, and how do I contribute. Include it for any public repo. Skip it for personal dotfiles and internal-only repos. ```markdown ## Support | Need | Where | |:-----|:------| | Bug report | [GitHub Issues](https://github.com/user/repo/issues) | | Question | [GitHub Discussions](https://github.com/user/repo/discussions) | | Security report | [Security policy](SECURITY.md) | | Contributing | [Contribution guide](CONTRIBUTING.md) | ``` Rules: - Link only the community health files Phase 1 actually found. A link to a file that does not exist is a broken link, which anti-pattern 4 already bans. - Never inline the content of those files. A contribution guide pasted into the README is the boilerplate wall this skill rejects; the link is the whole deliverable. - Name a maintainer or an owning team when a reader can reach one. Pull the name from `CODEOWNERS` when present. Skip it when the sole maintainer is the repo owner, since the GitHub header already shows that. - When the repo is public, takes external contributions, and Phase 1 found none of these files, omit the section and report the gap as a follow-up rather than generating dead links. - A security reporting path is the one entry that must not be silently dropped for a public repo handling credentials, network input, or user data. When `SECURITY.md` is absent there, say so in the follow-up list. ### 13. License Short and simple. One line with the license name and a link to the full text. ```markdown ## License [MIT](LICENSE) ``` ## Style Guide ### Voice and Tone - **Direct.** State what the project does. No hedging such as `might` or `could potentially`. - **Plain.** Assume the reader is a developer deciding whether to use the project. Every sentence passes the three tests in [`standards/anti-slop.md`](../../standards/anti-slop.md): it could not appear unchanged in another project's README, deleting it would change what the reader does, and the content chose its structure. - **Show, don't tell.** Instead of "easy to set up", show a 3-line setup. Instead of "fast", show a benchmark with its machine and command. Instead of "flexible", show the configuration options. - **State a decision with its reason.** "Uses SQLite because the data fits on one disk" tells the reader something; "carefully designed" does not. - **No self-validation.** Words like `validated`, `confirmed`, `production-grade`, `battle-tested` or `robust` assert quality instead of showing it, and readers read them as generated text. A test count, a coverage figure or a user list shows the same thing. - **No emoji in headings or bullets, no em dashes, no ASCII diagrams.** Diagrams are Mermaid. ### Visual Hierarchy The README should be scannable in 10 seconds. A developer scrolling fast should understand what the project does without reading a single paragraph. 1. **Hero**: the name, a one-line description, and the badges. 2. **Usage**: the most common call or command, with real output. 3. **Quick Start**: install, run, and verify. 4. **Architecture diagram**, when the system has enough parts to need one. 5. **Everything else** is reference material below the fold. ### Formatting Rules - **Centered hero section** using `
`. This is the only centered section. - **Markdown tables for data** such as commands, env vars, endpoints, or prerequisites. - **Mermaid diagrams** for architecture. Keep them readable, max 20 nodes. - **Collapsible sections**, `
` for verbose content: project structure, FAQ, extended config. - **Code blocks** for every command. Always include the language identifier. - **Horizontal rules**, `---` to separate the hero from the content. Use sparingly elsewhere. - **Consistent alignment**: use `:--------` for left-align, `:--------:` for center-align in tables. Align columns purposefully: names left, statuses center, descriptions left. ### Badges Every repository carries the same badge block, computed from its files by [`tools/readme-badges.py`](../../tools/readme-badges.py), never written by hand. The block sits in the centered header, after the tagline and the language switcher, one badge per line, with a blank line above and below it, and every `README*.md` translation carries the identical block. ```bash python3 ~/.claude/tools/readme-badges.py --visibility public --release yes --write python3 ~/.claude/tools/readme-badges.py --visibility public --release yes --check ``` Read `--visibility` from `gh repo view --json visibility` and `--release` from whether `gh release list --limit 1` prints a release. `--check` exits 1 …(truncated)