HTML SEO レビュー
概要
1つ以上の静的HTMLファイルに対して、実行可能で重要度順にランク付けされた問題点リストを生成します。このスキルは、stdlibのみで動作するHTMLパーサー（すべてのSEO関連シグナルを単一のJSONドキュメントに抽出）、包括的なルーブリック、および問題報告テンプレートをバンドルしており、監査を毎回予測可能な出力で実行できます。
使用するタイミング
入力が1つ以上の静的.htmlファイル（またはそれらのディレクトリ）であり、ユーザーが実行可能なオンページSEOの問題点を求めている場合に使用します。トリガーとなるフレーズは「SEOレビュー」、「SEO監査」、「このHTMLのSEOをチェック」、「このページのメタタグをレビュー」、「オンページSEOを監査」などです。
以下の場合は使用しないでください:
- アーティファクトが静的サイトジェネレーター（Jekyll/Hugo/Astro/Eleventy/Next.js）のソースである場合。それらはソースを認識したレビューが必要です。将来の
ssg-seo-reviewスキルに委ねてください。 - ユーザーがライブパフォーマンスメトリクス（LCP、CLS、INP）を求めている場合。HTMLだけではこれらを生成できません。LighthouseまたはPageSpeed Insightsを推奨してください。
- ユーザーがバックリンク、ドメインオーソリティ、またはその他のオフページ分析を求めている場合。これにはサードパーティ製ツール（Ahrefs、SEMrushなど）が必要です。
ワークフロー
1. シグナルの抽出
対象に対してパーサーを実行します。単一のファイルまたはディレクトリ（再帰的に *.html を検索）を受け入れます。
python3 scripts/extract_seo_signals.py <path> --pretty
出力は、lang、title、meta、links、scripts、headings、images、links_audit、body_word_count というトップレベルキーを持つJSONドキュメントです。各要素には、問題点で引用するための line 番号が含まれています。
ディレクトリの場合、出力は {"files": [<ファイルごとのオブジェクト>]} となります。
スクリプトはPythonの標準ライブラリのみを使用します。pip install は必要ありません。特定のファイルの解析に失敗した場合、そのファイルの結果には error フィールドが含まれ、監査は残りのファイルで続行されます。
2. シグナルをルーブリックにマッピング
references/seo-checklist.md を読み込みます。各セクションを順に確認し、対応するJSONパスをチェックします。ルーブリックには、すべてのチェック項目について検査するパスが明示的にリストされています（例：images.missing_alt、meta.description.length、scripts.render_blocking_candidates）。
各チェックが失敗した場合、以下を記録します:
- ルーブリックからの重要度（P0/P1/P2/P3）
- JSON出力からの行番号
- ファイルからの正確に引用されたマークアップまたは属性値（行番号を使用してファイルを再読み込みし、逐語的に引用します。言い換えは絶対にしないでください）
- 修正方法。変更が機械的な場合は、具体的なbefore/afterの差分として記述します。
3. 報告前に各問題点を検証
問題点を報告する前に、問題を機械的に確認します:
- 属性が「欠落している」という主張は、HTMLをざっと読んだ結果ではなく、パーサーの構造化出力に基づいている必要があります。
- 値が「短すぎる/長すぎる」という主張は、JSONからの実際の文字数を引用する必要があります。
- 引用されたマークアップは正確でなければなりません。引用をファイルから一字一句再現できない場合は、その引用を破棄します。
これにより、実際には存在しない問題を作り出すという、最も一般的なレビューの失敗を防ぎます。
4. 問題報告書の作成
assets/findings-template.md を構造として使用します。以下を記入します:
- 全体的な評価と重要度カウントを含む要約段落。
- 問題点ごとに1ブロック。重要度順（P0 → P3）、次にファイル順で並べ替えます。
- 問題点の数が10程度を超える場合は、オプションの「クイックウィン」セクション。レバレッジの高い修正を3～5つ選びます。
- 「対象外の項目」セクション。ユーザーが外部ツール（実際のCWVにはLighthouse、正規URLの解決にはcurlなど）でフォローアップすべきものをリストします。
監査が複数のファイルにわたる場合は、ファイルごとに重要度階層内で問題点をグループ化した1つのレポートを作成します。ファイルごとに1つのレポートではありません。
5. 適切にスキップ
パーサーが生成できない情報（例：「この正規URLは200を返していますか？」）が必要なチェックの場合は、推測しないでください。レポートの「対象外の項目」セクションにそれを記載して次に進みます。
参考
scripts/extract_seo_signals.py— HTMLパーサー。stdlibのみ。行番号付きの構造化JSONを出力します。references/seo-checklist.md— 完全なルーブリック。カテゴリ別に整理され、すべてのチェックの重要度とJSONパスが含まれています。assets/findings-template.md— 監査レポートの出力形式。