opencode-workflow-skills

The three major skills: startup / shutdown / project-init (OpenCode full version)

Updated: 2026-07-27

Once you install this package, you only need to say three sentences to OpenCode, and the project can seamlessly continueon any computer, any AI Agent :

Command	Skill	What it does
「Initialize project」	`project-init`	Create a project blueprint for this folder `AGENTS.md` + handoff file `handoff.md`; if there is GitHub, also create a private repo, and if there is Obsidian, create detailed notes
「Startup」	`startup`	Read the blueprint + handoff file, report "where you left off, which computer you finished on last time, git status, suggested next step"
「Shutdown」	`shutdown`	Update blueprint progress, rewrite the handoff file, git commit + push, write detailed records into Obsidian

The core design in one sentence: startup is "read", shutdown is "write". The two processes never overlap and never conflict.

Three levels: the skills do as much as you install

These three skills willautomatically detectyour tools; no need to choose a version or change settings:

Level	What needs to be installed first	What you get
L1 Local	Nothing at all (recommended to put the project in your cloud drive folder)	`AGENTS.md`＋`handoff.md`, switching computers relies on cloud drive automatic sync
L2 ＋GitHub	Quick-start package 07-github（`gh auth login` already logged in)	Version control + cloud backup
L3 ＋Obsidian	Quick-start package 04-obsidian(Obsidian MCP available)	Detailed project notes (second brain)

The three layers of information have differentread frequencies, and this is the soul of the whole design:

AGENTS.md＋handoff.md：Read every session(only contains the concise information necessary for handoff)
GitHub：Read only when specified(backup and history)
Obsidian：Read only when needed(full context and details)

Prerequisites

OpenCode is installed (quick-start package 00-env-setup）
(only needed if you want L2) quick-start package 07-github is complete,gh auth status passed
(only needed if you want L3) quick-start package 04-obsidian is complete
If you only do L1, you can skip both of the above for now and add them later

Please have OpenCode execute the following steps for me

Step 1: Create three skill folders

Windows（PowerShell）：

New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\startup"
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\shutdown"
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\project-init"

Mac／Linux：

mkdir -p ~/.config/opencode/skills/startup
mkdir -p ~/.config/opencode/skills/shutdown
mkdir -p ~/.config/opencode/skills/project-init

⚠️ The filename must beall uppercase SKILL.md, and the folder name must match the skill's name exactly, so OpenCode can scan it.

Step 2: Create the startup skill

Write the entire block below verbatim into ~/.config/opencode/skills/startup/SKILL.md （Do notwrite the outermost ```` fence symbols into the file; the first line of the file must be ---）：

---
name: startup
description: 開工接續助手（三層級自動偵測）。當使用者說「開工」、「開始工作」、「我來了」、「上次做到哪」、「我們繼續」、「接下來呢」、「接續工作」、「來吧」等任何要接續上次工作的請求時，請一定要使用此技能。本技能會讀取 AGENTS.md 專案藍圖與 handoff.md 交接檔、檢查 git 狀態（含遠端 fetch）、辨識上次是否在另一台電腦收工、建議下一步該做什麼。
---

# 開工接續助手（三層級）

新對話開始時，幫使用者快速進入「上次做到哪」的脈絡，避免從零開始解釋。

## 核心原則

1. **開工是「讀」、收工是「寫」**——本技能只讀、只報告，不改任何檔案
2. **不主動 `git pull`**（避免覆蓋本地未 commit 變動，只提醒「要不要 pull」）
3. **30 分鐘內 fetch 過就跳過**（避免單台多對話冗餘）
4. **Obsidian 有需要才讀**——L3 筆記是詳細背景資料，開工預設不讀、只列出路徑
5. 跟收工（shutdown）技能是**對偶關係**：收工存進去、開工讀出來

## 層級偵測（開工看「這個專案」建到哪層）

- **L1**：專案有 `AGENTS.md`／`handoff.md` → 讀
- **L2**：專案有 `.git` → 做 git 檢查
- **L3**：`AGENTS.md` 同步層級表登記了 Obsidian 路徑，且**目前有可用的 Obsidian MCP 工具**（例如能列出 vault 目錄、讀寫筆記的工具）→ 列出筆記路徑（不主動讀）

> 判斷 L3 時請看「你手上實際有哪些工具」，不要假設特定的工具名稱——不同的 Obsidian MCP 名稱不一樣。
> 注意：偵測依據是「專案有什麼」，不是「電腦有什麼」。低層級電腦打開高層級專案時做得到的照做、做不到的註明（優雅降級）。

## 開工 SOP（依序執行）

### L1：讀藍圖與交接檔（永遠執行）

1. **讀 `AGENTS.md`**：專案目標、路線圖進度、工作約定（摘要，不全文倒出）
2. **讀 `handoff.md`**：上次做到哪、目前狀態、下一步、注意事項
3. **檢查「最後更新」欄**：
   - 取得這台電腦的名稱——Windows（PowerShell）用 `$env:COMPUTERNAME`；Mac／Linux 用 `hostname`
   - 若**更新者的電腦名 ≠ 這台電腦** → 特別標示「⚠️ 上次在另一台電腦（名稱）收工」，並確認雲端硬碟同步已完成（看 `handoff.md` 的檔案時間戳是否與交接檔內寫的時間吻合；若本地檔案明顯過舊，提醒等雲端同步完再開工）
   - 若 `handoff.md` 的更新時間比 `AGENTS.md` 舊很多 → 提醒「上次可能沒有正式收工」

**Fallback（舊專案相容）**：若專案沒有 `AGENTS.md`／`handoff.md`：
- 有 Obsidian MCP → 改讀 `<你的 vault>/<專案資料夾名>/專案工作流程.md` 或 `工作筆記.md` 的「上次做到哪」段
- 讀完提議：「這個專案還沒有 AGENTS.md＋handoff.md，要不要用『初始化專案』補建？」（提議即可，不主動建）

### L2：git 檢查（專案有 `.git` 才做）

4. **本地狀態**：`git status --short`
   - clean → 「本地工作區乾淨」
   - 有未 commit 變動 → 列出，提醒「上次有未完成的修改，要繼續還是放棄？」
5. **遠端狀態（30 分鐘規則）**：
   1. 先看 `.git/FETCH_HEAD` 的最後修改時間（用你手上的檔案工具讀取時間戳即可，**不要用只有某個平台才有的 shell 語法**）
   2. 檔案不存在，或距離現在**超過 30 分鐘** → 執行：
      ```
      git fetch origin
      ```
   3. 再看落後幾個 commit：
      ```
      git rev-list --count "HEAD..@{u}"
      ```
      > 引號不能省：PowerShell 會把沒加引號的 `@{...}` 當成 hashtable 語法而報錯。
      > 若回報「沒有上游分支」之類的錯誤 → 視為 0，並在報告註明「尚未設定上游分支」。
   4. 落後 > 0 → 提醒「遠端有 N 個新 commit，要 `git pull` 嗎？」**不主動 pull**
6. **交叉比對防呆**：若 `handoff.md` 寫「Git push：✅」但遠端沒有對應的新 commit → 警告「上次收工可能沒推成功，建議先確認再動工」

### L3：Obsidian 筆記（有登記才列，不主動讀）

7. 在報告中列出筆記路徑（例：`<專案資料夾名>/專案工作流程.md`），註明「需要詳細背景時我再去讀」
8. 只有兩種情況才主動讀：`handoff.md` 的「下一步」明確指向筆記內容，或使用者要求

### 報告 + 建議下一步

給使用者**結構化摘要**（不要冗長）：

```
📂 專案：<資料夾名>（第 N 層級）
📘 上次做到哪：<handoff 摘要 1-2 句>（<時間>，<更新者> @ <電腦名>）
🔧 本地 git：<clean｜有 N 個未 commit 變動｜—（L1 專案）>
🌐 遠端：<最新｜落後 N commits，建議 git pull｜—>
🧠 Obsidian：<筆記路徑，需要時再讀｜—>
➡️ 建議下一步：
   1. <handoff「下一步」第 1 項>
   2. <可選：第 2 項>

要從哪個方向開始？
```

最後**等使用者選方向**，不要自己擅自繼續。

## 不該做的事

- ❌ 主動 `git pull`（會撞本地未 commit 變動）
- ❌ 修改 `AGENTS.md`／`handoff.md`／Obsidian 筆記（那是收工的事）
- ❌ 沒有交接檔時硬建一個（先問使用者）
- ❌ 開工就把 Obsidian 筆記全文讀進來（違反「有需要才讀」的分層設計）
- ❌ 把藍圖與交接檔內容**全文倒出來**（要摘要、保持精簡）

## 與收工（shutdown）的對偶關係

| 面向 | 收工 | 開工 |
|------|------|------|
| 主要動作 | 摘要今天做什麼 | 摘要上次做什麼 |
| AGENTS.md / handoff.md | **寫入** | **讀出** |
| Git 動作 | add + commit + push | status + fetch（不 pull） |
| Obsidian | 寫詳細紀錄 | 只列路徑、需要才讀 |
| 對外副作用 | 推 GitHub、改檔案 | **無**（只讀、只報告） |

## 注意事項

- 所有訊息使用**繁體中文**
- 專案藍圖檔名固定是**全大寫 `AGENTS.md`**（跨 Agent 開放標準）。Mac／Linux 會區分大小寫，寫成小寫會變成「檔案在、Agent 卻讀不到」

Step 3: Create the shutdown skill

Write the entire following content verbatim into ~/.config/opencode/skills/shutdown/SKILL.md：

---
name: shutdown
description: 收工同步助手（三層級自動偵測）。當使用者說「收工」、「結束了」、「下班」、「準備換電腦」、「同步」、「先到這裡」、「換電腦繼續做」等任何要結束工作並保存進度的請求時，請一定要使用此技能。本技能會更新 AGENTS.md 進度與 handoff.md 交接檔、git commit + push、把詳細紀錄寫進 Obsidian，確保下次（或在另一台電腦、或換一個 Agent）打開能無縫接續。
---

# 收工同步助手（三層級）

對話結束前，把這次的工作保存到專案建到的每一層：

| 層級 | 收工動作 | 給誰看 |
|------|---------|--------|
| L1 本地 | 更新 `AGENTS.md` 進度＋改寫 `handoff.md` | 下一個 session 的任何 Agent、任何電腦 |
| L2 GitHub | commit + push | 版本歷史＋雲端備份 |
| L3 Obsidian | 詳細紀錄寫進 `專案工作流程.md` | 未來需要完整脈絡的自己 |

## 核心原則

1. **開工是「讀」、收工是「寫」**——`handoff.md` 是收工的必寫項，這是跨電腦／跨 Agent 交接的生命線
2. **不在 vacuum 中執行**——先從對話脈絡盤點今天做了什麼
3. **只動需要動的**——沒實質進度（只是問問題、沒改檔案）就不跑同步
4. **有疑問先問人**——commit 前先給訊息草稿等點頭；不確定要不要 add 的檔案先問
5. **精簡與詳細分家**——`handoff.md` 只放交接必需資訊，完整脈絡（決策原因、踩坑細節）寫 Obsidian，兩邊不重複

## 層級偵測（收工看「這個專案」建到哪層）

- **L1**：專案有 `AGENTS.md`／`handoff.md` → 更新（沒有就提議先跑「初始化專案」）
- **L2**：專案有 `.git` → commit + push
- **L3**：`AGENTS.md` 登記了 Obsidian 路徑，且**目前有可用的 Obsidian MCP 工具**（能讀寫 vault 筆記的工具）→ 寫詳細紀錄

> 判斷 L3 請看你手上實際有哪些工具，不要假設特定工具名稱。
> 低層級電腦打開高層級專案：做得到的照做，做不到的在 `handoff.md` 註明（例：「本次在無 Obsidian 的電腦收工，L3 筆記未更新」），回到高層級電腦時補。

## 收工 SOP（依序執行）

### L1：更新藍圖與交接檔（永遠執行）

1. **盤點本次成果**：從對話歷史摘要——完成了哪些檔案、做了什麼決定、踩了什麼坑
2. **更新 `AGENTS.md`**：
   - 路線圖 checklist：勾掉完成項、新增發現的待辦
   - 「資料夾結構」有新增檔案就補
3. **改寫 `handoff.md`**（整份重寫，不是往下堆）：
   - ⏯️ 目前做到哪：本次最後完成的動作
   - 🚦 目前狀態：可運行？哪些做一半？
   - ➡️ 下一步：具體、可執行的 1-3 項
   - ⚠️ 注意事項：新踩的坑、暫時 workaround
   - 🕐 最後更新：時間＋更新者（Agent 名 @ 電腦名）＋ Git push 狀態（先寫「待推」，L2 完成後回填）
     - 電腦名取得方式：Windows（PowerShell）用 `$env:COMPUTERNAME`；Mac／Linux 用 `hostname`

### L2：git 同步（專案有 `.git` 才做）

4. `git status --short` 看變動 → 擬**繁體中文** commit 訊息（標題：動詞＋對象；正文 3-5 條 bullet 描述變動＋為什麼）→ **給使用者過目，點頭再 commit**
5. commit → `git push`
6. **回填 `handoff.md` 的 Git push 欄**：成功 → `✅ 已推`；失敗 → `❌ 未推（原因）`，並在回報中特別提醒（沒推成功，另一台電腦就拿不到 GitHub 備份）
7. 不要 add：`.env`、API key、憑證檔、untracked 的不明新檔（先問）

### L3：Obsidian 詳細紀錄（可用才做）

8. 更新 `<你的 vault>/<專案資料夾名>/專案工作流程.md`：
   - 「⏯️ 上次做到哪」段：同步 handoff 摘要
   - 「🗓️ 最近更動紀錄」表格：加一行（日期＋摘要＋同步狀態）
   - 「🕳️ 踩坑筆記」：有新坑就依分類補（含原因與解法，這裡寫詳細版）
   - 決策紀錄：本次做了什麼取捨、為什麼（handoff 不放這些，放這裡）
9. 表格超過 30 行 → 提醒使用者歸檔到 `歷史日誌.md`

### 回報（層級 checklist）

```
✅ L1 本地：AGENTS.md 進度已更新、handoff.md 已改寫（更新者：<Agent> @ <電腦名>）
✅ L2 GitHub：<repo> 已 commit + push（<commit 標題>）
✅ L3 Obsidian：專案工作流程.md 已補紀錄
⚠️ 手動處理：<例：本次新增了 ~/.xxx_api_key，另一台電腦要手動建>
```

沒做到的項目用 ⚠️ 或 ❌ 並說明原因。
若本次改過 `~/.config/opencode/` 底下的全域設定或技能，要特別提醒使用者：**這些檔案不在專案 repo 裡，不會被這次的 push 帶走**，換電腦要自己再裝一次或另外複製。

## 不該做的事

- ❌ 對「沒實質進度」的對話也跑同步
- ❌ 沒更新 `handoff.md` 就收工（那是下次開工的唯一線索）
- ❌ commit message 寫「更新」、「修改」這種沒資訊的字
- ❌ 自動 add untracked 的新檔或敏感檔（要使用者確認）
- ❌ 把該寫進 Obsidian 的長篇細節塞進 `handoff.md`（交接檔要保持一頁內讀完）

## 與開工（startup）的對偶關係

| 面向 | 收工 | 開工 |
|------|------|------|
| AGENTS.md / handoff.md | **寫入** | **讀出** |
| Git 動作 | add + commit + push | status + fetch（不 pull） |
| Obsidian | 寫詳細紀錄 | 只列路徑、需要才讀 |
| 對外副作用 | 推 GitHub、改檔案 | 無 |

## 注意事項

- 所有訊息使用**繁體中文**
- 專案藍圖檔名固定是**全大寫 `AGENTS.md`**（Mac／Linux 會區分大小寫）
- Windows＋雲端硬碟資料夾內的 repo，第一次操作若遇 git 寫入錯誤：`git config windows.appendAtomically false`

Step 4: Create the project-init (initialize project) skill

Write the entire following content verbatim into ~/.config/opencode/skills/project-init/SKILL.md：

---
name: project-init
description: 專案初始化技能（三層級自動偵測）。當使用者說「初始化專案」、「專案初始化」、「幫這個專案做初始化」、「開新專案」、「建立專案藍圖」、「幫我 init 專案」等要為當前資料夾建立專案基礎建設的請求時，請一定要使用此技能。本技能會依這台電腦的工具鏈自動建到最高可用層級：L1 本地（AGENTS.md + handoff.md）→ L2 GitHub（私有 repo）→ L3 Obsidian（專案詳細筆記）。
---

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

## 設計理念

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

| 層級 | 平台 | 建立的東西 | 讀取時機 |
|------|------|-----------|---------|
| L1 本地 | 專案資料夾（建議放在你的雲端硬碟資料夾） | `AGENTS.md`（專案藍圖）＋`handoff.md`（交接檔） | **每個 session 都讀** |
| L2 GitHub | 私有 repo | git 版本控制＋雲端備份 | 指定才讀 |
| L3 Obsidian | 第二大腦 vault | `專案工作流程.md`（詳細筆記） | 有需要才讀 |

> 為什麼藍圖叫 `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`

```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`

```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）寫

Step 5: Configure opencode.json permissions

Open (or create)~/.config/opencode/opencode.json, and confirm it contains this section:

{
  "permission": {
    "skill": {
      "startup": "allow",
      "shutdown": "allow",
      "project-init": "allow",
      "*": "ask"
    }
  }
}

Meaning: these three skills can be used directly, and all other skills will ask you first.

⚠️ If opencode.json already has content (for example, the MCP settings added by the quick-start guide earlier),do not overwrite the entire file, just merge in the "permission" block. Each JSON block must be separated by a comma, and the last item must not have a comma.

Step 6: Restart OpenCode

OpenCode only scans the skills directory at startup. The three folders just added will only be recognized after fully closing OpenCode and opening it again.

(In the terminal, press Ctrl + C to exit, or just close the window, then type opencode again to start.)

Verification steps

After restarting, do these three things in order:

1. Confirm the skills are scanned

Tell OpenCode:

"List the skills you currently have available. Are there startup, shutdown, and project-init?"

All three must appear. If they do not appear → see the first question in "Common issues" below.

2. Test "start work"

cd to any project folder, then say:

"start work"

If it works, you will see a structured summary like this (for a folder without AGENTS.md , it will ask whether you want to initialize, and that also counts as success):

📂 專案：<資料夾名>（第 1 層級）
📘 上次做到哪：（尚未建立 handoff.md）
➡️ 建議下一步：要不要先跑「初始化專案」？

3. Test "initialize project" + "finish work"

Find a new empty folder, say "initialize project", and see whether it creates AGENTS.md(confirm it isall uppercase) and handoff.md. Then modify any file and say "finish work" to see whether it reports the L1/L2/L3 checklist.

Completion report format

Ask OpenCode to report in this format:

## 三大技能安裝完成

- startup：~/.config/opencode/skills/startup/SKILL.md ✅
- shutdown：~/.config/opencode/skills/shutdown/SKILL.md ✅
- project-init：~/.config/opencode/skills/project-init/SKILL.md ✅
- opencode.json 權限：permission.skill 三項 allow 已設定 ✅
- 重啟 OpenCode：已完成 ✅
- 驗證 1／技能清單：三個技能都掃到 ✅
- 驗證 2／說「開工」：有正常回報摘要 ✅
- 驗證 3／說「初始化專案」：AGENTS.md（大寫）＋ handoff.md 已建立 ✅

For items that did not pass, use ⚠️ or ❌ and explain the reason.

Common issues

Issue	Solution
The skill does not appear in the available list	①The filename must beall uppercase `SKILL.md` ②The folder name must match the frontmatter's `name` ③The topmost `---` must not have blank lines or extra text before or after it ④OpenCode was not restarted
Saying "start work" has no effect	Fully close OpenCode and open it again; if it still does not work, check `opencode.json` 's `permission.skill` to see whether it is written correctly
The SKILL.md that was written in has an extra ```	at the beginning; the outer fence markers are for the quick-start guide's formatting, do not write them into the file. The file's first line must be `---`
On Mac/Linux, the Agent says it cannot find the project blueprint	Check whether the filename was written in lowercase `agents.md`。it must be uppercase `AGENTS.md`—Windows is case-insensitive so the problem is not visible, but Mac/Linux will simply fail to read it
"Initialize project" skipped L2	`gh auth status` did not pass. First do the quick-start guide 07-github
"Initialize project" skipped L3	This computer doesn't have Obsidian MCP. Do the quick-start pack first 04-obsidian, or later on another computer say "build the third level"
Running git in a cloud drive folder produces write errors	`git config windows.appendAtomically false`(a known pitfall with Windows + cloud drives)
Can two computers work on the same project at the same time?	Not recommended—cloud drives will create "conflict copies." The start-work skill shows which computer and time last finished work, helping you avoid it