專案初始化技能（三層級自動偵測）

設計理念

一套技能、三個層級。這台電腦裝了什麼工具，就自動建到哪個層級——不用問使用者「你要第幾層級」。

為什麼藍圖叫 AGENTS.md 而不是 CLAUDE.md？因為 AGENTS.md 是跨 Agent 開放標準——OpenCode、Claude Code、Codex、Gemini CLI 都讀得懂。專案層的檔案刻意用開放格式，任何 Agent 接手都能無縫工作。 檔名必須全大寫 AGENTS.md：Windows 不分大小寫所以寫錯也能動，但 Mac／Linux 分大小寫，小寫的 agents.md 會變成「檔案明明在、Agent 卻讀不到」。

層級偵測（初始化看「這台電腦」有什麼）

依序檢查，決定本次能建到第幾層級：

1. L1：無條件可建
2. L2：跑 gh auth status，成功（已登入 GitHub CLI）→ 可建
3. L3：目前有可用的 Obsidian MCP 工具（能列目錄、建立筆記的工具）→ 可建
   • 請依「你手上實際有哪些工具」判斷，不要假設特定的工具名稱

檢查完先告訴使用者：「這台電腦可初始化至第 N 層級」，再開始執行。

初始化 SOP（依序執行）

L1：本地藍圖（永遠執行）

1. 掃描資料夾現況：列出既有檔案，若已有 AGENTS.md 或 handoff.md → 停下來問使用者是否要覆蓋
2. 詢問使用者：專案名稱、一句話目標、關鍵時程（沒有就留白，不要硬編）
3. 建立 AGENTS.md：用下方範本為底，填入實際內容；「資料夾結構」區塊由掃描結果自動生成
4. 建立 handoff.md：用下方範本為底，「目前做到哪」填「專案初始化完成」，更新者填 Agent 名＋電腦名
   • 電腦名：Windows（PowerShell）用 $env:COMPUTERNAME；Mac／Linux 用 hostname
5. 若路徑含「雲端硬碟」「My Drive」「Google Drive」→ 提醒使用者確認雲端硬碟桌面版的同步圖示已打勾（檔案要真的躺在雲端，換電腦才拿得到）

範本：AGENTS.md

# <專案名稱>（專案藍圖）

> 本檔為跨 Agent 通用的專案藍圖（AGENTS.md 開放標準）。任何 Agent 的每個 session 都應先讀本檔＋`handoff.md`。

## 專案簡介
<!-- 一段話：這個專案是什麼、目標是什麼 -->

## 關鍵時程
<!-- 格式：- 事件名稱：日期（說明）；沒有就留白 -->

## 目標與路線圖
<!-- 用 checklist 追蹤，收工技能會更新這裡 -->
- [ ] 階段一：
- [ ] 階段二：

## 資料夾結構
<!-- 初始化時自動掃描生成，之後新增檔案要更新 -->

## 同步層級（本專案初始化至第 N 層級）

| 層級 | 平台 | 位置 | 讀取時機 |
|------|------|------|---------|
| L1 | 本地（雲端硬碟資料夾） | `AGENTS.md`＋`handoff.md` | 每個 session |
| L2 | GitHub | <未啟用｜<你的 GitHub 帳號>/repo-name> | 指定時 |
| L3 | Obsidian | <未啟用｜專案資料夾名/專案工作流程.md> | 有需要時 |

## 工作約定
- 任何 Agent、任何電腦：**開工先讀 `handoff.md`，收工必更新 `handoff.md`**
- 修改共用檔案前先讀最新內容，避免覆蓋其他 Agent 的變更
- 所有回應與文件使用繁體中文
- 修改前先確認計畫，優先保留原有資料結構

## 安全與隱私（不可違反）
- **不把 API key、密碼、憑證寫進 repo**，也不要貼進 `AGENTS.md`／`handoff.md`；一律放 `.env` 並列入 `.gitignore`
- **學生資料只用座號**，不出現姓名、學號、班級以外的個資、照片或聯絡方式
- 要公開分享前，先確認檔案裡沒有上述兩類內容

範本：handoff.md

# 交接檔（handoff.md）

> 任何 Agent、任何電腦接手前**必讀**；收工時**必更新**。本檔只放交接必需的精簡資訊，詳細脈絡放 Obsidian（若有 L3）。

## ⏯️ 目前做到哪
<!-- 最後完成的動作，1-3 句 -->
專案初始化完成。

## 🚦 目前狀態
<!-- 可運行嗎？哪些做一半？ -->

## ➡️ 下一步
1.

## ⚠️ 注意事項
<!-- 坑、暫時 workaround、不要動的東西 -->

## 🕐 最後更新
- 時間：<YYYY-MM-DD HH:mm>
- 更新者：<Agent 名> @ <電腦名>
- Git push：<✅ 已推｜❌ 未推（原因）｜—（本專案未啟用 git）>

L2：GitHub（gh 已登入才做，否則跳過並註明）

這一層的 git／GitHub 設定不在本技能重寫：完整做法請依懶人包 07-github 那一包。 本技能只負責「呼叫它、然後回填藍圖」。

6. 確認 gh auth status 通過（沒過就跳過 L2，並告訴使用者「先跑懶人包 07-github」）
7. 先建立 .gitignore（避免把敏感檔推上去，這是唯一在本技能處理的 git 相關動作）：

   desktop.ini
   *.tmp
   ~$*
   .env
   *.key
   credentials.*

8. 依懶人包 07-github 的做法，把這個資料夾變成 GitHub 上的私有 repo 並推上去 （repo 的英文名字要先問使用者）
9. 回填 AGENTS.md 同步層級表的 GitHub 欄（repo 網址）

L3：Obsidian（MCP 可用才做，否則跳過並註明）

10. 在 vault 根目錄建立與專案資料夾同名的資料夾
11. 建立 <專案資料夾名>/專案工作流程.md，內容包含：專案背景與詳細脈絡、決策紀錄（為什麼這樣做）、素材與相關筆記連結、🕳️ 踩坑筆記、🗓️ 最近更動紀錄表格（第一行寫今天的初始化）
12. 回填 AGENTS.md 同步層級表的 Obsidian 欄（vault 內路徑）

回報

給使用者一個層級 checklist：

🏗️ 本專案初始化至第 N 層級
✅ L1 本地：AGENTS.md ＋ handoff.md
✅ L2 GitHub：<你的 GitHub 帳號>/<repo>（私有）
⚠️ L3 Obsidian：未建（這台電腦沒有 Obsidian MCP，之後可在有 Obsidian 的電腦說「補建第三層級」）

不該做的事

• ❌ 未經確認就覆蓋既有的 AGENTS.md／handoff.md
• ❌ 把藍圖檔名寫成小寫 agents.md（Mac／Linux 會讀不到）
• ❌ 電腦沒 gh／Obsidian 時報錯中斷（正確行為：跳過該層級、在回報中註明原因）
• ❌ 把 .env、API key 之類敏感檔 commit 進 git
• ❌ 建 public repo（預設一律 private，使用者明說才轉公開）

注意事項

• 所有訊息與檔案內容使用繁體中文
• Windows＋雲端硬碟資料夾內跑 git 若遇寫入錯誤：git config windows.appendAtomically false
• 之後的日常循環交給搭檔技能：開工（startup）讀、收工（shutdown）寫