初始化 AGENTS.md
為儲存庫根或一個既有目錄建立貢獻者指南。輸出格式和推薦章節的唯一來源是 references/agents-md-prompt.md；本 skill 負責把這份固定指令安全地應用到正確的作用域。
輸入與作用域
- 接受零或一個目錄參數，相對路徑按當前工作目錄解析。無參數時使用
git rev-parse --show-toplevel找到的 Git 根目錄。 - 顯式目錄可以不在 Git 儲存庫中；無參數且找不到 Git 根時，要求使用者指定目錄並停止。路徑必須解析為可讀目錄；缺失路徑、檔案、不可讀目錄或多個目錄參數都停止。
- 預設候選輸出為該目錄的
AGENTS.md。一次只處理一個作用域，不建立目錄，不改動其他檔案，不暫存、提交或建立分支。 - 正文跟隨本地文件主語言；訊號不足時使用英文。若選定目錄不是儲存庫根，輸出在開頭加入
## Scope，說明相對目錄和適用父級指南，只寫本地新增或收窄規則。
先偵查，再產生
- 在草擬前讀取目標和必要的專案上下文：目錄結構、manifest/lockfile、腳本、建構/測試/lint 設定、CI、README/CONTRIBUTING，以及 Git 可用時最多 30 條相關提交。識別 monorepo 套件邊界、套件管理器和本地文件主語言。
- 找出所有相關
AGENTS.md：目標檔案、從儲存庫根到目標父目錄的祖先檔案，以及目標子樹中的巢狀檔案。對非 Git 目錄，按祖先鏈檢查。子樹先檢查直接子目錄，只在 manifest、套件邊界或已有指南指向更深層時擴展；跳過.git、依賴/vendor、建構/coverage 輸出、快取和被忽略的密碼儲存。 - 將匹配項標為
target、ancestor或nested，並讀取CLAUDE.md、CONTRIBUTING.md等相關指南作為約束。巢狀指南只讀取、保留，必要時連結；不合併或修改它們。 - 僅檢查潛在秘密檔案的名稱和元資料。絕不讀取或寫入金鑰、token、憑證或
.env內容。 - 每個命令和約定必須能由腳本、設定、已有檔案或歷史驗證。區分觀察到的儲存庫規則和通用預設建議；沒有證據的章節、命令或斷言直接省略。
匹配指南確認
在產生草稿前，展示所有匹配項、各自作用域和候選輸出路徑，並檢查大小寫衝突（例如 agents.md）。這是一道硬門檻：
- 候選目標已存在時，讀取它並要求使用者選擇
merge、replace或abort。 - 目標不存在但發現祖先或巢狀指南時，要求使用者明確選擇「建立該作用域的新指南」或「更新某個命名的現有指南」；不得靜默新增子級檔案。若選擇其他現有檔案，按該檔案目錄重新偵查後再選擇模式。
- 沒有匹配項時，繼續為原目標草擬新檔案。
- 選中的
AGENTS.md是符號連結、目錄、特殊檔案或不可寫的一般檔案時停止並報告原因。
任何未回答、含糊的選擇或與 CLAUDE.md 等指南的衝突，都保持工作區不變。
讀取固定指令
在開始草擬前完整讀取 references/agents-md-prompt.md。它是標題、文件要求、推薦章節、字數目標和表達風格的 canonical owner；正常運行時不改寫它，也不要在本 skill 中複製它的正文。
合併、預覽與寫入
merge 按 Markdown 標題語意合併：保留既有事實和自訂章節，只補入缺失且有證據的內容。把全部命令、路徑、優先級或事實衝突列成一張表，讓使用者逐項選擇保留現有、採用證據或提供自訂文字；存在未決衝突時不得寫入。replace 只影響選中的單一檔案，不自動產生備份。
新檔案展示完整草稿；更新展示 unified diff，並附路徑、作用域、章節、字數、證據缺口和模式摘要。使用者明確確認最終寫入前不建立或修改檔案；要求修改則回到草擬和預覽。寫入前重新讀取目標，若內容已被外部改動，重新走確認流程。
校驗與完成
寫入前檢查標題、標題層級、巢狀指南的作用域連結、引用的路徑/腳本、佔位符、敏感值和 Markdown 空白；根指南按固定指令的字數目標檢查，巢狀增量按約 100-300 詞檢查。只自動修復尾隨空格、重複空行等機械問題，並再次預覽；語意或事實問題交給使用者決定。目標在 Git 中時執行 git diff --check，否則做等價空白檢查；不要為本 skill 預設執行完整 build、test 或 lint。
完成條件：已確認的 AGENTS.md 在選定路徑存在、通過靜態檢查、與批准的預覽一致；最終報告模式、作用域、已验证命令、遺漏/不確定項和校驗結果。使用者 abort 或校驗無法通過時，報告原因並保持目標不變。