docs-auditor について
開発者向けドキュメントチームの監査スキルです。ドキュメントサイトを7カテゴリ、計33項目で確認し、スコア付きのビジュアル HTML レポートを作成します。AI からの発見性、ナビゲーション、コンテンツ品質、SEO、リンク、保守状況を対象にします。
主な機能
- 017カテゴリ、計33項目のチェック
- 02ドキュメント構成と網羅性の評価
- 03SEO、内部リンク、バージョン情報の確認
- 04スコア付き自己完結型 HTML レポート生成
活用シーン
- 01開発者向けドキュメント全体の品質評価
- 02ナビゲーション、内容、クロール性の不足発見
- 03ドキュメント改善の優先順位付け
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/docs-auditorを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
README.mdreferences/fetch-strategy.mdscoring.mdwidget-template.mdtests/test-cases.json詳細
ドキュメント監査スキル
7 つのカテゴリにわたる 33 項目のチェックを通じて、開発者向けドキュメントサイトを監査します。ドキュメントの URL を指定すると、必要なページをすべて取得し、各項目を評価して、視覚的なスコア付きレポートを作成します。
ステップ 0a — 対象を絞った検索で派生 URL のロックを解除する（重要。最初に実行）
派生 URL を取得する前に、必要な正確なファイルパスを含めて、web_search を 1 回実行します。これは必須です。web_fetch で取得できるのは、ユーザーが指定した URL、または以前の検索／取得結果に表示された URL のみです。このツールは、ルートドメインが判明していても、派生パスを独自に取得できません。
https://docs.example.com/ のようなドキュメント URL が指定された場合は、次の検索を作成して実行します。
docs.example.com/llms.txt docs.example.com/robots.txt docs.example.com/sitemap.xml example.com/llms.txt example.com/robots.txt example.com/sitemap.xml
同じクエリにサブドメインとルートドメインの両方のバリエーションを含めます。これらのファイルはどちらにホストされている場合もあります。この 1 回の検索で、結果に正確なファイル URL が表示され、すぐに取得可能になります。ファイルが検索結果にまったく表示されない場合は、それ自体がファイルが存在しない強い証拠です。取得を試みる必要はなく、該当する項目を不合格とします。
この検索は内部の準備手順として、ユーザーに知らせずに実行します。ユーザーに説明しないでください。
ステップ 0b — URL の展開（重要）
ユーザーがベースとなるドキュメント URL（例：https://docs.example.com/）を指定した場合、次の派生 URL をすべてユーザーが指定したものとして直ちに扱い、許可を求めずに取得しなければなりません。これが監査を機能させる中核となる仕組みです。
ベース URL が https://docs.example.com/ の場合、最初の取得で次のものをすべて取得します。
{base}/robots.txt
{base}/sitemap.xml
{base}/llms.txt
{base}/llms-full.txt
ドキュメントがサブドメインにある場合は、ルートドメインのバリエーションも試します。
https://{root-domain}/robots.txt
https://{root-domain}/llms.txt
https://{root-domain}/llms-full.txt
https://{root-domain}/sitemap.xml
その後、メインのドキュメントページに加えて、次の標準的なサブページも取得します（サイドバー／ナビゲーションで見つかった内容に応じてスラッグを調整してください）。
{base}/ ← landing / intro page
{base}/quickstart (or /getting-started, /get-started)
{base}/changelog (or /releases, /release-notes)
{base}/api (or /api-reference, /reference)
{base}/faq (or /troubleshooting, /help)
{base}/[one use-case or tutorial page]
{base}/[one deep settings or config page]
最低 6〜8 ページを取得します。多いほど望ましいです。ユーザーに URL の追加を求めてはいけません。URL は自分で導き出します。
ステップ 1 — 33 項目すべてをチェックする
取得後、以下のすべての項目を評価します。証拠として、取得した HTML／Markdown の内容を使用します。各項目について、その項目に定められた基準に従い、合格、注意、または不合格と判定します。
カテゴリ 1 — AI と LLM による見つけやすさ（5 項目）
| # | チェック項目 | 合格 | 注意 | 不合格 |
|---|---|---|---|---|
| 1.1 | ルートドメインに llms.txt がある | ファイルを正常に取得し、内容がある | ファイルは存在するが、空または形式が不正 | 404／見つからない |
| 1.2 | llms-full.txt がある | ファイルを正常に取得できる | ファイルは存在するが、内容が乏しい | 404／見つからない |
| 1.3 | llms.txt にドキュメントページが記載されている | llms.txt 内にドキュメントページへのリンクがある | 一部のページは記載されているが、不完全 | llms.txt がない、またはドキュメントへのリンクがない |
| 1.4 | robots.txt で AI ボットが許可されている | GPTBot、ClaudeBot などが明示的に許可されている、または該当ボットへの禁止ルールがない | ボットへの言及がない（判断できない） | ボットが明示的に禁止されている |
| 1.5 | sitemap.xml にドキュメントページが含まれている | サイトマップが見つかり、ドキュメントページの URL が含まれている | サイトマップは存在するが、内容が乏しい／不完全 | サイトマップがない、または 404 |
カテゴリー 2 — 構成とナビゲーション（6 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 2.1 | 実際のコンテンツを含む概要ページがある | 充実した製品説明（200 語超）を含むページがある | ページはあるが、内容が薄い／曖昧 | 概要ページが見つからない |
| 2.2 | 実行可能な手順を含むクイックスタート／はじめに | ユーザーが動作する状態になるまでの手順を段階的に説明している | ページはあるが、手順が曖昧または不完全 | クイックスタートが見つからない |
| 2.3 | API リファレンス／リファレンスセクションがある | エンドポイントまたはメソッドを含む専用の API リファレンスセクションがある | リファレンスのコンテンツはあるが、API リファレンスとして整理されていない | リファレンスセクションが見つからない |
| 2.4 | サイドバー／ナビゲーションメニューがある | カテゴリー分けされたリンクを含むサイドバーが HTML 上で確認できる | サイドバーはあるが、分類されていない | サイドバーが検出されない |
| 2.5 | パンくずナビゲーションがある | 抽出したページでパンくずリストを確認できる | 一部のページにはあるが、すべてにはない | パンくずリストが見つからない |
| 2.6 | 検索機能がある | HTML 上で検索入力欄を検出できる | 検索機能への外部リンクはあるが、ページ上にはない | 検索機能が見つからない |
カテゴリー 3 — コンテンツの網羅性（6 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 3.1 | ユースケース／チュートリアル／サンプルのセクションがある | 2 ページ以上の完全なチュートリアルを含む専用セクションがある | セクションはあるが、ページが 1 つだけ、または内容が非常に薄い | ユースケース／チュートリアルが見つからない |
| 3.2 | コードサンプルがある | 抽出した複数のページでコードブロックが見つかる | コードがあるのは 1 ページのみ | コードサンプルが見つからない |
| 3.3 | 複数の言語によるサンプル（Python、JS、cURL など） | コードサンプルで 2 言語以上が示されている | 示されている言語は 1 つのみ | コードサンプルがまったくない |
| 3.4 | 変更履歴／リリースノートがある | 実際のエントリーを含む変更履歴ページがある | ページはあるが、空またはプレースホルダー | 変更履歴が見つからない |
| 3.5 | FAQ／トラブルシューティングのセクションがある | 実際の Q&A を含む専用の FAQ またはトラブルシューティングページがある | FAQ への言及はあるが、内容が最小限 | FAQ またはトラブルシューティングが見つからない |
| 3.6 | エラーメッセージ／ステータスコードが文書化されている | ドキュメント内のどこかにエラーコードまたはステータスコードが記載されている | 簡単な言及のみ | エラーに関するドキュメントが見つからない |
カテゴリー 4 — コンテンツの品質（3 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 4.1 | 概要ページで、製品の内容と対象ユーザーが説明されている | 明確な製品説明があり、対象ユーザーも示されている | 製品は説明されているが、対象ユーザーが曖昧 | 内容のない一般的な紹介／マーケティング文 |
| 4.2 | クイックスタートでユーザーが動作する状態になる | 初期状態から動作する出力を得るまでの一連の手順がある | 手順はあるが、不完全または重要な詳細が欠けている | クイックスタートが曖昧すぎて手順を追えない |
| 4.3 | 抽出したページに十分な内容がある（雛形ではない） | 抽出したすべてのページに実際のコンテンツ（150 語超、構成あり）がある | 充実したページと雛形が混在している | 抽出したページの大半が雛形 |
カテゴリー 5 — テクニカル SEO とクロール可能性（5 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 5.1 | HTTPS が適用されている | 取得したすべての URL が HTTPS を使用している | HTTP と HTTPS が混在している | HTTP のみ |
| 5.2 | ドキュメントページにメタタイトルがある | 抽出したすべてのページで <title> タグが見つかる | 一部のページにある | ほとんどのページで見つからない |
| 5.3 | ドキュメントページにメタディスクリプションがある | 抽出したすべてのページで meta-description が見つかる | 一部のページにある | ほとんどのページで見つからない |
| 5.4 | 正しい canonical URL がある | canonical タグがあり、正しいドメインを指している | canonical タグはあるが、誤ったドメイン／プレビュードメインを指している | canonical タグが見つからない |
| 5.5 | ドキュメントページに noindex 指定がない | 抽出したすべてのページで meta-robots: index, follow が設定されている | 混在している。一部のページに noindex が設定されている | ほとんどのページに noindex が設定されている |
カテゴリ 6 — 内部リンクとページ遷移（4 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 6.1 | ドキュメントページ同士が相互にリンクしている | サンプルページの本文に内部リンクが見つかる | 一部のページでは相互リンクされているが、大半ではされていない | 本文に内部リンクが見つからない |
| 6.2 | 次／前のページへのナビゲーションがある | サンプルページの下部に前／次のページへのナビゲーションリンクがある | 一部のページにはある | 見つからない |
| 6.3 | GitHub／ソースコードへのリンクがある | ドキュメント内に GitHub またはソースコードへのリンクが見つかる | テキスト内で言及されているが、リンクはない | GitHub／ソースコードへのリンクが見つからない |
| 6.4 | コミュニティ／サポートへのリンクがある（Discord、Slack、フォーラム、チャット） | コミュニティまたはサポートチャネルへの直接リンクが見つかる | 言及はあるが、直接リンクはない | コミュニティまたはサポートへの言及がない |
カテゴリ 7 — バージョン管理とメンテナンス（4 項目）
| # | チェック項目 | 合格 | 警告 | 不合格 |
|---|---|---|---|---|
| 7.1 | バージョン表示が見える（v1.2、「latest」、バッジ） | サンプルページにバージョンバッジまたはラベルが見える | テキスト内でバージョンに言及されているが、バッジはない | バージョンを示す情報が見つからない |
| 7.2 | ページに最終更新日／鮮度を示す情報がある | 「最終更新日」または同様の情報が見える | 代替情報として変更履歴がある | 鮮度を示す情報がどこにもない |
| 7.3 | インストールコマンドにバージョンが固定されている | インストールコマンドでバージョンが固定されている（例：pip install foo==1.2） | インストールコマンドはあるが、バージョンは固定されていない | インストールコマンドが見つからない |
| 7.4 | 非推奨の告知がある（複数バージョンがある場合） | 非推奨のバナーまたは告知が見える | 変更履歴で非推奨について言及されている | 非推奨の告知がない（複数バージョンの製品の場合のみ不合格） |
ステップ 2 — スコアの計算
各カテゴリについて、満点を基準に採点します。各チェック項目の配点は、カテゴリ内で均等です。 各カテゴリの重みは同じです（それぞれ最大で 100/7 ≈ 14.3 点）。
各カテゴリ内では：
- 合格 = 満点
- 警告 = 配点の半分
- 不合格 = 0 点
最終スコア = 7 カテゴリすべての合計を、100 点満点で最も近い整数に丸めた値です。
ステップ 3 — レポートの生成
単独で動作する HTML レポートファイルを生成します。
- デザインの参考として、
references/widget-template.mdの HTML/CSS/JS テンプレートを使用します。 - 完成したレポートを、現在の作業ディレクトリに
{domain}-docs-audit.htmlという名前で保存します（例：supabase-docs-audit.html）。 - レポートには以下を含めます。
- スコアのヒーロー表示 — 100 点満点の大きなスコア、ドメイン名、合格／警告／不合格の件数の概要
- 凡例 — 緑のドット = 合格、琥珀色のドット = 警告、赤のドット = 不合格
- カテゴリセクション — 各カテゴリにつき 1 つのブロック。以下を含めます。
- カテゴリ名とスコア（例：「3/5」）
- ピル型バッジ：「X 合格」「X 警告」「X 不合格」
- 各チェック項目の行。アイコン（✓ / ! / ✗）、ラベル、短い根拠メモを含めます。
- 監査データ（スコア、件数、カテゴリスコア、チェック状況、根拠メモ）はすべてテンプレートに直接反映し、プレースホルダーを未入力のまま残さないでください。
- ファイルは完全に自己完結している必要があります（外部依存なし）。サーバーを使わずに、どのブラウザーでも正しく開けるようにします。
ステップ 4 — レポートの後
レポートの生成後、以下を含む短いテキストの要約（3～5 文）を提示します。
- 特に優れた 1～2 個のカテゴリ
- 最大の不足点／すぐに実施できる改善策
- 重大な問題（例：canonical の不備、ドキュメントページの noindex、AI ボットのブロック）
さらに詳しく調べたいカテゴリがあるか、優先順位付きのアクションプランを作成するかを尋ねます。
エッジケースに関する注意事項
- サブドメインのドキュメント（例：
docs.stripe.com）：robots.txt、llms.txt、sitemap.xmlを必ずルートドメイン（stripe.com）でも確認してください。ルートドメインで公開されていることがよくあります。 - 認証が必要なドキュメント：ページが 401/403 を返す場合、該当するチェックを警告としてマークし、「確認できませんでした — ページには認証が必要です。」という注記を付けてください。
- JavaScript でレンダリングされるドキュメント：取得した HTML のテキストが少ない（200 文字未満）場合、ドキュメントが JavaScript でレンダリングされている可能性があり、一部のチェックでは結論を出せないことを注記してください。
- チェック 7.4（非推奨化）：製品に複数のバージョンがあることを示す証拠がある場合に限り、失敗としてください。v1 のみであることが明らかな場合は、N/A（スコアリングでは合格としてカウント）とマークしてください。