sdk-docs-auditor

SDK ドキュメント監査ツール

あらゆる SDK ドキュメントサイトを包括的かつ相互参照しながら監査し、スタイルが整ったダウンロード可能な HTML レポートを生成します。

このスキルでできること

1. まず llms.txt を使って SDK の全ページを検出し、利用できない場合は sitemap.xml（curl を使用）、その後ホームページのナビゲーションをクロールします
2. SDK に関連するすべてのページを取得して読み込みます
3. 6 つの固定セクションを監査します：インストール、クイックスタート、エラー処理、トラブルシューティング、例、ベストプラクティス
4. すべての不足項目を、他のすべての SDK ページと相互参照します — 別の場所に存在する内容を不足として指摘することはありません
5. 各セクションを 0～100 点で採点し、評価ランクを割り当てます
6. 美しく、自己完結型で、ダウンロード可能な HTML レポートを生成します

---

ステップ 1 — SDK の全ページを検出する

3 段階の検出方法を順番に試し、成功するまで進めます。

1a. まず llms.txt を試す（推奨）

llms.txt を取得する bash の curl コマンドを実行します：

curl -s <docs_url>/llms.txt

見つかった場合：

• - [Page Title](URL): description というパターンに一致する行から、すべての URL を抽出します
• SDK に関連するページだけに絞り込みます — パスに次のいずれかが含まれる URL を残します： sdk, installation, quickstart, quick-start, error, troubleshoot, example, best-practice, getting-started, reference, api-reference, overview, client, service, memory, search, worker, job, policy, agent, team
• マーケティングページ、変更履歴、ブログ、法務、コミュニティ／フォーラムのページは除外します
• {title, url, description} のリストとして SDK_PAGES[] に保存します
• レポートに「検出方法：llms.txt」と記載します

1b. フォールバック — sitemap.xml を試す

llms.txt が利用できない場合、または有用な URL が含まれていない場合は、サイトマップを取得する bash の curl コマンドを実行します：

curl -s <docs_url>/sitemap.xml | python3 -c "import sys, re; print('\n'.join(re.findall(r'<loc>(.*?)</loc>', sys.stdin.read())))"

サイトマップから URL が返された場合：

• すべての <loc> エントリを解析し、完全な URL の一覧を取得します
• 上記と同じキーワードリストを使って絞り込みます
• {title, url} のリストとして SDK_PAGES[] に保存します
• レポートに「検出方法：sitemap.xml — URL が合計 N 件見つかり、そのうち M 件を SDK 関連ページとして採用」と記載します

レスポンスに <sitemapindex> があるか確認し、複数のサイトマップを含むインデックスにも対応します。見つかった場合は、子サイトマップをそれぞれ curl で取得し、絞り込む前に URL を集約します。

1c. 最終フォールバック — ホームページのナビゲーションをクロールする

llms.txt と sitemap.xml の両方が失敗した場合は、ドキュメントのホームページ（<docs_url>）を取得し、ナビゲーションサイドバーまたはサイトマップ構造からすべてのリンクを抽出して、同じキーワードリストで絞り込みます。

• レポートに「検出方法：ホームページのナビゲーションをクロール（llms.txt と sitemap.xml は利用できません）」と記載します

1d. セクションとの対応を特定する

検出したページから、監査対象の 6 セクションに対応するページを特定します：

監査セクション	パス／タイトルに含まれる語句
インストール	install, setup, getting-started
クイックスタート	quick-start, quickstart, tutorial
エラー処理	error, exception, errors
トラブルシューティング	troubleshoot, faq, debug
例	example, sample, cookbook, tutorial
ベストプラクティス	best-practice, guide, pattern

あるセクションに専用ページが見つからない場合は、その旨を記載します。不在そのものが監査結果となります。

コーパスを作成する

検出したすべてのページを、セクション監査と相互参照の両方に使用するページコーパスとします。

検出の概要を報告します：

[sitemap.xml／llms.txt／ナビゲーションクロール] から N ページが見つかりました。SDK に関連する M ページを採用しました。これから取得します...

---

ステップ 2 — コーパス内のすべてのページを取得する

各ページは bash_tool と curl を使用して取得し、Python で HTML タグを除去してプレーンテキストを抽出します。コーパス内のページには web_fetch を使用しないでください — curl のほうが信頼性が高く、権限エラーも回避できます。

各ページの URL に対して、次のパターンを使用します：

curl -s "https://docs.example.com/sdk/some-page" -L | python3 -c "
import sys, re, html
content = sys.stdin.read()
content = re.sub(r'<script[^>]*>.*?</script>', '', content, flags=re.DOTALL)
content = re.sub(r'<style[^>]*>.*?</style>', '', content, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', content)
text = html.unescape(text)
text = re.sub(r'\s+', ' ', text).strip()
print(text[:6000])
"

Batch multiple pages in a single bash call using a loop to minimise round-trips:

```bash
for page in installation quick-start error-handling troubleshooting examples best-practices overview api-reference; do
  echo "=== PAGE: $page ==="
  curl -s "https://docs.example.com/sdk/$page" -L | python3 -c "
import sys, re, html
content = sys.stdin.read()
content = re.sub(r'<script[^>]*>.*?</script>', '', content, flags=re.DOTALL)
content = re.sub(r'<style[^>]*>.*?</style>', '', content, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', content)
text = html.unescape(text)
text = re.sub(r'\s+', ' ', text).strip()
print(text[:6000])
"
  echo ""
done

大規模サイト（30 ページ超）では、次の順に優先します：

1. 監査対象の 6 セクションのページ（installation、quick-start、error-handling、troubleshooting、examples、best-practices）
2. 概要／クライアント概要ページ
3. API リファレンス
4. サービス固有のページ（agents、jobs、workers、policies、memory、search など）

---

ステップ 3 — 6 つの対象セクションを監査する

以下の 6 つのセクションそれぞれについて、ページを注意深く読み、基準に照らして評価します。その後、取得した他のすべてのページも確認し、見つかった不足が実際には別のページで補われているかを調べます。

3a. インストール

必須（不足している場合は大きく減点）：

• 正確なバージョンを記載した前提条件（Python／Node／言語のバージョン、パッケージマネージャー）
• 少なくとも 1 つの完全なインストールコマンド（pip／npm など）
• 認証情報を取得して設定するための、正確な手順を含む認証設定
• インストールの成功を確認できる、動作する検証用スニペット
• 少なくとも 1 つの期待される出力、または成功を示す確認方法

あると望ましい（不足している場合は中程度の減点）：

• 複数のインストール方法（パッケージマネージャー、ソース、Docker）
• IDE／エディターのセットアップ
• .env の例を含む環境変数の設定
• バージョン互換性表
• オプションの依存関係の説明（各追加機能に含まれるもの）
• コンストラクターのパラメーターリファレンス（すべてのパラメーター、型、デフォルト値）

他のページで確認する一般的な不足項目：

• 環境変数の自動検出（引数なしで呼び出したときにクライアントが環境変数を読み込むか）— api-reference、overview を確認
• 高度なコンストラクターパラメーター（timeout、retries、org）— api-reference を確認
• バージョン固定のガイダンス — getting-started ページを確認

3b. クイックスタート

必須：

• 初めてのユーザーが 5 分以内に実行できる、最小限の番号付き手順
• 最初の呼び出しが成功するまでの、完全に動作するコード
• 各コードスニペットに対する期待される出力
• 前提となるサービス／リソース（キュー、ワーカーなど）の説明

あると望ましい：

• 環境変数とインライン認証情報の両方のパターン
• 複数のインストール方法（pip と poetry など）
• 紹介する各概念について、より詳しいドキュメントへのリンク

確認する一般的な不足項目：

• ワーカー／キューの前提条件 — workers／environments のページを確認
• 有効なモデル／ランタイム ID — models／runtimes サービスのページを確認
• execute 呼び出しのシグネチャの正確さ — api-reference と agents サービスのページを確認

3c. エラー処理

必須：

• 例外クラスの完全な階層（すべての例外クラスと継承関係）
• 各例外クラスについて、説明、インポートパス、コード例を記載
• 少なくとも、認証、接続、タイムアウト、レート制限、API／HTTP エラーを網羅
• HTTP ステータスコードによる分岐（少なくとも 400／401／403／404／500）
• 少なくとも 1 つのレジリエンスパターン（バックオフを伴う再試行）

あると望ましい：

• リソース固有の例外（主要サービスごとに 1 つ）
• ストリーミングのエラー処理
• コンテキストマネージャーによるクリーンアップパターン
• エラーシナリオのテスト／pytest の例
• 避けるべきアンチパターンの例

相互参照チェック — 重要：

• api-reference またはサービスのページに登場する例外クラスをすべて一覧にする
• このページに記載されていないものを明示する
• execute／メソッド呼び出しのシグネチャがすべてのページで一致するか確認し、不一致があれば明示する

3d. トラブルシューティング

必須：

• 診断手順を含む認証エラーの対処
• 解決策を含む接続／タイムアウトの問題
• 少なくとも 1 つのサービス固有のトラブルシューティングセクション

あると望ましい：

• 主要サービス（workers、jobs、policies、agents など）すべてのトラブルシューティング
• セルフホスト／カスタム base_url の問題
• 正しいインポートパスを含むインポートエラー
• エラーメッセージの一覧表
• バックオフの参照先を含むレート制限の説明
• 実際のリンク／コマンドを含む、問題解決のための具体的なチェックリスト

相互参照チェック：

• 独自のエラー処理セクションがあるすべてのサービスページについて、そのシナリオがここにも記載されているか確認する
• 「見つからない」エラーの説明に、データセット／リソース作成メソッドへのリンクがあるか確認する
• 「ステータスを確認する」手順で、ヘルスチェック API が参照されているか確認する

3e. 例

必須：

• 主要なサービスごとに、完全で実行可能なエンドツーエンドの例を少なくとも1つ掲載します
• すべての例に期待される出力を示します
• ワークフローの例にはエラー処理を含めます

推奨：

• エージェントのライフサイクル、ジョブ／スケジューリング、メモリ／想起、セマンティック検索、ポリシー管理、ワーカー管理、ストリーミングを網羅します
• リソースを調査するだけで、何も実行しない「ワークフロー」の例は掲載しません
• SDK がセッションをサポートしている場合は、複数ターン／セッション管理の例を掲載します

相互参照チェック — 不足が最も蓄積しやすい箇所です：

• 独自の専用ページに例があるサービスすべてについて、該当する例がここにも掲載されているか確認します
• 例が掲載されている元のページを示しながら、不足しているサービスのカテゴリをすべて指摘します

3f. ベストプラクティス

必須：

• 認証／認証情報のセキュリティに関するセクション
• エラー処理／再試行ロジック
• パフォーマンス（バッチ処理、ページネーション、キャッシュ）

推奨：

• 主要なサービス（ワーカー、ジョブ、ポリシー、エージェント）ごとのベストプラクティスのセクション
• リソースのクリーンアップ／コンテキストマネージャー
• コードの整理（型ヒント、再利用可能な関数）
• テストのパターン
• 並行処理／スレッドセーフティに関するガイダンス
• シークレットのローテーション／認証情報のライフサイクル

相互参照チェック：

• 独自のベストプラクティスを定めているサービスページすべてについて、そのパターンがここにも記載されているか確認します
• 並行処理／スレッドセーフティがコーパス全体のどこかで扱われているかを記録します

---

ステップ 4 — 各セクションを採点する

次の基準を使用して、各セクションを 0～100 点で採点します。

スコア	意味
85–100	強い — 必須項目がすべて含まれ、推奨項目の大半も含まれており、不足はほとんどありません
70–84	良好 — 必須項目はすべて含まれていますが、推奨項目の一部が不足しています
50–69	十分 — 必須項目の大半は含まれていますが、目立った不足があります
30–49	弱い — 必須項目が複数不足しています
0–29	不十分 — セクションの内容が表面的であるか、大部分が欠けています

評価ラベルを付けます：強い / 良好 / 十分 / 弱い / 不十分

---

ステップ 5 — 各セクションの不足リストを作成する

不足項目ごとに：

• 欠けている内容を明確な一文で記述します
• コーパス内に該当する内容がある場合は、その場所をタグで示します：[covered in: page-name]
• コーパス内のどこにもない場合は、次のタグを付けます：[not covered anywhere in corpus]

この区別は重要です。どこにもない不足項目には新しいページが必要ですが、別の場所にある場合は相互参照か統合で対応できます。

---

ステップ 6 — 優先度の高い推奨事項を導き出す

影響度 × 工数に基づいて、優先度の高い対応を6～8件ランク付けします。次の順に優先します。

1. 事実誤認／シグネチャの不一致（最優先 — ユーザーの操作失敗につながるため）
2. どこにも記載されていない必須項目の不足
3. 別の場所には記載されているが、リンクされていない必須項目の不足
4. 価値の高い推奨項目の不足
5. 相互参照と統合の機会

---

ステップ 7 — HTML レポートを生成する

assets/report-template.html のテンプレートを読み込み、監査データを挿入します。

以下のプレースホルダーを置き換えます。

• __AUDIT_URL__ → 監査対象の URL
• __PAGES_FETCHED__ → 取得したページの合計数
• __AUDIT_DATE__ → 今日の日付
• __SECTION_DATA_JSON__ → JSON データ（以下のスキーマを参照）
• __PRIORITIES_JSON__ → JSON データ（以下のスキーマを参照）
• __OVERALL_SCORE__ → 6 つのスコアの加重平均を表す整数（0～100）

データスキーマ

{
  "sections": [
    {
      "num": "01",
      "name": "Installation Guide",
      "rating": "Good",
      "score": 74,
      "strengths": ["string", ...],
      "gaps": [
        {
          "text": "Description of the gap",
          "covered_in": ["page-name-1", "page-name-2"],
          "nowhere": false
        }
      ]
    }
  ]
}

不足項目がコーパス内のどこにもない場合は、"nowhere": true、"covered_in": [] を設定します。

{
  "priorities": [
    {
      "rank": 1,
      "text": "Fix X in Y page. The correct form per api-reference is Z.",
      "type": "error"
    }
  ]
}

優先度のタイプは次のとおりです："error"（事実誤認）、"missing"（どこにも記載されていない）、"xref"（別の場所に記載されており、リンクが必要）、"improvement"（推奨項目の不足）。

---

出力

最終レポートを /mnt/user-data/outputs/sdk-audit-report.html に保存し、present_files を使って提示します。

ユーザーには次の内容を伝えます。

• 取得したページ数
• 総合スコアとその意味
• 最も重大な指摘事項

レポート全文をチャットに転載しないでください。ファイルを提示し、簡潔な概要だけを伝えてください。