lggarrison/agent-skills

儲存庫設定

一個新的儲存庫每次都需要的基礎：一份授權、一個回報安全問題的方式、一個 README、讓 PR 和 Issue 有用的範本，以及執行與貢獻者在本地端相同檢查的 CI。這個技能是該基礎的檢查清單，也是一種逐步完成的方式。

先確認儲存庫規則

在添加任何內容之前，先讀取儲存庫已有的檔案：AGENTS.md / CLAUDE.md、CONTRIBUTING.md、現有的 .github/ 檔案、套件清單及其腳本，以及任何 CI 設定。在它們設定了慣例（預設分支、授權、工具、檔案位置）的地方，遵循這些慣例。切勿覆蓋現有檔案以符合此處的範本。應擴展現有檔案，或保留原狀並指出差距。

工作流程

1. 確定要求

• 引導（Bootstrap）： 一個新的或幾乎為空的儲存庫。執行整個檢查清單。
• 填補空缺（Fill gaps）： 現有儲存庫缺少部分內容。僅添加缺少的部分。
• 稽核（Audit）： 回報缺少或薄弱的部分，不做任何更改。

2. 盤點

列出哪些檢查清單檔案存在，並讀取清單（package.json、pyproject.toml、go.mod、Cargo.toml 等）以了解語言、腳本以及專案是否已發布。使用 git remote show origin 或 gh repo view --json defaultBranchRef 找到預設分支。不要詢問你可以透過這種方式了解的任何資訊。

3. 詢問需要判斷的問題

這些是用戶的決定。一次性、簡短地詢問，並在有證據支持時提出建議：

• **授權（License），**以及版權持有者的名稱。
• 安全聯絡人（Security contact）： GitHub 私有漏洞回報、電子郵件地址，或兩者。
• **行為準則聯絡人（Code of conduct contact），**如果要添加的話。
• **PR 基礎分支（PR base branch），**如果不是預設分支。
• 已發布或未發布（Published or not）： 發布到套件註冊表，或作為發布工件。
• CI 矩陣（CI matrix）： 要支援的作業系統和執行時期版本。

4. 撰寫檔案

從頭到尾執行檢查清單，並跳過不適用的部分。

• **獲取規範文本；不要憑記憶回想。**使用 gh api licenses/<spdx-id> --jq .body（例如 mit 或 apache-2.0）取得授權文本，然後填入年份和持有人。從其官方來源（例如 Contributor Covenant）取得行為準則。
• **調整範本。**從 templates/ 開始。替換每個 <placeholder>，並將指令更改為此儲存庫中存在的指令。列出儲存庫不存在的腳本的範本比沒有範本更糟。
• **一份檢查清單。**PR 範本檢查清單、CONTRIBUTING.md、pre-commit hook 和 CI 都應指定相同的指令。當一個更改時，也更改其他。
• **在更改設定前先詢問。**分支保護、規則集和私有漏洞回報是儲存庫設定，而非檔案。提出它們並僅在用戶同意時套用。

5. 檢查

• 在範本、hook 或 CI 工作中命名的每個指令都能在本地端執行並通過。
• 任何檔案中都沒有遺留 <placeholder>。
• Issue 表單和工作流程是有效的 YAML。Issue 表單僅出現在預設分支上，因此在合併後在那裡檢查它們。
• 連結可以解析，包括安全政策 URL。
• 儲存庫自己的格式和 lint 檢查在新的檔案上通過。

6. 報告

說明你新增了什麼、你保留了什麼以及原因、你提出的儲存庫設定，以及任何仍然開放的判斷問題。

檢查清單

R 表示必要，rec 表示建議，opt 表示可選。

工具

• R git，以及語言執行時期和套件管理器。
• rec 一個執行時期版本管理器（nvm、fnm、pyenv 等），與釘選的版本檔案相符。
• rec gh，已使用 gh auth login 進行驗證，用於維護者。

法律與社群

• R LICENSE。
• R SECURITY.md：支援的版本、如何私下回報，以及回報者在回報後可以期待什麼。
• rec CONTRIBUTING.md：設定、要執行的檢查、分支和提交慣例，以及 PR 如何被審查。
• rec CODE_OF_CONDUCT.md，附有真實的執行聯絡人。
• rec CHANGELOG.md，採用 Keep a Changelog 格式。

文件

• R README.md：它是什麼、如何安裝、一個最小使用範例，以及指向 CONTRIBUTING.md、SECURITY.md 和授權的連結。
• opt AGENTS.md：編寫代理的供應商中立入口點。提供要執行的指令和要遵循的規則，並連結到其他文件，而不是重複它們。
• opt RELEASING.md，用於已發布的專案。請參閱發布。

編輯器與 Git 整潔規範

• R .gitignore，用於語言、建置輸出和本地環境檔案。
• rec .gitattributes，帶有 * text=auto eol=lf，這樣行尾就不會在作業系統之間變動。
• rec .editorconfig，用於字元集、結尾新行和縮排。

GitHub 範本與自動化

如果儲存庫不在 GitHub 上，請使用託管服務提供商的等效功能。

• rec .github/PULL_REQUEST_TEMPLATE.md。請參閱範本。
• rec Issue 表單在 .github/ISSUE_TEMPLATE/ 中：bug_report.yml、feature_request.yml，以及一個關閉空白 Issue 並將安全回報指向私人管道的 config.yml。請參閱範本。
• rec .github/dependabot.yml，為每個儲存庫使用的套件生態系統加上 github-actions 各有一個條目。
• R .github/workflows/ci.yml，在每個 PR 和每次推送到預設分支時執行與 PR 範本相同的檢查。
• opt .github/release.yml，用於按標籤分組產生的發行說明。
• opt .github/workflows/release.yml，僅用於已發布的專案。
• rec 對預設分支進行分支保護或規則集，要求 CI 通過。這是一個設定，所以先詢問。

Node.js 與 TypeScript

對於其他語言，跳過本節，並使用該生態系統的工具套用相同的概念：一個釘選的執行時期版本、一個格式化工具、一個 linter、一個測試執行器、一個單一的「檢查所有」指令，以及一個 CI 矩陣。

執行時期與中繼資料

• rec .nvmrc，以及 package.json 中的 engines.node，兩者相互一致。
• R package.json 中的 repository、homepage、bugs、license 和 author。
• rec "type": "module" 用於原生 ESM。

TypeScript（僅限 TypeScript 專案）

• R typescript 和一個 tsconfig.json，並帶有一個編譯的 npm run build。
• 不要將 JavaScript 專案轉換為 TypeScript。對於新專案，是否使用 TypeScript 由用戶決定。

格式與 lint

• rec Prettier（.prettierrc.json、.prettierignore）和一個 ESLint flat config。
• rec Scripts lint、lint:fix、format 和 format:check。

單元測試

• R 一個執行單元測試的 npm test。
• rec Vitest，測試檔案放在程式碼旁邊（src/**/*.test.ts），共享的 fixture 放在 test/ 中。

端到端測試（可選，適用於有 UI 或瀏覽器流程的專案）

• rec @playwright/test、一個 playwright.config.ts，以及 e2e/ 中的測試。
• rec 一個 npm run test:e2e 指令。
• rec 將 playwright-report/、test-results/ 和 blob-report/ 加入 .gitignore。
• rec 一個 CI 工作，使用 npx playwright install --with-deps 安裝瀏覽器，並在測試失敗時上傳報告。
• opt 對於沒有瀏覽器的 CLI，改為透過單獨的 Vitest 設定執行端到端測試。

Git hooks（僅限本地開發）

• rec Husky 搭配一個執行 lint-staged 的 pre-commit hook。
• rec 一個 prepare 指令，當 CI 被設定或 NODE_ENV=production 時跳過安裝 Husky，這樣 CI 和生產環境的安裝就不會失敗。
• opt 一個執行單元測試的 pre-push hook。

品質關卡

• rec 一個指令，例如 check，它按順序執行 lint、format:check、單元測試、建置和端到端測試。CI 和貢獻者都執行它。
• rec 一個跨支援的作業系統和 Node.js 版本的 CI 矩陣。

發布

適用於發布到套件註冊表的專案。其他所有情況為可選。

• rec package.json 中的 "files" 允許列表（或 .npmignore），使用 npm pack --dry-run 檢查。
• rec 一個執行建置的 prepublishOnly 指令。
• rec 從 CI 使用 npm Trusted Publishing（OIDC，id-token: write）發布，這樣就不需要將長期存取的 token 儲存為密鑰。
• rec RELEASING.md 涵蓋如何選擇版本（semver）、如何標記發布、哪些檢查會阻止錯誤的標記，以及如何回滾。

範本

檔案	複製到
templates/PULL_REQUEST_TEMPLATE.md	.github/PULL_REQUEST_TEMPLATE.md
templates/ISSUE_TEMPLATE/bug_report.yml	.github/ISSUE_TEMPLATE/bug_report.yml
templates/ISSUE_TEMPLATE/feature_request.yml	.github/ISSUE_TEMPLATE/feature_request.yml
templates/ISSUE_TEMPLATE/config.yml	.github/ISSUE_TEMPLATE/config.yml

預留位置寫成 <like-this>。例如，將 <runtime-version-command> 替換為 node --version、python --version 或 go version。範本中的其他指令是來自 Node.js 專案的範例。將它們替換為儲存庫自己的指令。