---
name: markdown-check
description: |
  Markdownドキュメントの整合性と完全性をチェックする。
  リンク切れ確認、アンカー検証、外部URL検証、空セクション検出を行い、
  問題があれば修正案を提示する。

  以下の依頼時に使用:
  - 「Markdownチェック」「ドキュメント整合性」「リンク切れ確認」
  - 「ドキュメントレビュー」「ドキュメント検証」「ドキュメント品質」
  - 「READMEのリンクを確認」「mdファイルを検証」「.mdをチェック」
  - 「壊れたリンクを探して」「デッドリンク」「無効なリンク」
  - 「broken links」「check markdown」「validate docs」「lint documentation」
  - 「dead links」「invalid links」「link checker」「doc review」
  - PR前のドキュメントチェック、ドキュメント更新後の確認
  - 「ドキュメントに問題ないか」「リンクが正しいか」
allowed-tools: Read, Glob, Grep, Edit, Bash(git diff:*), WebFetch
context: fork
agent: general-purpose
model: haiku
effort: low
license: MIT
metadata:
  origin: "https://github.com/ebal5/agent-skills"
---

# Markdown Documentation Integrity Check

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

## チェック手順

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

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

### Step 2: 内部リンクの検証

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

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

2. 各リンクについて:
   - リンク元ファイルのディレクトリを基準にパスを解決
   - Globまたは `ls` でファイル存在を確認

3. 問題検出時:
   - 類似ファイル名を検索して修正候補を提示
   - ファイル作成またはリンク削除を提案

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

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

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

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

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

3. GitHub形式アンカー変換ルール:
   - 小文字化
   - スペース → ハイフン
   - 特殊文字削除（英数字・ハイフン・日本語以外）
   - 例: `## Installation Guide` → `#installation-guide`
   - 例: `## fzfユーティリティ` → `#fzfユーティリティ`

4. 問題検出時:
   - 正しいアンカー形式を提示

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

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

1. URLを抽出:

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

2. WebFetchツールで到達性確認
3. レート制限に注意（大量URLは分割実行）

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

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

   ```text
   パターン: `[^`]+\.(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
## Markdownドキュメントチェック結果

### 概要

| カテゴリ | 検出数 | 問題数 |
|----------|--------|--------|
| 内部リンク | X | Y |
| アンカー | X | Y |
| 外部URL | X | Y (チェック時のみ) |
| バッククォート参照 | X | Y |
| 完全性 | - | Y |
```

### 問題詳細

```markdown
### 内部リンク切れ (N件)

| ファイル | 行 | リンク | 修正案 |
|----------|-----|--------|--------|
| `README.md` | 42 | `[guide](GUIDE.md)` | `guide.md` に修正 or リンク削除 |

### アンカーエラー (N件)

| ファイル | 行 | 参照 | 修正案 |
|----------|-----|------|--------|
| `docs/api.md` | 15 | `#instalation` | `#installation` に修正 |
```

### 問題なしの場合

```markdown
## Markdownドキュメントチェック結果

✓ すべてのチェックをパスしました

- チェックファイル数: X
- 内部リンク: Y件（すべて有効）
- アンカー: Z件（すべて有効）
```

## 自動修正

このスキルは `context: fork` で隔離 subagent として動作する。
fork 実行中は対話的確認ができないため、**検出と修正提案の生成まで**を
行い、実際の Edit 適用は返却レポートを受けたメインセッションで
ユーザー確認の上で実施する。

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

### 修正可能な問題

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

### 修正手順

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

## ベストプラクティス

### 効率的なチェック

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

### 誤検知の回避

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

### フォローアップ

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

## プロジェクト規約（markdownlint との相性）

この skill 自体は semantic check（リンク・アンカー・空セクション）だが、
新規 markdown を書く / 修正するときは `markdownlint-cli2` も同時に通過させたい。
特にハマりやすい罠:

### MD060 table-column-style

table の separator row（区切り行）のスタイルが不統一だと、MD060 の
`consistent` 検出ロジックが「最初に見た形」を基準にして以降の表を誤判定する。
コンパクト形式（`|------|------|`）と空白入り形式（`| --- | --- |`）を混在
させるとエラーが連発する。

**このリポジトリの convention は空白入り形式**（`| --- | --- |`）。
review-loop / grill-me が先例。新規 markdown を書くときは最初からこの形で
書けば落とし穴を回避できる。

```markdown
| col1 | col2 | col3 |
| --- | --- | --- |
| ... | ... | ... |
```

### 対処

既存ファイルで混在している場合、`markdownlint-cli2 --fix` は一部を直すが
MD060 は auto-fix しない。手動で separator を全て `| --- |` 形式に揃える。