majiayu000 Markdown Documentation Integrity Check
Markdownドキュメントの整合性・完全性を検証し、問題を検出・修正するスキル。
チェック手順
Step 1: 対象ファイルの特定
Globツールで **/*.md を検索
除外ディレクトリ: node_modules/, .git/, vendor/, dist/, build/
Step 2: 内部リンクの検証
Grepで内部リンクを抽出:
パターン: \[.*\]\((?!https?://|mailto:|#)[^)]+\)各リンクについて:
- リンク元ファイルのディレクトリを基準にパスを解決
- Globまたは
lsでファイル存在を確認
問題検出時:
- 類似ファイル名を検索して修正候補を提示
- ファイル作成またはリンク削除を提案
Step 3: アンカーリンクの検証
アンカー参照を抽出:
パターン: \[.*\]\([^)]*#[^)]+\)対象ファイルの見出しを取得:
パターン: ^#+\s+(.+)$GitHub形式アンカー変換ルール:
- 小文字化
- スペース → ハイフン
- 特殊文字削除（英数字・ハイフン・日本語以外）
- 例:
## Installation Guide→#installation-guide - 例:
## fzfユーティリティ→#fzfユーティリティ
問題検出時:
- 正しいアンカー形式を提示
Step 4: 外部URLの検証（オプション）
ユーザーが明示的に依頼した場合のみ実行:
URLを抽出:
パターン: https?://[^\s\)>]+WebFetchツールで到達性確認
レート制限に注意（大量URLは分割実行）
Step 5: バッククォート参照の検証
バッククォート内のファイル参照を検出:
パターン: `[^`]+\.(md|txt|json|yaml|yml|sh|py|js|ts)`参照先ファイルの存在を確認
Step 6: 完全性チェック
空セクション検出:
- 見出し直後に別の見出しまたはEOFがある箇所
TODOマーカー検出:
TODO,FIXME,XXX,TBD,WIP
プレースホルダー検出:
[...],(placeholder),TBD
報告フォーマット
概要
## 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件（すべて有効）
自動修正
ユーザー確認後に以下の修正を実行可能:
修正可能な問題
- リンク先ファイル名の修正: 類似ファイル名への置換
- アンカーの修正: 正しいアンカー形式への変換
- リンクの削除: 参照先が存在しないリンクの除去
修正手順
- 修正対象と修正内容を一覧表示
- ユーザーに確認を求める
- 承認後、Editツールで修正を実行
- 修正後の差分を表示
ベストプラクティス
効率的なチェック
- 大規模リポジトリでは
git diff --name-onlyで変更ファイルのみ対象 - ユーザーが範囲指定した場合はその範囲のみチェック
誤検知の回避
- コードブロック（```）内のリンク構文は無視
- HTML コメント内は無視
- 動的生成リンク（変数展開など）は注記付きで報告
フォローアップ
- 問題発見後は具体的な修正案を提示
- 自動修正可能な問題を明示
- 修正の影響範囲を説明