# Markdown Check

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

- Skill: `ebal5/markdown-check` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ebal5/markdown-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ebal5/markdown-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: ebal5 (https://skillmd.com/u/ebal5)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ebal5/markdown-check

---


# 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` で存在確認し、あれば実行する:

```bash
# 内部リンクとアンカー（外部 URL は叩かない）
lychee --offline --include-fragments --no-progress <Step 1 のファイル>
```

フラグ名は lychee の版で変わることがあるので、失敗したら `lychee --help`
で確認する。外部 URL の到達性まで見るのはユーザーが明示的に依頼した場合
のみ（`--offline` を外す）。レート制限があるため、大量の URL は分割する。
lychee が無く対象が数個なら WebFetch で個別確認してもよい。

**lychee が無い環境でのフォールバック**（lychee は同梱されないため、
実際にはこちらが走ることが多い）:

1. リンクを抽出する。**外部 URL・mailto・同一ファイル内アンカーは
   除外する**（相対パスとして解決すると全件が偽陽性になる）:

   ```text
   \[[^\]]*\]\((?!https?://|mailto:|#)([^)]+)\)
   ```

2. リンク元ファイルのディレクトリを基準にパスを解決し、存在を確認する
3. アンカー付きリンク（`path.md#section`）は、対象ファイルの
   `^#+\s+(.+)$` を GitHub 形式（小文字化 → 空白をハイフン →
   英数字・ハイフン・日本語以外を削除）に変換して突き合わせる

取りこぼしがあり得るので、報告に「lychee 未導入のため簡易チェック」と
明記する。

### Step 3: 書式の検証

`markdownlint-cli2` があれば実行する。リポジトリに
`.markdownlint.jsonc` があれば自動で読まれる。

対象は Step 1 で絞ったファイルに合わせる。リポジトリ全体を指定すると
大規模リポジトリで無駄が大きい。

```bash
markdownlint-cli2 <Step 1 のファイル>
```

`--fix` は自動修正するが MD060 など一部は直さない（後述）。

### Step 4: ツールが拾えない部分の検証

ここが LLM の担当。機械的な存在確認ではなく、内容の判断が要るもの:

1. **空セクション**: 見出し直後に別の見出しまたは EOF が来る箇所。
   意図的な見出しのみのセクション（目次的な親見出し）と区別する
2. **バッククォート参照**: `` `path/to/file.md` `` のようにリンクでは
   ないファイル参照。lychee は見ないので、実在するか確認する
3. **未完成マーカー**: `TODO` / `FIXME` / `TBD` / `WIP` や
   `(placeholder)` の残存。ただしそれ自体を説明している文脈
   （このスキルの記述のような）は誤検知として除外する

## 報告フォーマット

### 概要

```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. 修正後の差分を表示

## ベストプラクティス

### 誤検知の回避

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

### フォローアップ

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

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

Step 3 で回す `markdownlint-cli2` で特にハマりやすい罠:

### MD060 table-column-style

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

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

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

### 対処

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