---
name: prep-repo
description: "Use when the user wants to prepare a local project for GitHub or public release. Runs a release-readiness sweep over README structure, bilingual docs, commit hygiene, sensitive-data exposure, broken links, markdown rendering, project layout, tests, CI, Docker, and final cleanup. Fixes issues only inside the target repo and treats secrets/history rewriting as explicit high-risk gates. NOT for publishing without user approval or for private operational runbooks that should not be open-sourced."
version: 2.1.0
status: stable
triggers:
- "/prep-repo"
- "推上 GitHub 前檢查"
- "開源前體檢"
- "prepare repo"
---
# Prep Repo
You are a release-readiness auditor for public GitHub projects. You scan first, separate must-fix blockers from polish, and never let private data, broken docs, or misleading setup instructions slip into a public repo.
Prepare a local project for publishing to GitHub. Run through all checks and fix issues found.
## 不適用
- 不直接 publish、push、改 repo visibility，除非 user 明確要求。
- 不自動重寫 git history；若掃到歷史中的秘密，先停下說明風險與命令。
- 不把 private/internal 專案硬改成 public 文案；先確認目標 visibility。
## 跟工程流程 skill 的關係
- `spec` / `prd-create` / `prd-breakdown` / `goal-engineer` 管「要做什麼、怎麼做、怎麼交給 agent 或 ADO」；本 skill 只管**做完後能不能安全公開/推 GitHub**。
- 遇到 bug 用 `diagnose`，遇到尚未定義的 feature 用 `spec`，遇到已完成但準備 release 的 repo 才用本 skill。
## Checklist
### 1. README
- [ ] `README.md` exists with an **engaging, descriptive title** (not the repo/folder name — e.g. "Pantry Pilot -- Because Life's Too Short to Track Groceries by Hand" instead of "my_pantry_app")
- [ ] `README_zh.md` exists (Traditional Chinese version)
- [ ] `README.md` has `[正體中文](README_zh.md)` link (not 繁體中文、繁體中文版 etc.)
- [ ] `README_zh.md` has `[English](README.md)` link (not English Version etc.)
- [ ] Both language links are **standalone lines** below the badges, not inside blockquotes
- [ ] Both READMEs have: project description, architecture/structure, quick start, and links to docs
- [ ] Badges present below title: at minimum **License** + **primary language version**. Common badges:
- `[](LICENSE)`
- `[](https://www.python.org/)`
- `[](https://www.docker.com/)`
- CI badge if GitHub Actions exists
- [ ] **Security Notice** section exists (what external services are used, how credentials are handled, how to report issues)
### 2. Docs (if any)
- [ ] Chinese docs have an **English summary** block at the top (in a `> **English summary:**` blockquote)
- [ ] All internal links are valid (no broken links)
### 3. Naming Conventions
- [ ] Repository/folder uses consistent naming (snake_case preferred)
- [ ] If user has a prefix convention (e.g. `kc_`), verify all repos follow it
### 4. Git Commit Messages
Follow the convention: `Category: lowercase description`
Common categories:
- `Init:` — initial commit
- `Core:` — core functionality changes
- `Docs:` — documentation only
- `fix:` — bug fixes
- `fix(security):` — security fixes
- `Build:` — build/Docker/CI changes
- `Plugins:` — plugin/skill/extension changes
### 5. Files
- [ ] `.gitignore` exists (at minimum: `.DS_Store`, `*.pyc`, `__pycache__/`)
- [ ] `LICENSE` exists
- [ ] No unnecessary files tracked (`.env`, credentials, `.DS_Store`, `__pycache__`)
### 6. Sensitive Data Scan
用兩層互補、不重疊的方式掃 **working tree 與整條 git history**，不要只靠其中一種：
- **Layer A — `gitleaks`（credential / token 類）**：抓 API keys、bot/gateway tokens、private keys、cloud creds 等有明確格式的秘密，且會逐 commit 掃過整條 history。這類正是手刻 grep 最容易漏的。
- **Layer B — targeted grep（營運情境洩漏類）**：抓 gitleaks 預設規則**不會**flag 的 project-specific PII，例如內網 IP、Telegram user/chat id、含使用者名稱的 SSH 路徑、Tailscale 網域、home directory 路徑。這類沒有通用秘密特徵、gitleaks 預設放行，必須自己補。
兩層都要跑；任一層命中 history 就進入下方的 history-rewrite 高風險 gate。
**Layer A — gitleaks**（若未安裝：`brew install gitleaks`）：
```bash
# 掃整條 git history（所有 commit）
gitleaks git . --no-banner --redact -v
# 掃 working tree（含尚未 commit 的檔案）
gitleaks dir . --no-banner --redact -v
```
- exit code `1` = 有 leak（blocker，必須先處理才能 publish）；`0` = clean。
- 誤報處理：**先由人確認確實是 placeholder / 公開範例**，再把該 finding 的 fingerprint 加進 repo 根目錄的 `.gitleaksignore`。不要用寬鬆 regex 一次 allowlist 一整類，否則等於關掉該類偵測。
- 想更嚴可加自訂規則檔（`gitleaks ... --config .gitleaks.toml`）延伸預設 rule set，但預設 rule set 已涵蓋主流 token 格式，通常不需要。
**Layer B — targeted grep**（gitleaks 不管的營運類）：
```bash
# 掃 working tree
grep -rn --exclude-dir=.git --exclude-dir=vendor --exclude-dir=node_modules --exclude-dir=.venv \
-iE "192\.168\.[0-9]+\.[0-9]+|10\.[0-9]+\.[0-9]+\.[0-9]+|(chat|user).?id.*[0-9]{9}|bot.?token|\.ts\.net|/Users/[a-z]+|/home/[a-z]+" .
# 掃 git history（把已知敏感值填進 pattern；或用 gitleaks git 的結果反查 commit）
git log --all -p | grep -nE "KNOWN_SENSITIVE_VALUES_HERE"
```
> Layer B 的 pattern 是通用範例，依專案調整；命中後人工判斷是真洩漏還是無害（例如文件裡的 `192.168.x.x` 佔位範例不算）。
**History-rewrite gate（高風險，不自動跑）**：任一層在 **git history** 命中真實秘密時：
1. 停下，明確告訴 user 洩漏值、所在 commit 與檔案，說明 rewrite history 會改寫所有後續 commit SHA、需要 force-push、且已 clone 的人仍留有舊值。
2. 經 user 同意後才執行 `git filter-repo --replace-text <file>`（或 BFG）清除，並提醒相關 token 應直接**作廢重簽**，因為它已進過版本庫。
（進階：可把 `gitleaks git --staged` 掛成 pre-commit hook、或把 `gitleaks git .` 放進 CI job，讓之後每次 commit 自動擋秘密；那屬持續防護、不在這份一次性 release sweep 範圍內，可在收尾時建議 user 設置。）
### 7. Co-Authored-By Removal
- [ ] No `Co-Authored-By` lines in any commit messages
```bash
git log --all --format="%B" | grep -i "co-authored"
```
If found, use `git filter-repo --message-callback` to remove.
### 8. Link Validation
- [ ] All internal markdown links point to existing files
- [ ] External URLs are valid (spot check, not exhaustive)
```bash
# Extract and verify internal links
grep -rn '\[.*\](.*\.md\|.*\.py\|.*\.json)' --include="*.md" . | grep -v .git
```
### 9. Markdown Rendering Check
- [ ] No bare `===` or `---` lines outside code blocks (causes heading/hr rendering issues)
- [ ] Nested code blocks use different fence levels (outer ```````` ```````` ````````, inner ```` ``` ````)
- [ ] Report blocks, ASCII art, and formatted text are wrapped in code fences
- [ ] No redundant wrapper patterns in headers — e.g. `（又名「...」）` or `(a.k.a. "...")` should be simplified to just the quoted text
```bash
# Find bare === lines that may cause rendering issues
grep -n "^===" --include="*.md" -r . | grep -v .git
```
### 10. Skill Directory Structure (if applicable)
Each skill follows:
```
skill-name/
├── SKILL.md # Frontmatter (name, description, version) + instructions
└── scripts/ # Executable scripts
└── script.py
```
- [ ] SKILL.md has YAML frontmatter with `name`, `description`, `version`
- [ ] Scripts are in `scripts/` subdirectory
- [ ] No orphan metadata files (`_meta.json` etc.) unless required
### 11. Project Directory Structure
Root directory should only contain entry-point files and config. Documentation and assets go in `docs/`.
```
project/
├── src/ or main code # Source code
├── tests/ # Automated tests
├── docs/ # Design docs, guides, images
│ ├── images/ # Screenshots, architecture diagrams
│ └── DESIGN.md # Design document (not in root)
├── .github/workflows/ # CI pipeline
├── README.md # Entry-point docs stay in root
├── README_zh.md
├── LICENSE
├── .gitignore
├── .gitattributes
├── pyproject.toml / package.json
├── Dockerfile (if applicable)
└── docker-compose.yml (if applicable)
```
- [ ] No documentation files (DESIGN.md, guides, etc.) floating in root — move to `docs/`
- [ ] `docs/images/` exists if project has screenshots or diagrams
- [ ] Root contains only: README*, LICENSE, config files, entry-point scripts
### 12. README Tree vs Actual Directory
The project structure tree in README must match reality.
- [ ] Every file/directory listed in README tree actually exists
- [ ] No existing important directories omitted from tree (e.g. `tests/`, `docs/`, `.github/`)
```bash
# Compare: extract directory names from README tree, check each exists
```
### 13. Tests & CI
- [ ] `tests/` directory exists and contains test files
- [ ] Tests can run successfully (`pytest`, `npm test`, etc.)
- [ ] `.github/workflows/` exists with at least one CI workflow
- [ ] CI workflow runs tests on push/PR to main
### 14. .gitattributes & Language Detection
- [ ] `.gitattributes` exists
- [ ] Lock files marked as generated to prevent language misdetection
Common rules:
```gitattributes
uv.lock linguist-generated=true
package-lock.json linguist-generated=true
pnpm-lock.yaml linguist-generated=true
yarn.lock linguist-generated=true
poetry.lock linguist-generated=true
```
### 15. Docker Build Verification (if applicable)
If project has a `Dockerfile` or `docker-compose.yml`:
- [ ] `docker build` completes without errors
- [ ] `docker compose up` starts all services successfully
- [ ] Services are reachable (health check or basic connectivity test)
- [ ] Common pitfalls checked:
- Files referenced in `COPY` actually exist at that build stage
- Multi-stage builds don't miss required files
- Build args and env vars have sensible defaults
### 16. GitHub Repo Metadata (post-push)
After pushing to GitHub, verify:
- [ ] **Description** is set (the one-line summary shown on repo cards and search results)
- [ ] **Topics** are set (tags like `python`, `modbus`, `mcp` — helps discoverability)
```bash
# Set description
gh repo edit OWNER/REPO --description "one-line summary"
# Set topics
gh repo edit OWNER/REPO --add-topic python --add-topic modbus --add-topic mcp-server
```
- [ ] Language badge is displaying correctly (should reflect primary language, not lock files)
## Execution
Run through each section. For each issue found:
1. Show the issue
2. Fix it
3. Verify the fix
After all checks pass, stage and commit with: `Docs: prep repo for GitHub publish`
For post-push checks (section 16), run after the repo is on GitHub.