markdown-check

ebal5's avatarfrom ebal5

Markdownドキュメントの整合性と完全性をチェックする。リンク切れ確認、アンカー検証、外部URL検証、空セクション検出を行い、問題があれば修正案を提示する。以下の依頼時に使用:- 「Markdownチェック」「ドキュメント整合性」「リンク切れ確認」- 「ドキュメントレビュー」「ドキュメント検証」「ドキュメント品質」- 「READMEのリンクを確認」「mdファイルを検証」「.mdをチェック」- 「壊れたリンクを探して」「デッドリンク」「無効なリンク」- 「broken links」「check markdown」「validate docs」「lint documentation」- 「dead links」「invalid links」「link checker」「doc review」- PR前のドキュメントチェック、ドキュメント更新後の確認- 「ドキュメントに問題ないか」「リンクが正しいか」

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025
[Technical Writing]

When & Why to Use This Skill

This Claude skill ensures the integrity and completeness of Markdown documentation by performing comprehensive checks on internal and external links, anchor tags, and content structure. It helps maintain professional documentation standards by identifying broken links, empty sections, and placeholders, offering automated fixes to streamline the editing process.

Use Cases

  • Pre-merge Documentation Review: Automatically validate links and anchors in Pull Requests to ensure documentation quality before merging code into the main branch.
  • Broken Link & Anchor Auditing: Scan entire repositories to detect and fix dead external URLs and mismatched internal anchors using GitHub-style formatting rules.
  • Content Completeness Check: Identify empty sections, TODO markers, and placeholder text to ensure technical manuals and READMEs are fully authored and ready for publication.
  • Automated Documentation Maintenance: Rapidly update file references and link paths during repository restructuring or file renaming tasks to prevent 'link rot'.
namemarkdown-check
description|

Markdown Documentation Integrity Check

Markdownドキュメントの整合性・完全性を検証し、問題を検出・修正するスキル。

チェック手順

Step 1: 対象ファイルの特定

Globツールで **/*.md を検索
除外ディレクトリ: node_modules/, .git/, vendor/, dist/, build/

Step 2: 内部リンクの検証

  1. Grepで内部リンクを抽出:

    パターン: \[.*\]\((?!https?://|mailto:|#)[^)]+\)

  2. 各リンクについて:

    • リンク元ファイルのディレクトリを基準にパスを解決
    • Globまたは ls でファイル存在を確認

  3. 問題検出時:

    • 類似ファイル名を検索して修正候補を提示
    • ファイル作成またはリンク削除を提案

Step 3: アンカーリンクの検証

  1. アンカー参照を抽出:

    パターン: \[.*\]\([^)]*#[^)]+\)

  2. 対象ファイルの見出しを取得:

    パターン: ^#+\s+(.+)$

  3. GitHub形式アンカー変換ルール:

    • 小文字化
    • スペース → ハイフン
    • 特殊文字削除（英数字・ハイフン・日本語以外）
    • 例: ## Installation Guide → #installation-guide
    • 例: ## fzfユーティリティ → #fzfユーティリティ

  4. 問題検出時:

    • 正しいアンカー形式を提示

Step 4: 外部URLの検証（オプション）

ユーザーが明示的に依頼した場合のみ実行:

  1. URLを抽出:

    パターン: https?://[^\s\)>]+

  2. WebFetchツールで到達性確認

  3. レート制限に注意（大量URLは分割実行）

Step 5: バッククォート参照の検証

  1. バッククォート内のファイル参照を検出:

    パターン: `[^`]+\.(md|txt|json|yaml|yml|sh|py|js|ts)`

  2. 参照先ファイルの存在を確認

Step 6: 完全性チェック

  1. 空セクション検出:

    • 見出し直後に別の見出しまたはEOFがある箇所

  2. TODOマーカー検出:

    • TODO, FIXME, XXX, TBD, WIP

  3. プレースホルダー検出:

    • [...], (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件（すべて有効）

自動修正

ユーザー確認後に以下の修正を実行可能:

修正可能な問題

  • リンク先ファイル名の修正: 類似ファイル名への置換
  • アンカーの修正: 正しいアンカー形式への変換
  • リンクの削除: 参照先が存在しないリンクの除去

修正手順

  1. 修正対象と修正内容を一覧表示
  2. ユーザーに確認を求める
  3. 承認後、Editツールで修正を実行
  4. 修正後の差分を表示

ベストプラクティス

効率的なチェック

  • 大規模リポジトリでは git diff --name-only で変更ファイルのみ対象
  • ユーザーが範囲指定した場合はその範囲のみチェック

誤検知の回避

  • コードブロック（```）内のリンク構文は無視
  • HTML コメント内は無視
  • 動的生成リンク（変数展開など）は注記付きで報告

フォローアップ

  • 問題発見後は具体的な修正案を提示
  • 自動修正可能な問題を明示
  • 修正の影響範囲を説明