xamjiang / handout-remake

# 深色講義
把上課的投影片、PDF 或筆記交給 AI，製作適合在平板裝置長時間閱讀、理解的教學講義。
> **English** — An Agent Skill that turns lecture slides into dark-mode, pen-ready study handouts for the 11-inch iPad. It re-teaches each topic from scratch with diagrams, worked examples and practice pages, then builds a fully vector PDF. Output language: Traditional Chinese (Taiwan).
---
## 概覽
老師的投影片重點很密、步驟常常省略、公式和圖只存在圖片裡。這個 skill 讓 AI 先讀懂教材，再**依照初學者需要的順序重新教一次**，最後排成固定格式的講義。
每一份講義都有這些特點：
- **從零講起**：每個概念依「生活情境 → 白話定義 → 圖解 → 公式 → 例題」的順序展開，術語附英文對照，方便對照課本與考卷。
- **為 iPad 設計**：頁面尺寸就是 11 吋 iPad 直向的螢幕大小，不用縮放；深色底色適合長時間閱讀。
- **可以直接作答**：練習題附點陣書寫區，解答固定在下一頁，寫完翻頁就能對答案。
- **品質有把關**：建置時自動檢查每頁有沒有內容超出版面；例題與解答的數字會用程式重算一次。
- **全向量 PDF**：文字、公式、圖解都是向量，放到最大也不會糊。
---
## 支援平台
這個 skill 使用 Agent Skills 開放格式，理論上支援所有能讀取 `SKILL.md` 的 AI 工具。製作過程需要執行 Node.js 與無頭瀏覽器，所以平台必須能執行程式碼，才能輸出 PDF。
| 平台 | 狀態 | 說明 |
| --- | --- | --- |
| Claude Cowork | ✅ 已實測（Cowork 功能已與 Chat 合併） | 範例截圖都是用 Cowork 製作的，實測 Opus 5.5 mediu、Sonnet 5.5 high 效果都很好。 |
| Claude.ai | ✅ 已實測 | 需要開啟程式碼執行功能 |
| Claude Code | 🧪 待測試 | 在你的電腦上執行，需要先安裝相依工具 |
| Codex | 🧪 待測試 | 在你的電腦上執行，需要先安裝相依工具 |
| Gemini Spark | ⚠️ 部分可用 | 內容可以正常產出，但受限於 Gemini 模型，效果堪用但不多。 |
| Gemini 聊天室 | ✋ 先不要 ❌ | 內容無法正常產出，效果相當炸裂，可愛龍還是可愛龍。 |
| ChatGPT Work | ✅ 已實測 | 使用 GPT-6 Astra high 可做到 Opus 5.5 八成效果，會有圖表文字些微跑版的問題。 |
> [!NOTE]
> 如果在各個平台上成功或失敗，歡迎開 Issue 告訴我。
---
## 安裝 skill
**點選你使用的平台**，直接跳到對應的教學：
 Claude Cowork・Claude.ai 
 Gemini Gemini Spark 
 ChatGPT ChatGPT Work 
 Claude Code 終端機 
 Codex 終端機 
Claude、Gemini 與 ChatGPT 需要從 Releases 頁面下載封包，請下載對應的那一個：
| 檔案 | 適用平台 |
| --------------------------- | --------------------------------- |
| `handout-remake.zip` | Claude Cowork、Claude.ai、ChatGPT |
| `handout-remake-gemini.zip` | Google Gemini（含 Gemini Spark） |
### Claude Cowork 與 Claude.ai
1. 到 Releases 頁面下載最新的 `handout-remake.zip`。
2. 開啟 Claude 的**設定**，在 **Capabilities** 裡確認**程式碼執行**（Code execution）已開啟。
3. 在 **Skills** 區塊選擇 **Upload skill**，上傳剛剛下載的 zip 檔。
4. 確認清單中出現 `handout-remake`，並且是開啟狀態。
> [!NOTE]
> Cowork 需要付費方案。設定頁面的名稱可能隨 Claude 更新而調整，以官方說明為準。
📖 官方說明：Use Skills in Claude、Getting started with Cowork
### Google Gemini Spark
Gemini 的 skill 統一在 Gemini 網頁版的設定裡管理，裝好之後，一般對話與 Gemini Spark 都能使用。
**開始之前**，請確認你符合 Gemini Spark 的使用條件：
- 訂閱 **Google AI Pro 或 Ultra**。
- 用**個人 Google 帳號**登入。
- 年滿 **18 歲**，並且開啟了「**保留活動記錄**」（Keep Activity）。
**安裝 skill**
1. 到 Releases 頁面下載最新的 **`handout-remake-gemini.zip`**。
2. 用電腦瀏覽器開啟 gemini.google.com（或 Mac 版 Gemini App），進入**設定 → 技能**（Skills）。
3. 選擇上傳檔案，上傳剛剛下載的 zip 檔。
4. 確認清單中出現 `handout-remake`，並且是啟用狀態。
> [!IMPORTANT]
> 請上傳 **`handout-remake-gemini.zip`**，不要用 Claude 版的 `handout-remake.zip`。Gemini 規定 `SKILL.md` 必須放在 zip 的最外層，也不接受 `.css`、`.html`、`.mjs` 這類副檔名，Claude 版的封包會上傳失敗。Gemini 版已經把這些檔案改成 `.txt`，AI 使用時會自動改回來。
**在 Gemini Spark 中使用**
1. 在 Gemini Spark 開一個新任務，上傳你的投影片或 PDF。
2. 在輸入框輸入 `/`，從清單中選擇 `handout-remake`。
3. 接著說明你要什麼，例如「幫我把第 2 章 p.37–46 做成講義」（也可以什麼都不說）。
> [!WARNING]
> 根據 Google 的官方說明，skill 裡的腳本不能連上網路，所以 Gemini Spark 可能無法安裝建置 PDF 所需的套件。目前實測的結果是**講義內容可以產出**，但不一定能得到排好版的 PDF。這時可以請 Gem