SKILL.md
readonlyread-only
name
create-agentsmd
description
用於為儲存庫產生 AGENTS.md 檔案的提示
建立高品質的 AGENTS.md 檔案
你是一個程式碼代理。你的任務是在此儲存庫的根目錄建立一個完整且準確的 AGENTS.md，遵循 https://agents.md/ 上的公開指引。
AGENTS.md 是一個開放格式，旨在為程式碼代理提供有效處理專案所需的背景和指示。
什麼是 AGENTS.md？
AGENTS.md 是一個 Markdown 檔案，作為「代理的 README」——一個專用且可預測的位置，用來提供背景和指示，幫助 AI 程式碼代理在你的專案上工作。它補充了 README.md，包含程式碼代理需要的詳細技術背景，但這些內容可能會讓以人為主的 README 顯得雜亂。
關鍵原則
- 以代理為中心：包含給自動化工具的詳細技術指示
- 補充 README.md：不取代人類文件，而是增加代理專用的背景
- 標準化位置：放在儲存庫根目錄（或 monorepo 的子專案根目錄）
- 開放格式：使用標準 Markdown，結構靈活
- 生態系統相容性：適用於 20 多種不同的 AI 程式碼工具和代理
檔案結構與內容指南
1. 必要設定
- 在儲存庫根目錄建立
AGENTS.md檔案 - 使用標準 Markdown 格式
- 無必要欄位——根據專案需求靈活結構
2. 應包含的基本章節
專案概述
- 專案功能的簡短描述
- 若架構複雜，提供架構概述
- 使用的關鍵技術和框架
設定指令
- 安裝說明
- 環境設定步驟
- 依賴管理指令
- 資料庫設定（如適用）
開發工作流程
- 如何啟動開發伺服器
- 建置指令
- 監看/熱重載設定
- 套件管理器細節（npm、pnpm、yarn 等）
測試說明
- 如何執行測試（單元、整合、端對端）
- 測試檔案位置與命名慣例
- 涵蓋率要求
- 使用的特定測試模式或框架
- 如何執行測試子集或專注於特定範圍
程式碼風格指南
- 語言特定的慣例
- Linting 與格式化規則
- 檔案組織模式
- 命名慣例
- 匯入/匯出模式
建置與部署
- 建置指令與輸出
- 環境設定
- 部署步驟與需求
- CI/CD 管線資訊
3. 可選但建議的章節
安全考量
- 安全測試需求
- 機密管理
- 驗證模式
- 權限模型
Monorepo 說明（如適用）
- 如何處理多個套件
- 跨套件依賴
- 選擇性建置/測試
- 套件專用指令
Pull Request 指南
- 標題格式要求
- 提交前必要的檢查
- 審查流程
- 提交訊息慣例
除錯與疑難排解
- 常見問題與解決方案
- 日誌模式
- 除錯設定
- 效能考量
範例模板
使用此模板作為起點，並根據特定專案進行自訂：
# AGENTS.md
## 專案概述
[專案簡短描述、目的與關鍵技術]
## 設定指令
- 安裝依賴：`[package manager] install`
- 啟動開發伺服器：`[command]`
- 建置生產版本：`[command]`
## 開發工作流程
- [開發伺服器啟動說明]
- [熱重載/監看模式資訊]
- [環境變數設定]
## 測試說明
- 執行所有測試：`[command]`
- 執行單元測試：`[command]`
- 執行整合測試：`[command]`
- 測試涵蓋率：`[command]`
- [特定測試模式或需求]
## 程式碼風格
- [語言與框架慣例]
- [Linting 規則與指令]
- [格式化需求]
- [檔案組織模式]
## 建置與部署
- [建置流程細節]
- [輸出目錄]
- [特定環境的建置]
- [部署指令]
## Pull Request 指南
- 標題格式：[元件] 簡短描述
- 必要檢查：`[lint command]`、`[test command]`
- [審查需求]
## 其他備註
- [任何專案特定的背景]
- [常見陷阱或疑難排解提示]
- [效能考量]
來自 agents.md 的實際範例
以下是來自 agents.md 網站的實際範例：
# 範例 AGENTS.md 檔案
## 開發環境提示
- 使用 `pnpm dlx turbo run where <project_name>` 跳轉到套件，而不是用 `ls` 掃描。
- 執行 `pnpm install --filter <project_name>` 將套件加入工作區，讓 Vite、ESLint 和 TypeScript 能看見它。
- 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 快速建立新的 React + Vite 套件，並準備好 TypeScript 檢查。
- 檢查每個套件 package.json 中的 name 欄位以確認正確名稱——跳過頂層的那個。
## 測試說明
- 在 .github/workflows 資料夾中找到 CI 計畫。
- 執行 `pnpm turbo run test --filter <project_name>` 來執行該套件定義的所有檢查。
- 從套件根目錄可以直接執行 `pnpm test`。提交前應通過所有測試。
- 若要專注於某一步驟，加入 Vitest 模式：`pnpm vitest run -t "<test name>"`。
- 修正所有測試或型別錯誤，直到整個套件都通過。
- 移動檔案或變更匯入後，執行 `pnpm lint --filter <project_name>` 以確保 ESLint 和 TypeScript 規則仍然通過。
- 為你變更的程式碼新增或更新測試，即使沒有人要求。
## PR 說明
- 標題格式：[<project_name>] <Title>
- 提交前務必執行 `pnpm lint` 和 `pnpm test`。
實作步驟
-
分析專案結構以了解：
- 使用的程式語言與框架
- 套件管理器與建置工具
- 測試框架
- 專案架構（monorepo、單一套件等）
-
識別關鍵工作流程，檢查：
- package.json 中的 scripts
- Makefile 或其他建置檔案
- CI/CD 設定檔
- 文件檔案
-
建立全面的章節，涵蓋：
- 所有必要的設定與開發指令
- 測試策略與指令
- 程式碼風格與慣例
- 建置與部署流程
-
包含具體、可執行的指令，讓代理可以直接執行
-
測試指示，確保所有指令如文件所述般運作
-
保持專注在代理需要知道的內容，而非一般專案資訊
最佳實踐
- 具體明確：包含確切指令，而非模糊描述
- 使用程式碼區塊：用反引號包裹指令以增加清晰度
- 包含背景：解釋為何需要某些步驟
- 保持更新：隨著專案演進而更新
- 測試指令：確保所有列出的指令確實可行
- 考慮巢狀檔案：對於 monorepo，在子專案中建立 AGENTS.md 檔案（如需要）
Monorepo 考量
對於大型 monorepo：
最終備註
- AGENTS.md 適用於 20 多種 AI 程式碼工具，包括 Cursor、Aider、Gemini CLI 等
- 格式刻意保持靈活——根據專案需求調整
- 專注於可執行的指示，幫助代理理解並與你的程式碼庫協作
- 這是活文件——隨著專案演進而更新
建立 AGENTS.md 檔案時，優先考慮清晰度、完整性和可執行性。目標是讓任何程式碼代理有足夠的背景來有效貢獻專案，無需額外的人類指導。
