| name | learn-tw |
| description | Generate a personalized learning document — FOR[yourname].md explaining a project in plain, engaging Taiwan Traditional Chinese, plus a styled HTML 好讀版 (FOR[yourname].html) when the markdown-to-html skill is installed. Use when the user wants a learning doc for a codebase ("help me understand this project", "write a FOR[name].md"), or a 好讀版 / readable HTML learning doc to read or share. |
| license | MIT |
Learn TW Skill
Create an engaging, personalized learning document that explains a project in plain language. Two deliverables, one source:
FOR[username].md — the primary deliverable; always ships. [username] is the user's name.FOR[username].html — the 好讀版, generated from the .md by the optional markdown-to-html skill (see 〈Generating the HTML 好讀版〉). The .md is the single source of truth — the HTML is never hand-written. Skill not installed → skip silently; the .md alone is the deliverable.
Workflow
- 先綁定讀者與目標（見〈讀者與目標〉）——它決定後面每一步深挖哪些子系統。
- Explore codebase structure (
ls, file patterns).
- Read key files (entry points, configs, core modules).
- Identify architecture patterns and tech decisions.
- Note documented bugs/issues in git history and comments.
- Write
FOR[username].md in Taiwan Traditional Chinese, following every rule in the
writing-rule sections below (〈Language Requirements〉 through 〈Document template〉).
Make the first line (H1) a descriptive document title — project name + 學習筆記
(e.g. # fcs-forensics 學習筆記), NOT the filename; it becomes the HTML page title.
Done when: all 7 sections present, every「為什麼」traceable per〈證據紀律〉, every
diagram follows〈Diagrams〉.
- Save into a timestamped topic folder — never loose in the project root.
Path:
<主題>-<時間戳>/FOR[username].md.
<主題> — filesystem-safe slug of the subject, usually the repo name: lowercase, spaces → -.<時間戳> — read the real clock, never guess it: date +%Y%m%d-%H%M (e.g. 20260707-1432).- The Write step creates the folder (no
mkdir). Each run is a self-contained snapshot;
re-running never overwrites an earlier one (folders accumulate — that is the point).
- Generate the HTML 好讀版 per 〈Generating the HTML 好讀版〉.
The 7 sections
- 專案概述 (Project Overview) — what the project does, who it's for, the problem it solves
- 技術架構 (Technical Architecture) — system design, data flow, key components and how they connect
- 程式碼結構 (Codebase Structure) — directory layout, important files, where to find things
- 技術選型 (Technology Stack) — what's used and why it beat the alternatives
- 設計決策 (Design Decisions) — the "why" behind architectural choices, trade-offs considered
- 學習心得 (Lessons Learned) — bugs encountered, pitfalls to avoid, best practices discovered
- 工程師思維 (How Good Engineers Think) — patterns, mental models, debugging approaches used
讀者與目標（先綁定，再下筆）
一份只把檔名個人化的文件，對所有讀者都長一樣，往往太抽象。下筆前先確立
這份文件為誰而寫、讀完他要能做什麼：
- 使用者沒講就問（或從他的指令合理推斷）：誰要讀？讀完要能做什麼——
onboarding？改某個子系統？評估技術選型？交接？
- 把它寫成開場框定：放在 H1 標題下、
專案概述 之前，用一句引言（>）
或一行粗體交代清楚。不要用 H2，以免占用七大章節的編號。
- 讓它真的影響內容，而不只是裝飾：目標是「改 FCS parser」→
程式碼結構
與設計決策就聚焦那個子系統，而非均勻導覽；讀者是資深工程師→多談 trade-off，
是新手→先給定位與全貌。同一個專案，給不同讀者就是兩份不同的文件。
Language Requirements
Output MUST be in Taiwan Traditional Chinese (繁體中文), using Taiwan local terminology:
| Taiwan Term (Use) | Mainland Term (Avoid) |
|---|
| 程式碼 | 代碼 |
| 資料庫 | 數據庫 |
| 資料 | 數據 |
| 軟體 | 軟件 |
| 硬體 | 硬件 |
| 網路 | 網絡 |
| 伺服器 | 服務器 |
| 記憶體 | 內存 |
| 物件 | 對象 |
| 變數 | 變量 |
| 迴圈 | 循環 |
| 陣列 | 數組 |
| 函式 | 函數 |
| 檔案 | 文件 |
| 視窗 | 窗口 |
| 滑鼠 | 鼠標 |
| 列印 | 打印 |
Writing Style
- Engaging, not boring — write like explaining to a curious friend, not a textbook
- Use analogies — compare complex concepts to everyday things
- Include anecdotes — "We tried X, it broke because Y, so we did Z"
- Be specific — real file names, real error messages, real solutions
- Show the journey — include the mistakes, not just the final answer
- 論斷要有出處 — 見〈證據紀律〉
- Highlight key insights — for an important takeaway, write a
★ Insight ───── block:
a line ★ Insight followed by box-drawing rules (─), then the points, then a closing
─ rule line. The 好讀版 renders it as a styled「★ 重點」callout box.
證據紀律（論斷要有出處）
把「絕不憑空臆測」當鐵則——這是 learn-tw 最容易出錯的地方（自信地編造設計理由）。
設計決策與學習心得裡每個「為什麼」都要能追溯到真實證據：
- 連回穩定名稱——檔名、
Class.method、路由、commit、git log、程式碼註解——
不要用 file:line（位置會失效，名稱會跟著程式碼走）。
- 找不到佐證的因果或歷史，就標明「（推測，未在程式碼／git 找到佐證）」，
不要把猜測寫成事實。一句沒有來源的「我們當初選 X 是因為 Y」比留白更糟。
自我檢核（retrieval practice）
被動讀完不等於學會；從記憶主動提取才建立長期記憶。每個主要章節結尾可選放
一題「自我檢核」，讓讀者先答再展開對照。寫成 <details> 折疊區塊：
<details class="self-check" markdown="1">
<summary>自我檢核：資料從讀取到報告，經過哪幾層？</summary>
> 先自己想，再展開對照。
讀取 FCS → 解析 TEXT/DATA → 計算統計量 → 產生報告，共四層。
</details>
格式要點（務必照做，否則算繪會壞）：
<summary> 後空一行，內層答案前後也各空一行——否則 GitHub/GitLab 不會把
答案當 Markdown 算繪。class="self-check" 與 markdown="1" 兩者都要：前者觸發編輯風樣式，後者讓內層
答案被當 Markdown 解析（而非一坨原始 HTML）。- 一節最多一題，問「能否重述／推導」而非背名詞；難度適中即可。
- 算繪行為：好讀版是可折疊卡片（收合顯示「？」、展開顯示「✓」，列印時自動
全部展開）；
.md 在 GitHub/GitLab 上是原生折疊。
附錄：詞彙表（Glossary，選用）
當專案有自己的術語時，在文件最後加一個詞彙表，並全文一律遵守——它是這份
文件的權威用語，順便降低不熟領域讀者的門檻。這是把上方〈Language Requirements〉的
用詞表，從中文用語延伸到專案領域。格式示意：
| 詞彙 | 定義（一兩句，講它是什麼） | 避免混用 |
|---|
| Gating | 在散點圖／直方圖上圈選目標細胞族群的操作 | 篩選、過濾 |
| Keyring | 作業系統的金鑰串／憑證保管庫（如 macOS Keychain） | 環境變數、設定檔 |
規則：只收真正需要釐清的詞；同義詞挑一個當標準、其餘列入「避免混用」；定義裡
也優先使用詞彙表自己的詞。沒有領域術語的專案就不必加這個附錄。
Diagrams: use Mermaid
Draw diagrams as ```mermaid fenced code blocks with Chinese labels written
directly — Mermaid renders vector diagrams, so CJK alignment is never a problem.
The 好讀版 renders them with mermaid.js (loaded from a CDN at view time; the diagram
text is rendered locally and never sent anywhere — safe for internal architecture);
the .md renders natively on GitHub/GitLab, and in a bare terminal the Mermaid
source is still legible.
-
flowchart for pipelines/architecture, sequenceDiagram for interactions.
Keep labels short; Chinese is fine.
flowchart LR
A[讀取 FCS] --> B[解析 TEXT/DATA]
B --> C[計算統計量]
C --> D[產生報告]
-
Directory / file trees → a Mermaid flowchart LR (parent → child, so it reads
like an indented tree). Put a node's name and its description on separate lines
with <br/>:
flowchart LR
r["project/"] --> s["src/<br/>主要程式碼"]
s --> c["core/<br/>核心邏輯"]
r --> t["tests/<br/>測試"]
-
CJK never goes inside an ASCII / box-drawing diagram. CJK glyphs are
double-width, so a frame built from ┌ ─ ┐ │ └ ┘ / +--+ splits open the
moment a label is Chinese — in every renderer and font. Anything with a real shape
(boxes, layers, quadrants, trees) → Mermaid or a Markdown table. A plain ASCII
block is fine only while its content stays pure ASCII (a -> b -> c, code
snippets, ASCII-labelled charts).
Generating the HTML 好讀版
Markdown → HTML is a pure deterministic transform, delegated to the optional
markdown-to-html skill — learn-tw bundles no converter, and the HTML is never
hand-written.
Resolve {MARKDOWN_TO_HTML} to the first of these where scripts/md_to_html.py
exists: .claude/skills/markdown-to-html/ (project), then
~/.claude/skills/markdown-to-html/ (user). No match → the skill is not installed;
skip this step silently and ship only the .md.
uv run --project {MARKDOWN_TO_HTML} python {MARKDOWN_TO_HTML}/scripts/md_to_html.py <主題>-<時間戳>/FOR[username].md
The converter writes FOR[username].html as a sibling in the same folder (no output
path needed) and prints the absolute paths of both files plus a file:// link —
relay those to the user verbatim so they can open the .html directly.
The output is a single self-contained editorial page tuned for long-form Chinese
reading — 書卷感 typography, a Chinese font switcher, a scroll-spy TOC, a light/dark
theme, Mermaid rendered as vectors, a print stylesheet; web fonts and Mermaid load
from a CDN at view time and degrade gracefully offline. The authoritative feature
list lives in the markdown-to-html skill.
Document template
# [專案名稱] 學習筆記
## 專案概述
[用一段話說明這個專案做什麼、給誰用、解決什麼問題]
---
## 技術架構
[系統設計、資料流、關鍵元件如何串接]
```mermaid
flowchart LR
A[讀取輸入] --> B[核心處理]
B --> C[輸出結果]
想像這個系統像是...（比喻）
程式碼結構
flowchart LR
r["project/"] --> s["src/<br/>主要程式碼"]
s --> c["core/<br/>核心邏輯"]
s --> u["utils/<br/>工具函式"]
r --> t["tests/<br/>測試"]
r --> cfg["config/<br/>設定檔"]
重要檔案：
src/main.ts - 進入點src/core/engine.ts - 核心引擎
技術選型
設計決策
決策 1：[標題]
問題： [遇到什麼問題]
選項：
決定： 選 A，因為...
學習心得
踩過的坑
問題： [錯誤訊息或現象]
原因： [為什麼會這樣]
解法： [怎麼修的]
學到： [以後要注意什麼]
最佳實踐
工程師思維
[這個專案展現的設計模式、除錯方法、思考方式]
