broken-link-check Skill

broken-link-check

掃描 .claude/ 目錄下所有 Markdown 文件中的路徑引用，偵測失效連結。

背景

.claude/ 目錄中的規則、方法論、代理人定義文件大量交叉引用彼此。當文件被重命名或移動時，舊的引用路徑會變成 broken link。

此工具用於定期偵測此類問題，防止 broken links 長期未被發現。

權威 gate：scan_links.py CLI

broken-link 計數的唯一權威來源是 scan_links.py 確定性 CLI，不是 LLM 手動判讀。LLM 手動 Glob/Grep 流程對同一 repo 會產出浮動計數（W8-019 實測 258 vs 155），無法作為跨框架完成 gate。CLI 以固定排除規則與穩定排序保證同一 repo 連續執行 byte-for-byte 一致，因此作為權威 gate。

立即掃描（權威）

python3 .claude/skills/broken-link-check/scan_links.py .

位置參數為 repo root（預設 cwd），掃描 <root>/.claude/**/*.md
exit code：0=零 broken（gate pass）/ 1=偵測到 broken（gate fail）/ 2=執行錯誤（root 不存在、I/O 失敗）
gate 用途可直接接 && 或 CI：broken>0 即非零 exit，與工具自身錯誤（exit 2）區隔

輸出格式

| flag | 用途 | |------|------| | --format text（預設） | 人類可讀：摘要 + 分組 broken 清單 | | --format json | 穩定 schema，供下游清理工具消費（含 source_file/line/raw_ref/resolved_path/category + categories 分類計數） |

四排除旋鈕（預設皆排除，flag 顯式覆寫納入）

| 旋鈕 | 預設 | 覆寫 flag | |------|------|-----------| | 程式碼區塊內引用 | 排除 | --include-code-block | | migration-backups / hook-logs 下路徑 | 排除（歸 excluded_backup） | --include-migration-backups | | placeholder 範例路徑（如 path/file.md） | 排除（歸 placeholder） | --include-placeholder | | documented-error 豁免 marker 行 | 排除（歸 excluded_documented） | --include-documented |

覆寫旋鈕用於 triage/debug，gate 預設一律不加 flag。

documented-error 豁免 marker（W8-049）

error-pattern 案例表會刻意記錄不存在的路徑——例如 confabulation 案例的「錯誤參照」欄、或已遷移/刪除檔案的歷史軌跡。這些路徑的文獻價值正在於保留原貌，redirect/刪除會毀損案例資料。在含該引用的行尾（或同 table cell 內）加上行內 marker，scanner 即將該行所有引用歸 excluded_documented 不計 broken：

<!-- broken-link-exempt: documented-error -->

顯式 opt-in（per-occurrence），無 marker 的真實 broken 不受影響。
marker 僅作用於所在行（PC-146 放置精確性），不會誤豁免他行。
僅取消「不存在」引用的 broken 計列；該行若有存在的引用仍歸 ok，不遮蔽存在事實。
--include-documented 可在 triage 時顯式納入計數。

搭配 /loop 定期掃描

/loop 1h python3 .claude/skills/broken-link-check/scan_links.py .

偵測規則（CLI 內建，供理解輸出用）

CLI 已內建以下規則，本節僅供閱讀輸出時對照，非需手動執行的步驟。

偵測的路徑格式：

| 格式 | 範例 | 解析基準 | |------|------|------| | @.claude/path/file.md | @.claude/pm-rules/decision-tree.md | repo root | | .claude/path/file.md | .claude/agents/incident-responder.md | repo root | | ../path/file.md | ../agents/lavender-interface-designer.md | 引用文件所在目錄  | | ./path/file.md | ./references/detail.md | 引用文件所在目錄  |

排除：http(s)://（外部 URL）、#section（錨點）、預設四旋鈕涵蓋的程式碼區塊 / 備份目錄 / placeholder 範例 / documented-error marker 行。

Fallback：手動流程（非權威，僅 CLI 不可用時參考）

以下手動 Glob/Grep 流程為 scan_links.py 無法執行時（如環境缺 Python）的降級參考，計數可能浮動，不可作為完成 gate。權威結果一律以 CLI 輸出為準。

Glob 找出 .claude/**/*.md，排除 .claude/hook-logs/
Grep 找出上述四種前綴的路徑引用，排除 URL / 錨點 / 程式碼區塊
依解析基準轉為實際路徑
Read/Glob 確認路徑存在，不存在者記為 broken link（含文件名與行號）
輸出 broken 清單

修復建議

發現 broken link 時，建議的修復步驟：

搜尋相似文件名（文件可能被重命名）
確認文件是否已移至其他目錄
更新引用路徑（使用 Edit 工具）
如文件確實已刪除，移除引用或更新為替代文件

注意事項

此工具只掃描 .claude/ 目錄（不掃描 docs/、ui/、server/ 等）
只偵測文件引用，不偵測 URL 有效性
相對路徑解析基於文件所在目錄，需正確計算層級
大型 .claude/ 目錄（100+ 文件）掃描可能需要數分鐘

Version: 2.1.0 Last Updated: 2026-06-15 Source: broken links 後置預防機制；1.0.0-W8-030.1 改路由至 scan_links.py 確定性 CLI 作權威 gate，手動流程降級為非權威 fallback；1.0.0-W8-049 新增 documented-error 豁免 marker（excluded_documented 類別 + --include-documented 旋鈕），case-study 內刻意記錄的不存在路徑顯式 opt-in 豁免

Agent Skills: broken-link-check

Install this agent skill to your local

Skill Files