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）。

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。這時可以請 Gemini 把排好的 HTML 檔交給你，再參考〈在自己的電腦上建置 PDF〉轉成 PDF。

📖 官方說明：建立及管理技能、使用 Gemini Spark

Claude Code

把 skill 資料夾複製到個人的 skills 目錄：

git clone https://github.com/xamjiang/handout-remake.git
cp -R handout-remake/skills/handout-remake ~/.claude/skills/

只想在某個專案裡使用的話，改為複製到該專案的 .claude/skills/。

📖 官方說明：Skills – Claude Code Docs

Codex

複製到 Codex 的 skills 目錄：

git clone https://github.com/xamjiang/handout-remake.git
cp -R handout-remake/skills/handout-remake ~/.codex/skills/

只想在某個專案裡使用的話，改為複製到該專案的 .agents/skills/。

📖 官方說明：Agent Skills – Codex

ChatGPT

ChatGPT 的 skill 在側邊欄的 Plugins → Skills 分頁管理。這個平台還沒實測，可以先試著上傳 handout-remake.zip，詳細的安裝方式請以官方說明為準。

📖 官方說明：Skills in ChatGPT

在自己的電腦上執行時：安裝相依工具

Claude Code 與 Codex 會在你的電腦上建置 PDF，所以要先安裝下列工具。Cowork 與 Claude.ai 在雲端沙箱執行，可以跳過這一步。

| 工具 | 用途 | 必要性 | | ------------------------------------- | ------------------------------- | ------------------- | | Node.js 18 以上 | 執行建置腳本 | 必要 | | Playwright 與 Chromium | 把 HTML 轉成 PDF | 必要 | | poppler | 讀取 PDF 文字、轉縮圖、檢查字型 | 必要 | | LibreOffice | 把 PPT 轉成 PDF | 教材是 PPT 時才需要 |

macOS 可以用 Homebrew 安裝：

brew install node poppler
brew install --cask libreoffice          # 教材是 PPT 時才需要
npx playwright install chromium          # 下載 Playwright 使用的瀏覽器

[!TIP]

不想安裝 LibreOffice 的話，可以先在 PowerPoint 或 Keynote 裡把投影片匯出成 PDF，再交給 AI。

在自己的電腦上建置 PDF

如果平台只能給你 HTML 檔（例如 Gemini Spark），可以在自己的電腦上轉成 PDF。需要先安裝 Node.js 18 以上。

git clone https://github.com/xamjiang/handout-remake.git
mkdir handout && cd handout
cp ../handout-remake/skills/handout-remake/assets/* ../handout-remake/skills/handout-remake/scripts/build.mjs .
npm install && npm i playwright && npx playwright install chromium

把 AI 給你的 HTML 檔放進 handout 資料夾，然後執行：

node build.mjs 講義.html 講義.pdf

畫面上會列出每一頁的剩餘空間。如果出現「溢出」，代表那一頁內容太多，請 AI 重新分頁後再建置一次。

---

製作第一份講義

步驟 1：準備教材

把投影片、PDF 或筆記準備好。一份講義只教一個小節，大約對應 6–12 張投影片，成品約 12–20 頁。

[!TIP]

教材很長的話，直接指定頁碼範圍，例如「第 47–60 頁」。章節太長時，AI 也會自動拆成「上」「下」兩份，並告訴你這份涵蓋到哪裡。

步驟 2：交給 AI

上傳教材，然後用一句話說出你要什麼。不需要特別提到 skill 的名稱，AI 會自己判斷要不要使用。

幫我把這份投影片的 1.10 節做成講義

把第 2 章 p.37–46 整理成好讀版，我下週要小考

這是計算機組織第 1 章，幫我整理 Amdahl 定律那一段

步驟 3：等待製作完成

AI 會依序完成這些事，過程中不需要你介入：

1. 把每一頁教材轉成文字與縮圖，並實際看過每一頁（公式和圖常常只存在圖片裡）。 2. 決定範圍，把內容切成 3–6 個段落，每段只講一個概念。 3. 撰寫內容、繪製圖解、排版。 4. 建置 PDF，並修正所有超出版面的頁面。 5. 逐頁檢查成品，並用程式驗算每一題的數字。

步驟 4：閱讀 AI 的回覆

完成後，AI 會附上 PDF，並用一兩句話說明：

• 這份講義涵蓋投影片的哪些頁。
• 有沒有不確定或自行補充的地方，例如投影片疑似有錯、或為了說清楚而加入的例子。

[!IMPORTANT]

請留意 AI 標出的不確定之處，有疑問時以課本和老師的說法為準。

步驟 5：傳到 iPad

用 AirDrop 或 iCloud 雲碟把 PDF 傳到 iPad，再用 GoodNotes、Notability 或內建的「檔案」App 開啟，就可以直接在書寫區作答。

---

了解講義的結構

每份講義都由幾種固定的頁面組成，順序也固定，讀過一份之後，之後的每一份都知道去哪裡找什麼。

節首頁與概念頁

節首頁：一句話說出這節在問什麼，列出讀完之後能做到的事，以及對應的投影片頁碼、閱讀時間與先備知識。	概念頁：從生活情境開始，帶出術語與中英對照，再用圖解和公式說明。整頁最關鍵的一句話會用螢光標出。

例題頁

每一題都先列出已知、要求、想法，再用編號步驟一步一步解，每一步都有一句小標說明在做什麼。 最後一步固定是檢查答案合不合理，養成驗算的習慣。 投影片上原有的例題會優先採用，並標明出處頁碼。

練習頁與解答頁

練習題分成基本、觀念、變化、綜合四種層次，每頁最多三題，每題都有點陣書寫區。解答一定在練習的下一頁：先給出最終答案，再給完整步驟，頁尾的「寫錯了？回頭看這裡」會告訴你該回去看哪一頁。

圖解

函數曲線與「動手做」：附上可以自己執行的程式碼，親眼看到概念的結果。	結構與流程圖：把每一步的變化並排畫出來，比文字說明更容易追蹤。

所有圖解都使用同一套色盤，同一個顏色在整份講義裡只代表一件事，而且和公式裡的色塊對應。圖解是向量繪製，放大後依然清晰：

複習頁

每份講義的最後依序是： 本節重點：每個段落濃縮成一句話 公式一覽：考前快速複習用 自我檢查：可以勾選的能力清單 術語對照：中文、英文與一句話解釋 下一節預告

---

自訂講義

在對話中調整

最簡單的方式是直接在對話中告訴 AI，例如：

練習題多一點，每個段落後面都放一頁

這份不需要「動手做」的段落

我已經學過微積分，基礎的部分可以講快一點

修改 skill 的預設值

想讓每一份講義都套用你的偏好，可以直接修改 skill 的檔案：

| 想改的東西 | 修改的位置 | | -------------------- | --------------------------------------------------------------------------------------------- | | 讀者程度、語言、偏好 | SKILL.md 開頭的「讀者設定」 | | 教學順序、練習數量 | SKILL.md 的〈教學規則〉 | | 顏色、字級、間距 | assets/handout.css 開頭的 CSS 變數 | | iPad 尺寸 | assets/handout.css 的 --page-w、--page-h、@page，以及 scripts/build.mjs 的 viewport |

[!NOTE]

修改後，Cowork、Claude.ai 與 Gemini 需要重新打包再上傳一次。在 repo 根目錄執行 tools/package.sh，就會在 dist/ 產生兩種封包（只會打包已 commit 的內容）。

---

疑難排解

npm i playwright
npx playwright install chromium

---

使用須知

• AI 可能出錯：skill 會要求 AI 驗算所有數字並標出不確定的地方，但請仍以課本與老師的說法為準。
• 尊重著作權：上課教材的著作權屬於老師或出版社。用這個 skill 製作的講義請只供個人學習使用，不要公開散布。

專案結構

.
├── README.md
├── LICENSE
├── docs/images/                  README 使用的圖片
├── tools/package.sh              打包 Claude 版與 Gemini 版的 zip
└── skills/handout-remake/        skill 本體
    ├── SKILL.md                  流程與規則
    ├── assets/
    │   ├── handout.css           樣式與色盤
    │   ├── template.html         每種頁面的範本
    │   └── package.json          字型與 KaTeX 的版本
    └── scripts/
        └── build.mjs             建置、溢出檢查、輸出 PDF

參與貢獻

歡迎開 Issue 回報問題或分享你的使用結果。送出 Pull Request 時，commit 訊息請遵守 Conventional Commits，例如：

feat(skill): 新增 13 吋 iPad 的版面
fix(build): 修正 KaTeX 巨集的顏色
docs: 補充 Codex 的安裝步驟

授權

本專案以 MIT License 授權。README 中的範例截圖取自作者自己的課程講義，僅供展示。

平台 logo 取自 Lobe Icons（MIT License），商標權屬於各自的公司，在此僅用來標示相容的平台。