handout-remake README

The project's README from github.com/xamjiang/handout-remake. As one markdown file: README.md.

四頁講義範例:節首頁、概念頁、例題頁、練習頁

深色講義

把上課的投影片、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 先讀懂教材,再依照初學者需要的順序重新教一次,最後排成固定格式的講義。

流程:丟入教材 → AI 重新教一次 → 排版與自動檢查 → 在 iPad 上讀寫

每一份講義都有這些特點:


支援平台

這個 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 的使用條件:

安裝 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。這時可以請 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 開啟,就可以直接在書寫區作答。


了解講義的結構

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

節首頁與概念頁

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

例題頁

例題頁

每一題都先列出已知、要求、想法,再用編號步驟一步一步解,每一步都有一句小標說明在做什麼。

最後一步固定是檢查答案合不合理,養成驗算的習慣。

投影片上原有的例題會優先採用,並標明出處頁碼。

練習頁與解答頁

左邊是練習頁,右邊是解答頁

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

圖解

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

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

圖解放大後的細節

複習頁

複習頁

每份講義的最後依序是:

  1. 本節重點:每個段落濃縮成一句話
  2. 公式一覽:考前快速複習用
  3. 自我檢查:可以勾選的能力清單
  4. 術語對照:中文、英文與一句話解釋
  5. 下一節預告

自訂講義

在對話中調整

最簡單的方式是直接在對話中告訴 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 的內容)。


疑難排解

出現「找不到 playwright」

在講義的工作資料夾裡安裝 Playwright 與它使用的瀏覽器:

npm i playwright
npx playwright install chromium
PPT 檔讀不進去

轉換 PPT 需要 LibreOffice。可以安裝 LibreOffice,或先在 PowerPoint、Keynote 裡把投影片匯出成 PDF 再上傳。

PDF 有內容被截掉

建置腳本會回報每一頁的剩餘空間,AI 應該在交付前修正所有溢出。如果成品仍有被截掉的地方,請告訴 AI 是第幾頁,請它重新分頁。

PDF 裡的字變成方框或模糊

字型必須使用 @fontsource 的靜態字重版本。請確認工作資料夾是用 skill 附的 package.json 安裝套件,不要改用 variable 版本的字型。


使用須知


專案結構

.
├── 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),商標權屬於各自的公司,在此僅用來標示相容的平台。

handout-remake (xamjiang/handout-remake)

Searching Database…

What is this?An Agent Skill that turns lecture slides, PDFs, or notes into dark-mode study handouts sized for an 11-inch iPad. It re-teaches each topic from scratch with real-life analogies, diagrams, worked examples and practice pages, then outputs a fully vector PDF in Traditional Chinese.
Is this a standalone app, or something I add to an AI assistant?It is an Agent Skill package (a SKILL.md file plus assets, not a program you run by itself). You upload or copy it into an AI tool like Claude, Codex, Gemini, or ChatGPT, and the AI invokes it to build the PDF for you.
How do I make my first handout?Download the skill zip from the Releases page, install it in your AI tool's Skills settings, then upload your slides or PDF and simply describe what you want in plain language. You don't even need to name the skill — the AI decides on its own whether to use it.
Do I need to install anything locally to build the PDF?Only if you run it through Claude Code or Codex on your own machine, where you need Node.js 18+, Playwright with Chromium, poppler, and (if your material is a PPT) LibreOffice. Claude Cowork and Claude.ai run in a cloud sandbox, so those don't need any local install.
Does it work the same on every AI platform?No. Claude Cowork, Claude.ai, and ChatGPT Work are confirmed to work well, while Gemini Spark only partly works because its sandboxed scripts can't reach the network to install PDF-building packages, and Gemini's regular chat basically doesn't produce usable output at all.
What does a finished handout look like inside?Each handout has a fixed structure: a section intro page, concept pages built from analogy to formula with a highlighted key sentence, worked examples with numbered reasoning steps, practice pages with a handwriting area whose answer always sits on the next page, and closing review pages with a formula summary and bilingual glossary.
Why is it sized for dark mode and an iPad specifically?Pages are set to the exact portrait screen size of an 11-inch iPad so nothing needs zooming, and the dark background is meant to make long reading and note-taking sessions easier on the eyes.
Can I change the teaching style or visual design?Yes — edit SKILL.md to change reader level, language, or teaching rules, or edit assets/handout.css for colors, fonts and page size. After editing, you need to re-run tools/package.sh to repackage the skill for Cowork, Claude.ai, or Gemini.
What output language does it produce?Currently only Traditional Chinese (Taiwan), regardless of the language of your source slides.
Creator
xamjiang
Size
2.1 MB
Stars
166
Age
12d
Commits · 90 Days