diff --git a/AGENTS.md b/AGENTS.md
index 2b45841..d0d76cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # jsc-log — 給 AI 助理的指引
 
-本 repo 是 jsc 技能組的 `log` domain（工作日誌與技能使用統計，寫入 `LOG_{HASH}` wiki 頁），Claude Code / Codex / Copilot / Antigravity / Kiro 都能安裝使用。
+本 repo 是 jsc 技能組的 `log` domain（工作日誌、技能使用統計與教訓紀錄，寫入 `LOG_{HASH}`、`LEARN_{HASH}` wiki 頁），Claude Code / Codex / Copilot / Antigravity / Kiro 都能安裝使用。
 
 ## 規則
 
diff --git a/README.md b/README.md
index 2020976..10e11a6 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # jsc-log — 工作日誌與統計
 
-jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），並統計技能使用次數與呼叫鏈次數。
+jsc 技能組的 log domain：工作完成後把十項資訊寫入 wiki 日誌頁（`LOG_{HASH}`，`HASH` 依共享規則計算；首碼若是數字或 `A`／`B`／`C`，改成 `H` 加上原前 7 碼；頁內仍按工作週週五整理），統計技能使用次數與呼叫鏈次數，並把技能執行的教訓記到 `LEARN_{HASH}`，供下次執行前查閱。
 
 ## 安裝、更新、移除
 
@@ -37,6 +37,10 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安
 
 統計本技能組各技能的使用次數與呼叫鏈使用次數，資料來源為 jsc-hooks 記錄的 `skills.jsonl` 與 `chains.jsonl`。
 
+### `learn`
+
+技能執行後把教訓（日期、技能、CLI、情境、教訓、下次做法）附加到 `LEARN_{HASH}` 並更新 `LEARN_CONTENTS`；技能執行前查閱同兩頁，套用相符的「下次做法」。
+
 <!-- JSC-SKILLS:END -->
 
 ## 範本
@@ -45,10 +49,12 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安
 | --- | --- |
 | `templates/log-entry.md` | 單筆工作日誌（十欄位） |
 | `templates/log-contents.md` | 日誌目錄 `LOG_CONTENTS` |
+| `templates/learn-page.md` | 教訓紀錄頁 `LEARN_{HASH}`（六欄表格，逐列附加） |
+| `templates/learn-contents.md` | 教訓目錄 `LEARN_CONTENTS` |
 
 ## 環境變數
 
-Wiki 位置：`JSC_WIKI_REPO_LOG`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。
+Wiki 位置：日誌頁用 `JSC_WIKI_REPO_LOG`、教訓頁用 `JSC_WIKI_REPO_LEARN`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。先讀目前 shell 繼承的環境變數，缺值才詢問。
 
 ## 相關 domain