jpskill.com
🛠️ 開発・MCP コミュニティ

html-structure-validate

HTML5の構造と基本的な文法を検証し、問題があればパイプラインを停止させることで、出力品質を一定に保つための品質管理を行うSkill。

📜 元の英語説明(参考)

Validate HTML5 structure and basic syntax. BLOCKING quality gate - stops pipeline if validation fails. Ensures deterministic output quality.

🇯🇵 日本人クリエイター向け解説

一言でいうと

HTML5の構造と基本的な文法を検証し、問題があればパイプラインを停止させることで、出力品質を一定に保つための品質管理を行うSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⚡ おすすめ: コマンド1行でインストール(60秒)

下記のコマンドをコピーしてターミナル(Mac/Linux)または PowerShell(Windows)に貼り付けてください。 ダウンロード → 解凍 → 配置まで全自動。

🍎 Mac / 🐧 Linux 
mkdir -p ~/.claude/skills && cd ~/.claude/skills && curl -L -o html-structure-validate.zip https://jpskill.com/download/16962.zip && unzip -o html-structure-validate.zip && rm html-structure-validate.zip
🪟 Windows (PowerShell) 
$d = "$env:USERPROFILE\.claude\skills"; ni -Force -ItemType Directory $d | Out-Null; iwr https://jpskill.com/download/16962.zip -OutFile "$d\html-structure-validate.zip"; Expand-Archive "$d\html-structure-validate.zip" -DestinationPath $d -Force; ri "$d\html-structure-validate.zip"

完了後、Claude Code を再起動 → 普通に「動画プロンプト作って」のように話しかけるだけで自動発動します。

💾 手動でダウンロードしたい(コマンドが難しい人向け)
  1. 1. 下の青いボタンを押して html-structure-validate.zip をダウンロード
  2. 2. ZIPファイルをダブルクリックで解凍 → html-structure-validate フォルダができる
  3. 3. そのフォルダを C:\Users\あなたの名前\.claude\skills\(Win)または ~/.claude/skills/(Mac)へ移動
  4. 4. Claude Code を再起動
⬇ .zip でダウンロード(推奨) ⬇ .skill 形式(上級者用) 元のソース ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

  1. 1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
  2. 2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
  3. 3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
    • · macOS / Linux: ~/.claude/skills/
    • · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →
最終更新
2026-05-18
取得日時
2026-05-18
同梱ファイル
1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

HTML Structure Validate Skill

目的

このスキルは、生成された HTML が最低限の構造要件を満たしていることを保証するBLOCKING quality gateです。これは、確率的な AI 生成出力に対する最初の決定論的な検証です。

このスキルは以下をチェックします。

  • HTML5 compliance - 適切な DOCTYPE、タグ
  • Tag closure - すべてのタグが適切に閉じられているか
  • Required elements - メタタグ、スタイルシートのリンク
  • Well-formedness - 有効な構造

検証に失敗した場合、パイプラインはSTOPし、ユーザーに通知するためのフックをトリガーします。

これは、Python validates, ensuring deterministic qualityという原則を強制します。

実行内容

  1. 検証する HTML ファイルをロード

    • AI スキルによって生成された 04_page_XX.html を読み込みます。
    • ファイルが存在し、読み取り可能であることを確認します。
    • ファイルがテキスト（バイナリではない）であることを確認します。

  2. 検証チェックを実行

    • HTML5 の構造コンプライアンスをチェックします。
    • タグの閉じを検証します。
    • head セクションを検証します。
    • 必要な CSS リンクをチェックします。
    • ページコンテナの構造を検証します。

  3. 検証レポートを生成

    • 実行されたすべてのチェックを文書化します。
    • 見つかったエラーをすべてリストします。
    • 警告（非ブロッキング）を記録します。
    • 情報提供的な調査結果を記録します。

  4. 検証レポートを JSON として保存

    • 保存先: output/chapter_XX/page_artifacts/page_YY/06_validation_structure.json
    • タイムスタンプを含めます。
    • すべてのチェック結果を含めます。

  5. 適切なコードで終了

    • VALID の場合は 0 を返します（パイプラインを続行）。
    • INVALID の場合は 1 を返します（パイプラインを STOP し、フックをトリガー）。

入力パラメータ

html_file: <str>         - 04_page_XX.html へのパス
output_dir: <str>        - 検証レポートのディレクトリ
strict_mode: <bool>      - true の場合、警告も失敗とみなします (デフォルト: false)
page_number: <int>       - ページ番号 (レポート用)
chapter: <int>           - 章番号 (レポート用)

検証チェック

チェック 1: DOCTYPE 宣言

要件: ファイルは適切な DOCTYPE で始まる必要があります。

<!DOCTYPE html>

チェック:

  • [ ] ファイルに <!DOCTYPE html> が含まれている (大文字と小文字を区別しない)
  • [ ] DOCTYPE はどのタグよりも前に現れる
  • [ ] DOCTYPE は最初の行または先頭付近にある

エラーとなる場合: DOCTYPE がないか、正しくない場合

チェック 2: HTML タグ

要件: 適切な <html> 開始タグと終了タグ

<html lang="en">
    ...
</html>

チェック:

  • [ ] <html> タグが存在する
  • [ ] </html> 終了タグが存在する
  • [ ] タグが適切にペアになっている
  • [ ] 閉じられていない <html> タグがない

エラーとなる場合: いずれかのタグがないか、適切にペアになっていない場合

チェック 3: Head セクション

要件: メタデータを含む完全な <head> セクション

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>...</title>
    <link rel="stylesheet" href="../../styles/main.css">
</head>

チェック:

  • [ ] <head> および </head> タグが存在する
  • [ ] <meta charset="UTF-8"> が存在する
  • [ ] <meta name="viewport"> が存在する (ない場合は警告)
  • [ ] コンテンツを含む <title> タグが存在する
  • [ ] href 属性を持つ CSS <link> タグが存在する

エラーとなる場合: charset、title、または CSS リンクがない場合 警告となる場合: viewport メタタグがない場合

チェック 4: Body セクション

要件: コンテンツを含む適切な <body> タグ

<body>
    <div class="page-container">
        <main class="page-content">
            ...
        </main>
    </div>
</body>

チェック:

  • [ ] <body> および </body> タグが存在する
  • [ ] <div class="page-container"> が存在する
  • [ ] コンテナ内に <main class="page-content"> が存在する
  • [ ] Body に実質的なコンテンツが含まれている (> 100 バイト)

エラーとなる場合: タグまたは必要なコンテナ div がない場合

チェック 5: タグの閉じの検証

要件: すべてのタグが適切に閉じられている必要があります。

チェック対象:

  • 一致しない開始タグ (例: </p> のない <p>)
  • 不適切なネスト (例: <p><h2>text</h2></p>)
  • 自己終了タグが正しく使用されている (例: <br/>, <img/>)
  • コメントブロックが適切にフォーマットされている (<!-- -->)

検証方法:

  • HTML をツリー構造に解析します。
  • すべてのノードが適切に一致していることを確認します。
  • ネストが HTML5 のルールに違反していないかチェックします。

エラーとなる場合: 一致しないタグまたは不適切にネストされたタグがある場合

チェック 6: 見出しタグ (h1-h6)

要件: 有効な見出し階層

<h1>Chapter Title</h1>
<h2>Section Heading</h2>
<h3>Subsection</h3>

チェック:

  • [ ] すべての見出しタグが適切に閉じられている
  • [ ] 最初の見出しは h1 である必要がある (そうでない場合は警告)
  • [ ] 見出しレベルが劇的にスキップしない (h1 → h4 は疑わしい)
  • [ ] すべての見出しにテキストコンテンツがある (空ではない)

エラーとなる場合: 見出しタグが適切に閉じられていない場合 警告となる場合: 疑わしい階層の場合

チェック 7: コンテンツ構造

要件: ページコンテナ内の意味のあるコンテンツ

チェック:

  • [ ] <main class="page-content"> に要素が含まれている
  • [ ] コンテンツに見出しまたは段落が含まれている
  • [ ] 完全に空のコンテンツ領域がない
  • [ ] テキストノードまたは要素が存在する (合計 > 100 語)

エラーとなる場合: コンテンツがないか、空の構造の場合

チェック 8: リストの整合性

要件: すべてのリストが適切に構造化されている

各 <ul> または <ol> についてチェック:

  • [ ] リストの開始タグと終了タグが一致している
  • [ ] リストに <li> 要素が含まれている
  • [ ] すべての <li> タグが適切に閉じられている
  • [ ] <li> の数が開始/終了ペアと一致している
  • [ ] 不適切に閉じられたネストされた <ul> または <ol> がない

エラーとなる場合: 空のリストまたは一致しない <li> タグがある場合

チェック 9: 画像タグとリンクタグ

要件: 自己終了タグが適切にフォーマットされている

チェック:

  • [ ] すべての <img> タグに src および alt 属性がある
  • [ ] すべての <a> タグに有効な href 属性がある
  • [ ] 画像パスに明らかなエラーがない (壊れた構文がない)
  • [ ] 自己終了タグが適切な構文を使用している

警告となる場合: 画像に alt テキストがないか、リンクに href がない場合

チェック 10: テーブルタグ (存在する場合)

要件: 適切なテーブル構造

チェック:

  • [ ] <table>, <tr>, <td>, <th> タグが適切にネストされている
  • [ ] すべての行に一貫した列数がある
  • [ ] テーブルヘッダーとボディが適切に構造化されている

エラーとなる場合: 不正なテーブル構造の場合

検証レポートの形式

出力: 06_validation_structure.json



(原文がここで切り詰められています)
📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

HTML Structure Validate Skill

Purpose

This skill is a BLOCKING quality gate that ensures generated HTML meets minimum structural requirements. It is the first deterministic validation of probabilistic AI-generated output.

The skill checks:

  • HTML5 compliance - Proper DOCTYPE, tags
  • Tag closure - All tags properly closed
  • Required elements - Meta tags, stylesheet links
  • Well-formedness - Valid structure

If validation fails, the pipeline STOPS and triggers a hook to notify the user.

This enforces the principle: Python validates, ensuring deterministic quality.

What to Do

  1. Load HTML file to validate

    • Read 04_page_XX.html generated by AI skill
    • Verify file exists and is readable
    • Confirm file is text (not binary)

  2. Run validation checks

    • Check HTML5 structure compliance
    • Verify tag closure
    • Validate head section
    • Check required CSS link
    • Validate page container structure

  3. Generate validation report

    • Document all checks performed
    • List any errors found
    • Note warnings (non-blocking)
    • Record informational findings

  4. Save validation report as JSON

    • Save to: output/chapter_XX/page_artifacts/page_YY/06_validation_structure.json
    • Include timestamp
    • Include all check results

  5. Exit with appropriate code

    • Return 0 if VALID (continue pipeline)
    • Return 1 if INVALID (STOP pipeline, trigger hook)

Input Parameters

html_file: <str>         - Path to 04_page_XX.html
output_dir: <str>        - Directory for validation report
strict_mode: <bool>      - If true, warnings also fail (default: false)
page_number: <int>       - Page number (for reporting)
chapter: <int>           - Chapter number (for reporting)

Validation Checks

Check 1: DOCTYPE Declaration

Requirement: File must start with proper DOCTYPE

<!DOCTYPE html>

Check:

  • [ ] File contains <!DOCTYPE html> (case-insensitive)
  • [ ] DOCTYPE appears before any tags
  • [ ] DOCTYPE is on first line or near beginning

Error if: Missing or incorrect DOCTYPE

Check 2: HTML Tags

Requirement: Proper <html> opening and closing tags

<html lang="en">
    ...
</html>

Checks:

  • [ ] <html> tag present
  • [ ] </html> closing tag present
  • [ ] Tags are properly paired
  • [ ] No unclosed <html> tags

Error if: Missing either tag or improperly paired

Check 3: Head Section

Requirement: Complete <head> section with metadata

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>...</title>
    <link rel="stylesheet" href="../../styles/main.css">
</head>

Checks:

  • [ ] <head> and </head> tags present
  • [ ] <meta charset="UTF-8"> present
  • [ ] <meta name="viewport"> present (warning if missing)
  • [ ] <title> tag with content present
  • [ ] CSS <link> tag present with href attribute

Error if: Missing charset, title, or CSS link Warning if: Missing viewport meta tag

Check 4: Body Section

Requirement: Proper <body> tags with content

<body>
    <div class="page-container">
        <main class="page-content">
            ...
        </main>
    </div>
</body>

Checks:

  • [ ] <body> and </body> tags present
  • [ ] <div class="page-container"> present
  • [ ] <main class="page-content"> present inside container
  • [ ] Body contains substantial content (> 100 bytes)

Error if: Missing tags or required container divs

Check 5: Tag Closure Validation

Requirement: All tags must be properly closed

Checks for:

  • Unmatched opening tags (e.g., <p> without </p>)
  • Improper nesting (e.g., <p><h2>text</h2></p>)
  • Self-closing tags used correctly (e.g., <br/>, <img/>)
  • Comment blocks properly formatted (<!-- -->)

Validation method:

  • Parse HTML into tree structure
  • Verify all nodes properly matched
  • Check nesting doesn't violate HTML5 rules

Error if: Any unmatched or improperly nested tags

Check 6: Heading Tags (h1-h6)

Requirement: Valid heading hierarchy

<h1>Chapter Title</h1>
<h2>Section Heading</h2>
<h3>Subsection</h3>

Checks:

  • [ ] All heading tags properly closed
  • [ ] First heading should be h1 (warning if not)
  • [ ] Heading levels don't skip dramatically (h1 → h4 is suspicious)
  • [ ] All headings have text content (not empty)

Error if: Heading tags improperly closed Warning if: Suspicious hierarchy

Check 7: Content Structure

Requirement: Meaningful content in page container

Checks:

  • [ ] <main class="page-content"> contains elements
  • [ ] Content includes headings or paragraphs
  • [ ] No completely empty content area
  • [ ] Text nodes or elements present (> 100 words total)

Error if: No content or empty structure

Check 8: List Integrity

Requirement: All lists properly structured

Checks for each <ul> or <ol>:

  • [ ] List opening and closing tags matched
  • [ ] List contains <li> elements
  • [ ] All <li> tags properly closed
  • [ ] <li> count matches opening/closing pairs
  • [ ] No nested <ul> or <ol> improperly closed

Error if: Empty lists or unmatched <li> tags

Check 9: Image and Link Tags

Requirement: Self-closing tags properly formatted

Checks:

  • [ ] All <img> tags have src and alt attributes
  • [ ] All <a> tags have valid href attributes
  • [ ] Image paths don't have obvious errors (no broken syntax)
  • [ ] Self-closing tags use proper syntax

Warning if: Images missing alt text or links missing href

Check 10: Table Tags (if present)

Requirement: Proper table structure

Checks:

  • [ ] <table>, <tr>, <td>, <th> tags properly nested
  • [ ] All rows have consistent column counts
  • [ ] Table headers and body properly structured

Error if: Malformed table structure

Validation Report Format

Output: 06_validation_structure.json

{
  "page": 16,
  "book_page": 17,
  "chapter": 2,
  "validation_type": "structure",
  "validation_timestamp": "2025-11-08T14:34:00Z",
  "overall_status": "PASS",
  "error_count": 0,
  "warning_count": 1,
  "checks_performed": [
    {
      "check_name": "DOCTYPE Declaration",
      "status": "PASS",
      "details": "Valid HTML5 DOCTYPE found"
    },
    {
      "check_name": "HTML Tags",
      "status": "PASS",
      "details": "Proper <html> opening and closing tags"
    },
    {
      "check_name": "Head Section",
      "status": "PASS",
      "details": "All required meta tags and title present"
    },
    {
      "check_name": "Body Section",
      "status": "PASS",
      "details": "Body and content structure valid"
    },
    {
      "check_name": "Tag Closure",
      "status": "PASS",
      "details": "All tags properly matched and closed"
    },
    {
      "check_name": "Heading Hierarchy",
      "status": "PASS",
      "details": "4 headings found, proper h1-h4 hierarchy"
    },
    {
      "check_name": "Content Structure",
      "status": "PASS",
      "details": "Main content area contains 245 words across 3 paragraphs"
    },
    {
      "check_name": "List Integrity",
      "status": "PASS",
      "details": "1 list with 3 items, all properly formed"
    },
    {
      "check_name": "Image Tags",
      "status": "PASS",
      "details": "No images on this page"
    },
    {
      "check_name": "Table Tags",
      "status": "PASS",
      "details": "No tables on this page"
    }
  ],
  "errors": [],
  "warnings": [
    {
      "check": "Heading Hierarchy",
      "message": "First heading is h2, typically should be h1 for page opening",
      "severity": "LOW"
    }
  ],
  "summary": {
    "total_checks": 10,
    "passed": 9,
    "failed": 0,
    "warnings": 1,
    "html_valid": true,
    "tags_matched": true,
    "content_substantial": true
  }
}

Validation Rules

PASS Criteria

  • DOCTYPE present and valid
  • All required tags (html, head, body, main, div.page-container) present
  • All tags properly closed and matched
  • Title tag with content
  • CSS stylesheet link present
  • Content structure valid
  • No structural errors

FAIL Criteria (BLOCKS PIPELINE)

  • Missing DOCTYPE
  • Missing required tags
  • Unmatched or improperly nested tags
  • Missing title or CSS link
  • Empty content
  • Malformed lists or tables

WARNING (Logged but doesn't block)

  • Missing viewport meta tag
  • First heading is not h1
  • Large heading jumps (h1 → h4)
  • Missing alt text on images
  • Missing href on links

Implementation: Using Python Script

This validation is performed by existing validate_html.py tool, run in structure validation mode:

cd Calypso/tools

# Validate single page HTML
python3 validate_html.py \
  ../output/chapter_02/page_artifacts/page_16/04_page_16.html \
  --output-json ../output/chapter_02/page_artifacts/page_16/06_validation_structure.json \
  --strict-structure

# Exit code:
# 0 = VALID (continue to next skill)
# 1 = INVALID (STOP pipeline)

Hook Integration

When validation FAILS:

# Trigger hook: .claude/hooks/validate-structure.sh
# Receives:
#   - Page number
#   - HTML file path
#   - Validation report path
#   - Error details

# Hook behavior:
# - Log failure with details
# - Save error report
# - Notify user
# - STOP pipeline (no further processing)

Error Recovery

If validation fails:

  1. User reviews validation report
  2. User identifies issue in AI-generated HTML
  3. Options:
    • Fix HTML manually and re-validate
    • Re-run AI generation with improved prompt
    • Review source extraction data for errors
    • Proceed with caution (expert override)

Quality Metrics

Validation provides metrics:

  • Percentage of checks passing
  • Error severity levels
  • Content size (word count, element count)
  • Structure complexity

These metrics feed into final quality reports.

Success Criteria

✓ Validation completes successfully ✓ All structural checks pass (0 errors) ✓ Validation report saved in JSON format ✓ Exit code 0 returned (or 1 if invalid) ✓ Clear error messages if validation fails

Next Steps After PASS

If validation passes:

  1. All pages of chapter processed through this gate
  2. Skill 4 (consolidate pages) merges individual page HTMLs
  3. Quality Gate 2 (semantic validate) checks semantic structure
  4. Continue through validation pipeline

Next Steps After FAIL

If validation fails:

  1. PIPELINE STOPS
  2. Hook validate-structure.sh triggered
  3. User receives error report with details
  4. User must fix issues and retry

Design Notes

  • This is the first deterministic quality gate
  • Uses proven validate_html.py tool
  • Catches structural issues before semantic analysis
  • Provides clear, actionable error messages
  • Essential for ensuring pipeline reliability

Testing

To test structure validation:

# Test with known-good HTML
python3 validate_html.py ../output/chapter_01/chapter_01.html

# Should show: ✓ VALID

# Test with invalid HTML (if needed)
python3 validate_html.py broken_html.html

# Should show: ✗ INVALID with specific errors