llm-wiki-lint

Use when the user wants to lint a repo following the Karpathy LLM Wiki pattern (raw/ + wiki/ + SCHEMA.md / index.md / log.md). The skill detects path, scans wiki pages + schema layer, reports frontmat

SKILL.md

GitHub

llm-wiki-lint — Karpathy LLM Wiki 三層健檢

You are a documentation auditor for repos following the Karpathy LLM Wiki pattern. Scan the three layers (raw/ + wiki/ + SCHEMA.md / index.md / log.md), surface drift and gaps, report — then fix only with explicit user approval.

CRITICAL — 兩段式契約:

  • Phase 1(report)純 read-only。掃描期間任何「順手補一下 frontmatter」「順手更新 index」都是違規。
  • Phase 2(fix)必須等 user 對報告明確點頭(「修」「fix」「都修掉」)才啟動。User 只說「跑 lint」= 只做 Phase 1。

跟 memory-lint 差異:

  • memory-lint → Claude memory 目錄(feedback / user profile / project,prefix-based)
  • llm-wiki-lint → LLM Wiki repo(wiki/ 主題頁 + frontmatter + raw source traceability + index 一致性)

Step 1: Detect wiki repo path

依序嘗試,命中第一個就用:

順序 來源 條件
1 $ARGUMENTS 第一個位置參數 使用者明確傳入,最優先
2 環境變數 $WIKI_REPO_DIR export 過
3 當前工作目錄 $PWD 含 SCHEMA.md + wiki/ 子目錄
4 — 都找不到 → 停止,告訴 user「偵測不到 wiki repo」,不要瞎猜

決定路徑後,先驗證結構:

ls "$WIKI_PATH/SCHEMA.md" "$WIKI_PATH/wiki/" 2>/dev/null
ls "$WIKI_PATH/index.md" 2>/dev/null || echo "WARN: index.md 不存在"
ls "$WIKI_PATH/log.md" 2>/dev/null   || echo "WARN: log.md 不存在"
  • SCHEMA.md 或 wiki/ 任一缺 → fatal,停止 lint
  • index.md / log.md 缺 → warning,繼續 lint 並在報告建議新建

Step 1b: 載入 repo 自有規約(lint 的 source of truth)

不要硬編碼 Karpathy 預設值 — 以目標 repo 自己的宣告為準:

規約 來源 fallback
type allow-list SCHEMA.md §Type 分類(含本地擴充) Karpathy 5 類(overview/entity/concept/comparison/synthesis)+ 報告註明 SCHEMA 未宣告
frontmatter 必備欄位 SCHEMA.md §Frontmatter 欄位 title / type / last_updated / sources
lint 後是否 append log.md SCHEMA.md §Lint 節奏 不 append
額外文件風格規則(如「body 禁 date marker」) repo 的 CLAUDE.md / docs/ 規則檔(如有) 跳過此項檢查

Step 2: Scan & lint(Phase 1 — read-only)

Step 2a: 掃描範圍

find "$WIKI_PATH/wiki" -maxdepth 1 -name '*.md' -type f
find "$WIKI_PATH/wiki" -mindepth 1 -maxdepth 1 -type d   # 子目錄偵測 — 上面那條只看 .md,抓不到目錄

包含:

  • <path>/wiki/*.md — 所有主題頁(第二條指令找到子目錄時列出並在報告標註,等 user 決定是否納入)
  • <path>/SCHEMA.md / index.md / log.md — schema 層
  • <path>/raw/** — 存在性檢查(gitignored,本地才看得到)

跳過:<path>/journal/、<path>/drafts/、<path>/scripts/(非 wiki 一部分)

工具紀律:解析 frontmatter / 比對清單一律用 python3 stdlib(re + glob),不要依賴 yq / jq(目標機器不保證裝了)。

Step 2b: Severity decision

嚴重度 含義 範例
🔴 Error 結構壞了或宣告與實況矛盾 缺必備 frontmatter 欄位、index 列出檔案不存在、body 連結指向已刪頁、SCHEMA.md 數字錯
🟡 Warning 沒壞但有腐臭味,user 應該 review last_updated 漂移、orphan page、stale claim、index 摘要與頁面內容矛盾
🔵 Info 啟發式提示,可選處理 缺 cross-ref、可能的 missing topic

不確定時就降一級(warning → info)。禁止把推測寫成 error。

Step 2c: Frontmatter 完整性

每個 wiki/*.md 開頭應有 YAML frontmatter,必備欄位以 Step 1b 載入的清單為準:

欄位 規則 缺失等級
title 主題名(string) 🔴 Error
type 在 Step 1b 載入的 allow-list 內 🔴 Error(缺欄位 / 不在 allow-list)
last_updated YYYY-MM-DD 🔴 Error(缺)/ 🟡 Warning(格式錯)
sources list,指向 raw/ 或外部來源 🔴 Error(缺欄位)/ 🟡 Warning(空 list — 見 Step 2i)
python3 - <<'EOF'
import re, glob
for f in sorted(glob.glob("wiki/*.md")):
    s = open(f, encoding="utf-8-sig").read()   # utf-8-sig 吃掉 BOM;\r?\n 容忍 CRLF(Windows 編輯過的檔)
    m = re.match(r"^---\r?\n(.*?)\r?\n---\r?\n", s, re.S)
    if not m: print(f"NO-FRONTMATTER {f}"); continue
    fm = m.group(1)
    for field in ("title", "type", "last_updated", "sources"):
        if not re.search(rf"^{field}:", fm, re.M): print(f"MISSING {field} {f}")
EOF

Step 2d: Index 一致性

情況 等級
index.md 列出但 wiki/ 下檔案不存在 🔴 Error(missing file)
wiki/ 下檔案存在但 index.md 沒列 🔴 Error(orphan file)
index.md 的 last_updated / type 跟檔案 frontmatter 不一致 🟡 Warning(drift)
index.md 標頭宣稱頁數 ≠ 實際頁數 🔴 Error

Step 2e: Index 摘要 vs 頁面內容矛盾

index 每列通常帶「一句話」摘要。逐列對照該頁當前核心結論 — 摘要還在講已被頁面推翻的舊事實(例:摘要說「服務 X 運行中、不能停」,頁面已改寫成「服務 X 已停用」)→ 🟡 Warning。這是日期 drift 抓不到的:日期可能同步了、摘要忘了改。

Step 2f: Body 連結完整性(in-body link integrity)

掃每頁 body 的兩種站內連結,目標不存在 → 🔴 Error:

  • markdown link:[...](some_page.md) → wiki/some_page.md 必須存在(含連字號 / 大寫 / ./ 前綴 / #anchor 變體)
  • wikilink:[[some_page]] 與別名形式 [[some_page|顯示文字]] → wiki/some_page.md 必須存在

捕捉要寬不要窄 — 斷鏈檢查的失敗模式是「沉默通過」:regex 漏掉的連結形式不會報錯,user 會誤以為全綠。寬鬆捕捉任何 .md 目標,再正規化比對:

python3 - <<'EOF'
import re, glob, os
for f in sorted(glob.glob("wiki/*.md")):
    s = open(f, encoding="utf-8-sig").read()
    for t in re.findall(r"\]\(([^)#\s]+\.md)(?:#[^)]*)?\)", s):
        if t.startswith(("http://", "https://")): continue   # 外部連結不在此檢查
        rel = t[2:] if t.startswith("./") else t
        if not os.path.exists(os.path.join("wiki", rel)): print(f"BROKEN-LINK {f} -> {t}")
    for t in re.findall(r"\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]", s):
        if not os.path.exists(f"wiki/{t.strip()}.md"): print(f"BROKEN-WIKILINK {f} -> {t}")
EOF

Step 2g: Stale claims(陳舊聲明)

條件 等級
git 最後 commit 日 vs frontmatter last_updated 差 > 14 天 🟡 Warning(frontmatter 沒跟上實際改動)
frontmatter last_updated > 60 天 且 type ∈ {overview, synthesis} 🟡 Warning(建議 review)
內文含未完成標記 + last_updated > 30 天 🟡 Warning(可能已有進展沒回寫)

未完成標記的關鍵詞清單跟 wiki 語言對齊(Rule 9):中文 wiki 掃「待 XXX 驗證」「規劃中」「尚未」;英文 wiki 掃 "TBD" / "pending" / "not yet" / "WIP" / "to be verified"。

# git repo 用 commit 日(mtime 在 clone / checkout 後不可靠);非 git repo 才 fallback stat
git -C "$WIKI_PATH" log -1 --format=%cs -- "wiki/<page>.md"

Step 2h: Orphan pages(孤立頁面)

  • 一頁沒有任何其他主題頁連到它(只有 index.md 列出)→ 🟡 Warning
  • index.md 不算入站 ref — index 列出是 Step 2d 的強制要求,每頁都有;若把它當例外,凡通過 2d 的頁面永遠不會是 orphan,本檢查形同虛設

Step 2i: Data gaps(資料缺口)

條件 等級
sources 欄位空 / 指向消失的 raw 檔案 🔴 Error(traceability 斷鏈;raw 可能被搬移過 — 報告附 find raw -iname 找到的新位置候選)
主題頁內文 raw/xxx 路徑 ref → raw/** 實際不存在 🔴 Error(local 才能查)
主題頁 Open questions 段 > 3 個月未解 🟡 Warning

Step 2j: Cross-page contradictions(矛盾)

啟發式(粗略,需人工確認)— 永遠 Warning,不要升 Error:

  • 同一 entity(同一台主機 / 同一服務名)在不同頁描述狀態不一致
  • 同一數字(容量 / 並發數 / 頁數)在不同頁不同
  • Output 必須註明「需人工確認,可能是更新時差」

Step 2k: SCHEMA.md 宣告 vs 實況

情況 等級
SCHEMA.md 說「N 主題頁」但實際 M(N≠M) 🔴 Error
實際使用的 type 不在 SCHEMA 宣告清單(反向也算:宣告了沒人用不報) 🟡 Warning — 修法二選一:頁面改 type,或 SCHEMA 擴充收編(報告兩案並列,user 拍板)

Step 2l: Repo 自有風格規則(Step 1b 有載入才跑)

例:repo 規定「wiki body 不留 date marker(更新/校正註記),事件日期除外」→ 掃 (YYYY-MM-DD 驗證) (校正) 類 pattern → 🟡 Warning。事件本身的日期(「X 月 X 日起」「YYYY-MM-DD 到期」)不算違規 — 逐筆判斷,不確定就標 Info。

Step 2m: Missing topics / cross-refs(啟發式,永遠 Info)

  • index.md 某類別空但其他類別有 → 🔵 Info
  • 頁 A 內文高頻提到頁 B 的主題詞但沒連結 → 🔵 Info

Step 3: 輸出報告(Phase 1 結束點)

繁體中文,固定格式(英文 wiki 才用英文):

# 🔍 LLM Wiki Lint 報告

**掃描目錄:** /path/to/team-wiki
**掃描時間:** YYYY-MM-DD HH:MM
**掃描檔案:** N 個 wiki 頁 + schema 層

## 🔴 Error(建議立即處理)

- [類別] 描述 — 建議動作

## 🟡 Warning(建議 review)

- [類別] 描述

## 🔵 Info(提示,可選處理)

- [類別] 描述

## 🟢 OK(通過)

- Frontmatter 完整性
- ...

## 📊 統計

| Type | 頁數 |
|------|------|
| (依 Step 1b 載入的 allow-list 動態列出實際使用的 type) | N |

**總計:** XX 個 wiki 頁

每個 finding 必須包含:

  • [類別] — Frontmatter / Index / Link / Stale / Orphan / SCHEMA / Contradiction / Style / Data gap
  • 具體檔名 + 行為描述
  • 建議動作(Error 必有,Warning 可有)

報告結尾固定問一句:「要修嗎?修的話哪些(全修 / 只修 Error / 指定項)?」 — 不要替 user 決定。


Step 4: Fix(Phase 2 — 必須 user 明確點頭才跑)

User 對報告回「修」後:

Step 4a: 修機械項

Error + 指定的 Warning,典型:index reconcile(補列 / 砍幽靈列 / 日期同步 / 頁數標頭)、補 frontmatter(從 index 值 + 頁內資料來源段重建)、移除斷鏈、修 sources 路徑、SCHEMA 數字 / type 清單同步。

修不動的(需 user 判斷的內容矛盾、大範圍風格清理)→ 列為 deferred,寫進 LINT entry,不要硬修。

Step 4b: 重跑驗證

Phase 1 同套檢查重跑,機械項應歸零。報告殘留項。

Step 4c: log.md LINT entry

僅當 repo SCHEMA 規定 lint 須留痕(Step 1b 載入)才 append,格式跟著該 repo log.md 既有 entry 走,內容含:findings 分類 + 修了什麼 + deferred 什麼。SCHEMA 沒規定 → 問 user 要不要記。

Step 4d: Commit

跟著目標 repo 的 commit 慣例(有 PR 流程走 PR)。Commit message 描述 lint 範圍 + 修正類別,不逐項展開。


範例輸出(虛構 repo,僅示意格式)

# 🔍 LLM Wiki Lint 報告

**掃描目錄:** /path/to/team-wiki
**掃描時間:** 2026-01-15 14:20
**掃描檔案:** 17 個 wiki 頁 + SCHEMA.md + index.md + log.md

## 🔴 Error

- [Frontmatter] `wiki/cheatsheet.md` 缺 `sources` 欄位 → 補上來源連結
- [Index] `index.md` 列 `wiki/old_topic.md` 但檔案不存在 → 移除 index 對應行
- [Link] `wiki/onboarding.md` 連到 `data_model.md`(頁已刪)→ 移除或改指現行頁
- [SCHEMA] SCHEMA.md 宣告「15 主題頁」但實際 17 → 更新 SCHEMA.md

## 🟡 Warning

- [Stale] `wiki/load_test.md` last_updated 2026-01-04,但 git 最後 commit 2026-01-13 → 更新 frontmatter
- [Index 摘要] `wiki/service_inventory.md` 摘要寫「服務 X 運行中」,頁面現況已改「服務 X 已停用」→ 改寫摘要
- [Contradiction] `db-host-01` 在 topology.md 寫「gateway + DB」,在 architecture.md 寫「僅 DB」→ 同步描述(需人工確認,可能是更新時差)

## 🔵 Info

- [Cross-ref] `wiki/security.md` 提到「訊息佇列」9 次但沒連 `mq_pipeline.md` → 考慮補連結

## 🟢 OK

- Body 連結完整性:除 1 項均 OK
- Type 分類:全部在 SCHEMA allow-list 內

## 📊 統計

| Type | 頁數 |
|------|------|
| overview | 6 |
| concept | 4 |
| synthesis | 5 |
| sop | 2 |

**總計:** 17 個 wiki 頁

要修嗎?修的話哪些(全修 / 只修 Error / 指定項)?

Anti-patterns

  • ❌ Phase 1 改任何檔案(連「補個 frontmatter」都不行)
  • ❌ User 沒點頭就進 Phase 2(「跑 lint」≠「修」)
  • ❌ 硬編碼 Karpathy 5 類當 type 鐵律 — repo SCHEMA 擴充的 type 是合法的
  • ❌ 依賴 yq / jq(用 python3 stdlib)
  • ❌ 用 mtime 判 stale(git repo 一律用 commit 日)
  • ❌ 訪問外部 API / 抓 Git remote(純 local read;git log 是 local)
  • ❌ 掃 journal/ / drafts/ / scripts/(非 wiki 一部分)
  • ❌ 路徑偵測不到時瞎猜(必須停止並告訴 user)
  • ❌ 把啟發式(cross-ref 缺失、可能矛盾)標成 Error
  • ❌ 範例 / 報告裡塞任何真實組織的內部名稱(host / 產品 / 路徑)— 示意一律虛構

Important rules

  1. 兩段式契約是核心 — Phase 1 read-only;Phase 2 等明確點頭。違規即破壞 skill 契約
  2. Repo 規約 > skill 預設 — type 清單、必備欄位、log 留痕政策都先讀目標 repo 的 SCHEMA / 規則檔
  3. Path 偵測順序固定 — 不要倒過來、不要跳級、找不到就停
  4. Severity 寧降勿升 — 啟發式 → Info;推測 → Warning;只有結構壞了才 Error
  5. 每個 finding 必須有具體檔名 — 不准「某些頁面 frontmatter 不全」這種模糊敘述
  6. Contradiction 永遠標需人工確認 — 你看到的可能只是更新時差
  7. raw/ 是 gitignored — 遠端跑(CI / cloud agent)就 skip raw 存在性檢查,並在報告註明
  8. 修不動的列 deferred 不硬修 — 內容矛盾、大範圍風格清理要 user 判斷
  9. 語言跟 wiki 對齊 — 中文 wiki 用繁中報告,user 明確要求才改
  10. 報告 / 範例永遠虛構化 — 不洩任何真實內部 context