ebal5 Markdown Documentation Integrity Check
Markdownドキュメントの整合性・完全性を検証し、問題を検出・修正するスキル。
方針: 決定的ツールを先に、LLM は解釈に使う
リンク・アンカーの存在検証はパターンマッチの仕事であり、LLM に手作業で やらせると取りこぼす。まず決定的ツールを回し、その出力の解釈と修正案の 生成に LLM を使う。ツールが無い環境ではフォールバックするが、 「無いので飛ばした」ことを必ず報告に明記する。
チェック手順
Step 1: 対象ファイルの特定
Glob で **/*.md を検索。除外: node_modules/, .git/, vendor/,
dist/, build/。
変更分だけで足りる場合は git diff --name-only に絞る。
Step 2: リンク・アンカーの検証
command -v lychee で存在確認し、あれば実行する:
# 内部リンクとアンカー（外部 URL は叩かない）
lychee --offline --include-fragments --no-progress <Step 1 のファイル>
フラグ名は lychee の版で変わることがあるので、失敗したら lychee --help
で確認する。外部 URL の到達性まで見るのはユーザーが明示的に依頼した場合
のみ（--offline を外す）。レート制限があるため、大量の URL は分割する。
lychee が無く対象が数個なら WebFetch で個別確認してもよい。
lychee が無い環境でのフォールバック（lychee は同梱されないため、 実際にはこちらが走ることが多い）:
リンクを抽出する。外部 URL・mailto・同一ファイル内アンカーは 除外する（相対パスとして解決すると全件が偽陽性になる）:
\[[^\]]*\]\((?!https?://|mailto:|#)([^)]+)\)リンク元ファイルのディレクトリを基準にパスを解決し、存在を確認する
アンカー付きリンク（
path.md#section）は、対象ファイルの^#+\s+(.+)$を GitHub 形式（小文字化 → 空白をハイフン → 英数字・ハイフン・日本語以外を削除）に変換して突き合わせる
取りこぼしがあり得るので、報告に「lychee 未導入のため簡易チェック」と 明記する。
Step 3: 書式の検証
markdownlint-cli2 があれば実行する。リポジトリに
.markdownlint.jsonc があれば自動で読まれる。
対象は Step 1 で絞ったファイルに合わせる。リポジトリ全体を指定すると 大規模リポジトリで無駄が大きい。
markdownlint-cli2 <Step 1 のファイル>
--fix は自動修正するが MD060 など一部は直さない（後述）。
Step 4: ツールが拾えない部分の検証
ここが LLM の担当。機械的な存在確認ではなく、内容の判断が要るもの:
- 空セクション: 見出し直後に別の見出しまたは EOF が来る箇所。 意図的な見出しのみのセクション（目次的な親見出し）と区別する
- バッククォート参照:
`path/to/file.md`のようにリンクでは ないファイル参照。lychee は見ないので、実在するか確認する - 未完成マーカー:
TODO/FIXME/TBD/WIPや(placeholder)の残存。ただしそれ自体を説明している文脈 （このスキルの記述のような）は誤検知として除外する
報告フォーマット
概要
## Markdownドキュメントチェック結果
### 概要
| カテゴリ | 検出数 | 問題数 |
| --- | --- | --- |
| 内部リンク | X | Y |
| アンカー | X | Y |
| 外部URL | X | Y (チェック時のみ) |
| バッククォート参照 | X | Y |
| 完全性 | - | Y |
問題詳細
### 内部リンク切れ (N件)
| ファイル | 行 | リンク | 修正案 |
| --- | --- | --- | --- |
| `README.md` | 42 | `[guide](GUIDE.md)` | `guide.md` に修正 or リンク削除 |
### アンカーエラー (N件)
| ファイル | 行 | 参照 | 修正案 |
| --- | --- | --- | --- |
| `docs/api.md` | 15 | `#instalation` | `#installation` に修正 |
問題なしの場合
## Markdownドキュメントチェック結果
✓ すべてのチェックをパスしました
- チェックファイル数: X
- 内部リンク: Y件（すべて有効）
- アンカー: Z件（すべて有効）
自動修正
このスキルは context: fork で隔離 subagent として動作する。
fork 実行中は対話的確認ができないため、検出と修正提案の生成までを
行い、実際の Edit 適用は返却レポートを受けたメインセッションで
ユーザー確認の上で実施する。
ユーザー確認後に以下の修正を実行可能:
修正可能な問題
- リンク先ファイル名の修正: 類似ファイル名への置換
- アンカーの修正: 正しいアンカー形式への変換
- リンクの削除: 参照先が存在しないリンクの除去
修正手順
- 修正対象と修正内容を一覧表示
- ユーザーに確認を求める
- 承認後、Editツールで修正を実行
- 修正後の差分を表示
ベストプラクティス
誤検知の回避
- コードブロック（```）内のリンク構文は無視
- HTML コメント内は無視
- 動的生成リンク（変数展開など）は注記付きで報告
フォローアップ
- 問題発見後は具体的な修正案を提示
- 自動修正可能な問題を明示
- 修正の影響範囲を説明
プロジェクト規約（markdownlint との相性）
Step 3 で回す markdownlint-cli2 で特にハマりやすい罠:
MD060 table-column-style
table の separator row（区切り行）のスタイルが不統一だと、MD060 の
consistent 検出ロジックが「最初に見た形」を基準にして以降の表を誤判定する。
コンパクト形式（|------|------|）と空白入り形式（| --- | --- |）を混在
させるとエラーが連発する。
このリポジトリの convention は空白入り形式（| --- | --- |）。
grilling が先例。新規 markdown を書くときは最初からこの形で書けば
落とし穴を回避できる。
| col1 | col2 | col3 |
| --- | --- | --- |
| ... | ... | ... |
対処
既存ファイルで混在している場合、markdownlint-cli2 --fix は一部を直すが
MD060 は auto-fix しない。手動で separator を全て | --- | 形式に揃える。