project-init

Project initialization skill (three-tier automatic detection)

Design philosophy

One skill, three tiers.Whichever tools are installed on this computer, it automatically builds to that tier—no need to ask the user "which tier do you want".

Tier	Platform	What gets created	When it is read
L1 local	Project folder (recommended to place in your cloud drive folder)	`AGENTS.md`(project blueprint) +`handoff.md`(handoff file)	Read every session
L2 GitHub	Private repo	git version control + cloud backup	Read only when specified
L3 Obsidian	Second brain vault	`專案工作流程.md`(detailed notes)	Read only when needed

Why is the blueprint called AGENTS.md instead of CLAUDE.md? Because AGENTS.md is a cross-Agent open standard—OpenCode, Claude Code, Codex, and Gemini CLI all understand it. The project-level file deliberately uses an open format so that any Agent taking over can work seamlessly. The filename must be all uppercase AGENTS.md: Windows is case-insensitive so a mistake still works, but Mac/Linux is case-sensitive, and a lowercase agents.md will become "the file is clearly there, but the Agent cannot read it".

Tier detection (initialization looks at what "this computer" has)

Check in order to determine which tier can be built this time:

L1: can be built unconditionally
L2: run gh auth status, success (already logged in to GitHub CLI) → can be built
L3: currently has usable Obsidian MCP tools (tools that can list directories and create notes) → can be built
- Please judge based on "which tools you actually have on hand"; do not assume specific tool names

After checking, first tell the user: "This computer can be initialized up to tier N", then begin execution.

Initialization SOP (execute in order)

L1: Local blueprint (always executed)

Scan the current folder state: list existing files; if there is already AGENTS.md or handoff.md → stop and ask the user whether to overwrite
Ask the user: project name, one-sentence goal, key milestones (leave blank if none; do not make them up)
Create AGENTS.md: use the template below as a base, fill in actual content; the "folder structure" section is automatically generated from the scan results
Create handoff.md: use the template below as a base, fill "where it is now" with "project initialization complete", and fill the updater with Agent name + computer name
- Computer name: Windows (PowerShell) uses $env:COMPUTERNAME; Mac/Linux uses hostname
If the path contains "cloud drive", "My Drive", or "Google Drive" → remind the user to confirm that the sync icon of the cloud drive desktop version is checked (the files must actually reside in the cloud so they can be retrieved on another computer)

Template:`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`
- **學生資料只用座號**，不出現姓名、學號、班級以外的個資、照片或聯絡方式
- 要公開分享前，先確認檔案裡沒有上述兩類內容

Template:`handoff.md`

# 交接檔（handoff.md）

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

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

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

## ➡️ 下一步
1.

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

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

L2：GitHub（`gh` only if already logged in; otherwise skip and note it)

The git/GitHub setup for this layeris not rewritten in this skill: for the complete method, follow the quick-start guide 07-github that package. This skill is only responsible for "calling it, then filling back the blueprint".

Confirm gh auth status passes (if it doesn't, skip L2 and tell the user "run the quick-start guide 07-github first")
First create .gitignore(to avoid pushing sensitive files up; this is the only git-related action handled in this skill):
```
desktop.ini
*.tmp
~$*
.env
*.key
credentials.*
```
Following the method in the quick-start guide 07-github , turn this folder into aprivate repo on GitHub and push it up (ask the user for the repo's English name first)
Fill back AGENTS.md the GitHub column of the sync-level table (repo URL)

L3: Obsidian (only if MCP is available; otherwise skip and note it)

Create a folder in the vault root with the same name as the project foldersame namefolder
Create <專案資料夾名>/專案工作流程.md, with contents including: project background and detailed context, decision records (why it was done this way), links to materials and related notes, 🕳️ pitfall notes, 🗓️ recent changes record table (first row writes today's initialization)
Fill back AGENTS.md the Obsidian column of the sync-level table (path within the vault)

Report

Give the user a level checklist:

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

Things that should not be done

❌ Overwriting an existing AGENTS.md／handoff.md
❌ Writing the blueprint filename in lowercase agents.md(Mac/Linux won't be able to read it)
❌ Erroring out and stopping when the computer doesn't have gh/Obsidian (correct behavior: skip that level, and note the reason in the report)
❌ Committing sensitive files like .envand API keys into git
❌ Creating a public repo (default is always private; only switch to public if the user explicitly says so)

Notes

UseTraditional Chinese
If a write error occurs when running git in a Windows + cloud drive folder:git config windows.appendAtomically false
The subsequent daily cycle is handed to the companion skill: startup reads, shutdown writes