mcpField
L
link-validation

link-validation

github.com/terrylicaテスト・品質2134 回インストール1 日前に更新
リポジトリ

link-validation について

lychee でリポジトリ内の Markdown リンクを検査するスキルです。コミット前に文書のリンクを確認したいコントリビューター向けで、オフラインで実行し、結果をターミナルに表示します。

主な機能

  1. 01オフラインでの Markdown リンク検査
  2. 02相対リンクとルート相対リンクの解決
  3. 03アンカーフラグメントの検証
  4. 04リポジトリルートの検出
  5. 05ターミナルへの概要と終了コードの出力

活用シーン

  1. 01コミット前の文書確認
  2. 02内部リンク切れの検出
  3. 03文書編集後のリンク検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/terrylica/cc-skills --skill link-validation

インストール後、Claude Code で/link-validationを入力して読み込まれたか確認します。

同梱ファイルreferences/evolution-log.md

詳細

リンク検証スキル

lychee を使用して、ワークスペース内の Markdown リンクを検証します。

自己進化するスキル：このスキルは使用を通じて改善されます。手順が誤っている、パラメーターにずれが生じた、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合のみ更新してください。

このスキルを使用する場面

次のような場合に使用してください。

  • Markdown ファイル内のリンク切れを確認する
  • ドキュメントをコミットする前にリンク先のパスを検証する
  • ドキュメントの変更後に内部リンク切れが残っていないことを確認する

実行方法

作業パスは、tasks/link-check.sh にあるオフラインの lychee チェックです。cc-skills リポジトリ内では、品質ゲートの一部として実行されます。

moon run repo:link-check     # this check alone
moon run repo:check          # the whole gate, link-check included
bash tasks/link-check.sh     # the same script without moon

それ以外のワークスペースでは、リポジトリのルートから同じ lychee コマンドを実行します。

lychee --offline --no-progress --root-dir "$(git rev-parse --show-toplevel)" './**/*.md'

リポジトリに lychee.toml がある場合は --config lychee.toml を追加してください。lychee は ./lychee.toml も自動で読み込みます。

チェックの内容

tasks/link-check.sh は次の処理を行います。

  1. 作業ツリーのルートに cd します（git rev-parse --show-toplevel を使用するため、worktree 内でも正しく動作します）
  2. bunx lychee --config lychee.toml --offline --no-progress --root-dir <repo root> './**/*.md' を実行します
  3. lychee のサマリー行を表示した後、✓ every internal link resolves または ✗ broken internal links found (lychee exit N) を表示し、lychee の終了コードで終了します

相対リンク、ルート相対リンク（/docs/adr/x.md。--root-dir を通じて解決されます）、および #anchor フラグメントをチェックします。意図的にオフラインで実行します。外部 URL の到達可能性は、ネットワークや他サイトの稼働状況に左右されるため、チェックしません。lychee 独自の .lycheecache 以外はディスクに書き込みません。結果はターミナル出力と終了コードで確認できます。

特定のマシン上にしか存在しないパス（~/...、別のリポジトリなど）はチェックに通りません。リンクにせず、インラインコードとして記載してください。

要件

  • lychee：tasks/link-check.sh は bunx 経由で実行するため、そこでは Bun だけで十分です。それ以外の場所ではインストールしてください（brew install lychee）。

設定

cc-skills では、リポジトリのルートにある lychee.toml を唯一の lychee 設定ファイルとして使用します。このファイルには、パスと URL の除外設定、および include_fragments = "anchor-only" が記述されています（lychee 0.24 では、以前のブール値 true は拒否されます）。statusline-tools の Stop フックも、同じファイルが存在する場合はこれを読み込みます。

関連するチェック

  • スキル内のリンクの可搬性（インストール後に機能しなくなる絶対リポジトリパス）：link-validator スキル
  • セッション終了時のパスのポリシー：statusline-tools の Stop フックが lint-relative-paths と lychee を実行し、ステータスライン用に .lychee-results.json を書き込みます

履歴

このスキルでは以前、Stop フック hooks/stop-link-check.py について説明しており、これは .link-check-results.md を書き込んでいました。link-tools には hooks.json が存在しなかったため、このフックは実行されず、issue #33 で削除されました。

参考資料

トラブルシューティング

問題原因解決策
lychee が見つからないインストールされていないbrew install lychee を実行するか、bunx lychee 経由で実行します
設定の読み込みに失敗するinclude_fragments = trueinclude_fragments = "anchor-only" を使用します（lychee 0.24 以降）
/docs/... のリンクがすべて失敗する--root-dir が指定されていない絶対パスのリポジトリルートを指定して --root-dir を渡します
~/... へのリンクが失敗するあるマシンにしかパスが存在しないリンクではなく、インラインコードとして記述します
フィクスチャ内の壊れたリンクで失敗するフィクスチャが除外されていない--exclude-path または設定の exclude_path に追加します

実行後の振り返り

このスキルの実行後、終了する前に確認します。

  1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった指示またはエラーテーブルを修正します。
  2. パラメーターまたは出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
  3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新します。推測に基づく更新はしません。

コメント

Markdown 対応