---
name: readme-i18n-greenfield
description: 建立、重寫或改善中文 repository README.md，尤其是 Greenfield repo bootstrap、OpenCode 自動 scaffold 後的 README、README 很像流水帳 evidence、或需要中英雙語/多語 README 與語言切換器時必須使用。預設以繁體中文撰寫 README.md，整合 create-readme 的專業 README 結構與 readme-i18n 的 Markdown/i18n preservation 規則，避免硬寫不存在的 API、Docker、DB 或 port。
---

# README 雙語 Greenfield

這個 skill 用於產生專業、可維護、中文優先的 repository README。它整合兩個來源 skill 的做法：

- `create-readme`：專業 README 結構、精簡、GitHub Flavored Markdown、不要濫用 emoji、不要塞 `LICENSE` / `CONTRIBUTING` / `CHANGELOG` 這類應獨立成檔的段落。
- `readme-i18n`：README 本地化、語言切換器、保留 Markdown 結構、命令、路徑、環境變數、URL、badge、code fences 與 anchors。

來源改寫摘要在 `references/source-create-readme.md` 與 `references/source-readme-i18n.md`。Markdown 保留規則在 `references/preservation-checklist.md`，語言切換器規則在 `references/language-selector-reference.md`。

## 使用時機

使用這個 skill 處理：

1. 新 Greenfield repo bootstrap 完成後產生中文 `README.md`。
2. 現有 `README.md` 很粗糙、像工具 evidence、缺少 setup / usage / verification / project structure 時重寫。
3. 需要建立中文 README，或需要同步建立英文 sibling，例如 `README.en.md`。
4. 需要加入或更新 README 語言切換器。
5. 需要翻譯 README，但不能破壞 code block、commands、links、anchors、badge URLs。

## 預設語言策略

- 預設主要檔案是繁體中文 `README.md`。
- 只有使用者明確要求英文或多語，才建立英文 sibling，例如 `README.en.md`。
- 如果 repo 已經使用 `README.md` 作英文、`README.zh.md` 作中文，保留既有命名慣例，不要強制改名。
- 如果使用者說「都用中文」、「全部中文」或同義需求，只產生/更新中文 `README.md`，不要新增英文版本。

## 核心原則

README 是給下一位開發者、reviewer 或使用者快速理解專案，不是 bootstrap log。

應該做到：

- 先檢查 repo 內容再寫，不要只根據 repo name 或 PRD 猜。
- 只描述可從檔案、指令、package metadata、skill metadata 或使用者已確認資訊支持的事。
- 不要硬寫不存在的 `/api`、`/api/health`、Docker、PostgreSQL、port、cloud、database、auth、payment、queue、worker。
- 如果某資訊未知，使用「待補」或省略該段，不要假裝存在。
- 使用 GitHub Flavored Markdown，簡潔、專業、可掃讀。
- 不濫用 emoji；除非 repo 已有明確品牌風格。
- 不包含 `License`、`Contributing`、`Changelog` 段落，除非 repo 沒有獨立檔且使用者要求。
- 生成多語 README 時，所有語言版本章節順序必須一致。

## `## 使用的 Skills` 保留規則

更新既有 repo README 時，不要把既有 `## 使用的 Skills` 整段覆蓋成只剩本輪使用的 README skill。必須先判斷 repo 是否真的仍使用過去的 skills：

- 先讀既有 `README*`、`AGENTS.md`、`.opencode/skills/**/SKILL.md`、`.opencode/opencode.json` / `opencode.json`、docs、scripts/config 中是否有 skill 名稱、`skill(...)`、bootstrap metadata、handoff 記錄或明確用途。
- 有 repo evidence 的舊 skill 必須保留，並補齊用途與套用範圍。
- 沒有 repo evidence、只有舊 README 表格殘留、或無法說明用途/套用範圍的舊 skill 才移除。
- Brownfield 本輪沒有經 project-flow 新選 bootstrap skills，不代表 repo 沒有使用過去的 skills；不可因此刪除已驗證的既有 skills。
- 本輪實際用於 README handoff 的 `readme-i18n-greenfield` 可以加入或更新，但應與已驗證保留的既有 skills 並存。

建議表格欄位：`Skill`、`用途`、`套用範圍`。每列都要能對應 repo evidence；不要只列 skill 名稱。

## 寫 README 前的檢查

至少檢查這些檔案或資料夾，存在才引用：

- package / runtime：`package.json`、`pnpm-lock.yaml`、`package-lock.json`、`yarn.lock`、`bun.lockb`、`pyproject.toml`、`requirements.txt`、`uv.lock`、`go.mod`、`Cargo.toml`
- app structure：`src/`、`app/`、`backend/`、`frontend/`、`tests/`、`docs/`
- config：`vite.config.*`、`next.config.*`、`tsconfig*.json`、`Dockerfile`、`docker-compose*.yml`、`.env.example`
- scripts：`package.json scripts`、Makefile targets、documented shell scripts
- existing docs：既有 `README*`、`docs/*`
- skills evidence：既有 `## 使用的 Skills`、`AGENTS.md`、`.opencode/skills/**/SKILL.md`、`opencode.json`、docs/scripts/config 中的 skill references

## 中文 README.md 推薦結構

依專案內容取捨，不要無腦塞滿。以下是中文優先模板：

````md
# <專案名稱>

<!-- README-I18N:START -->

**中文** | [English](./README.en.md)

<!-- README-I18N:END -->

用一到兩句話具體說明這個 repo 包含什麼、服務誰、目前狀態是什麼。

## 專案概述

說明專案用途、目前完成範圍、重要邊界與非目標。

## 功能

- 實際存在或已 scaffold 的能力。
- 另一個有具體描述的能力。

## 技術棧

- 從檔案推斷出的 runtime / framework。
- 從 lockfile 或 scripts 推斷出的 package manager / build tool。

## 專案結構

```text
.
├── src/
└── ...
```

## 開始使用

### 前置需求

- 已知的 Node.js / Python / Docker 版本；未知時不要亂寫。

### 安裝

```bash
<真實 install command>
```

### 啟動

```bash
<真實 dev/start command>
```

## 驗證

```bash
<真實 test/build/typecheck command>
```

## 環境變數

只記錄 `.env.example`、config 或 source code 實際出現的變數。

## 備註

放重要 implementation note、bootstrap note 或維護提醒。不要把第一屏變成 generated evidence。
````

## Greenfield repo 專用規則

Greenfield bootstrap 產生 README 時，通常資訊有限。請使用「可驗證資訊優先」：

- Project name：使用 repo name 或 package name。
- 專案概述：描述目前 scaffold 產物與用途，不要寫成已完成產品。
- 功能：僅列出 scaffold 已建立、PRD 明確要求且 repo 已落地的能力。
- 技術棧：從檔案推斷，例如 `vite.config.ts`、`FastAPI` app、`pyproject.toml`、`package.json`。
- 專案結構：最多列 10-16 個重要路徑，避開 `node_modules`、`.git`、cache、build output。
- 開始使用：只使用實際存在 scripts 或 skill metadata 給出的命令。
- 驗證：只使用實際已執行或可從 metadata 得到的 verification commands。
- Runtime smoke：如果有 `runtimeSmokeCommand` / `runtimeSmokeHealthUrl`，放在「驗證」或「啟動」段落，命令不可翻譯。
- Repository：可列 ADO remote URL、branch，但不要把 PAT 或 credential 寫入 README。
- Provenance：如需標記 OpenCode bootstrap，放在「備註」最後一小段，不要放在第一屏。

不要產生這些不實內容：

- 「Frontend calls backend through /api」除非 repo 有 proxy/fetch/config 支持。
- 「Backend health endpoint: /api/health」除非 route 存在。
- 「PostgreSQL service: db:5432」除非 compose 或 config 存在。
- 「Docker compose validation」除非有 compose file。
- Host published ports may be dynamically allocated by scaffold scripts; document fixed ports only when scripts or config explicitly fix them.

## 多語 README 規則

建立英文或其他語言版本時：

- `README.md` 與 sibling README 章節順序一致。
- 翻譯 prose，不翻譯 commands、inline code、file paths、URLs、env vars、package names、repo names、badge/image URLs。
- code fences 數量、語言標籤與內容保持一致。
- 相對連結預設保持原目標；只有 README 語言切換器需要指向 sibling README。
- 若標題翻譯會影響 same-file anchor，更新 `(#...)` links。
- 中文使用自然繁體中文；專有名詞如 `OpenCode`、`Greenfield`、`README`、`GitHub Flavored Markdown` 可保留英文。

## 語言切換器

每個 README variant 頂部只保留一個 selector block。

中文主檔：

```md
<!-- README-I18N:START -->

**中文** | [English](./README.en.md)

<!-- README-I18N:END -->
```

英文 sibling：

```md
<!-- README-I18N:START -->

[中文](./README.md) | **English**

<!-- README-I18N:END -->
```

若已有 selector：

- 有 `README-I18N` marker 時，只替換 marker 中間內容。
- 沒有 marker 但頂部已有明顯語言切換器時，就地正規化，不要新增第二個。

## 最終驗證

完成後檢查：

- 中文 `README.md` 存在。
- 如果有多語版本，每個 README 剛好一個 `README-I18N` selector block。
- code fence 數量一致。
- commands、URLs、env vars、file paths 未被翻譯。
- README 沒有硬寫不存在的 API、Docker、DB、port。
- 若有 same-file anchor links，目標都存在。
- README 第一屏不是 generated evidence，而是專案介紹。
- 既有 `## 使用的 Skills` 已完成 reconcile：有 evidence 的舊 skills 被保留，無 evidence 的舊 skills 才被移除，本輪 `readme-i18n-greenfield` 不會覆蓋掉其他仍有效的 skills。

## 輸出要求

當使用者要求建立或改寫 README：

- 直接編輯 repo 內 README 檔案，不只給範例。
- 簡短回報建立/更新的檔案。
- 列出任何刻意保留英文的專有名詞。
- 如果資訊不足導致省略某段，簡短說明，不要腦補。

## OpenCode Greenfield Bootstrap Metadata

```opencode-bootstrap-json
{
  "role": "any",
  "category": "readme-docs",
  "order": 90,
  "packageManager": "none",
  "scaffoldCommand": [],
  "verificationCommands": []
}
```

這段 docs-only metadata 讓 Greenfield bootstrap 可以把 `readme-i18n-greenfield` 當成已指派的 README 規則 skill 載入。它只提供 README 指導，不 scaffold app code、不安裝 dependency、不執行 verification，也不啟動 runtime smoke。

## Bootstrap Boundary

這個 skill 只負責 README 產出與 i18n preservation。Greenfield bootstrap 會透過上方 docs-only metadata 識別它為 README 規則來源。只有在使用者要求 README、文件整理或 Greenfield README 時才使用。