Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Get Started Free →

HTML Structure Validate Skill · aiskillstore | DecimalAI

aiskillstore/html-structure-validate

SkillScore92Maintained

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

Code Reviewby aiskillstore

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Frontend / UI pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/aiskillstore-html-structure-validate/SKILL.md

decimalai skills pull aiskillstore-html-structure-validate --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/aiskillstore-html-structure-validate/SKILL.md https://app.decimal.ai/s/aiskillstore-html-structure-validate/SKILL.md

Raw file: /s/aiskillstore-html-structure-validate/SKILL.md ↗ · machine-readable summary at /s/aiskillstore-html-structure-validate.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

24 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 7d ago

Yes — +50% lift · at higher cost+143% tokens0% turns92% of whole cases pass with skill (22/24)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-04	✗→✓	▲ Improved	290%	0%
case-09	✗→✓	▲ Improved	135%	0%
case-10	✗→✓	▲ Improved	116%	0%
case-11	✗→✓	▲ Improved	41%	0%
case-12	✗→✓	▲ Improved	484%	0%

Showing 5 of 24 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

aiskillstore / marketplace

skills/abejitsu/html-structure-validate/SKILL.md

View on GitHub ↗

Imported 8/3/2026Version v1

Skill contents

SKILL.md

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

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)

Run validation checks

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

Generate validation report

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

Save validation report as JSON

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

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

html
<!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
<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

html
<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

html
<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

html
<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`

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:

bash
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:

bash
# 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:

User reviews validation report
User identifies issue in AI-generated HTML
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:

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

Next Steps After FAIL

If validation fails:

PIPELINE STOPS
Hook validate-structure.sh triggered
User receives error report with details
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:

bash
# 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

Want to see if aiskillstore/html-structure-validate would activate on your phrasing? Try it before you install — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/22/2026, 05:17 UTC · 24 cases

Lift

+50%

92% vs 42%

Agent turns

0%

1.0 vs 1.0

Tokens

+143%

3,835.45 vs 1,579.23

fail → pass · 12pass → pass · 10fail → fail · 2

Per-case results (24)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Please validate the generated HTML file for chapter 1 page 5 (`output/chapter_01/page_artifacts/page_05/04_page_05.html`). Check whether the page meets all core structural requirements like proper DOCTYPE, matched tags, header links, and body container layout. Save a detailed JSON validation output to the page artifact folder detailing each rule's pass/fail status and warning count, returning a failure signal if any blocking errors are found.	fail→fail	8,472	6,979	-18%	1	1	0%	403	3,701	+818%	0	0	—
case-02 We just finished generating `04_page_08.html` for chapter 2 page 8. Can you execute the HTML structure validator on this file? I want a comprehensive JSON report saved in the artifacts folder containing a timestamped breakdown of all structural checks, error logs, and warnings, along with a pass/fail determination that halts execution if structural criteria aren't met.	fail→fail	5,891	5,666	-4%	1	1	0%	349	3,422	+881%	0	0	—
case-03 We have a stylesheet at `styles/main.css` for our book layout. Check whether this CSS file follows BEM Naming conventions, uses valid custom properties, and passes stylelint checks.	pass→pass	9,494	14,742	+55%	1	1	0%	1,037	5,805	+460%	0	0	—
case-04 Run an accessibility audit on `04_page_02.html` using axe-core or WCAG 2.1 AA screen reader rules to check contrast ratios and screen reader accessibility labels.	fail→pass	8,796	17,074	+94%	1	1	0%	1,684	6,569	+290%	0	0	—
case-05 Analyze the generated HTML text content of `04_page_03.html` to evaluate whether the historical explanation of quantum physics is accurate and pedagogical for high school students.	pass→pass	17,474	15,100	-14%	1	1	0%	2,691	5,510	+105%	0	0	—
case-06 During initial structure testing of a generated page, the viewport meta element is omitted from the document head. Does this trigger a blocking pipeline failure or a non-blocking notification?	pass→pass	8,163	2,502	-69%	1	1	0%	1,230	3,384	+175%	0	0	—
case-07 A generated HTML document in the pipeline lacks the charset meta tag inside the head section. How should the structure checker treat this defect?	pass→pass	9,954	5,095	-49%	1	1	0%	1,674	3,936	+135%	0	0	—
case-08 When running structure checking on a page file where DOCTYPE declaration was omitted entirely, what process exit status should be returned?	pass→pass	7,822	2,278	-71%	1	1	0%	1,227	3,390	+176%	0	0	—
case-09 What specific element container structure inside the body element is required for an HTML page artifact to pass structural validation?	fail→pass	9,584	2,853	-70%	1	1	0%	1,493	3,516	+135%	0	0	—
case-10 An HTML document starts its visible headings with an h2 element instead of an h1. How is this flagged during structural analysis?	fail→pass	9,777	4,510	-54%	1	1	0%	1,732	3,745	+116%	0	0	—
case-11 When validating chapter 3 page 12 artifact `output/chapter_03/page_artifacts/page_12/04_page_12.html`, what exact filename must be used for saving the validation result report?	fail→pass	11,518	2,126	-82%	1	1	0%	2,392	3,374	+41%	0	0	—
case-12 What exact string value must be stored in the validation_type key inside the generated JSON report?	fail→pass	3,704	1,322	-64%	1	1	0%	548	3,200	+484%	0	0	—
case-21 A table element in a page artifact has inconsistent row column counts or broken table tags. What validation result is assigned?	pass→pass	8,164	2,777	-66%	1	1	0%	1,283	3,486	+172%	0	0	—
case-13 When a page artifact fails structural validation, what shell hook script path is triggered to handle the notification?	fail→pass	23,696	1,300	-95%	1	1	0%	3,694	3,233	-12%	0	0	—
case-14 What minimum byte threshold is required for body content during structural validation?	fail→pass	10,153	1,716	-83%	1	1	0%	1,654	3,283	+98%	0	0	—
case-15 If an HTML document has a valid head tag and CSS stylesheet link but lacks a title tag, what validation outcome occurs?	pass→pass	6,051	3,512	-42%	1	1	0%	996	3,653	+267%	0	0	—
case-16 If an unordered list in the page contains three list item opening tags but only two list item closing tags, what check fails?	fail→pass	8,550	3,358	-61%	1	1	0%	1,379	3,586	+160%	0	0	—
case-17 An HTML page artifact includes DOCTYPE, html, head, title, meta charset, and body tags, but lacks a CSS stylesheet link. What validation status is generated?	fail→pass	4,637	3,118	-33%	1	1	0%	807	3,607	+347%	0	0	—
case-18 When strict_mode is set to true during HTML structure validation, how are warnings handled?	pass→pass	11,599	4,990	-57%	1	1	0%	1,688	3,898	+131%	0	0	—
case-19 What summary field keys are present in 06_validation_structure.json to report tag matching and content validity?	fail→pass	11,830	2,402	-80%	1	1	0%	1,801	3,464	+92%	0	0	—
case-20 An img tag in the document has a src attribute but lacks an alt attribute. What severity level does this trigger?	fail→pass	6,732	2,329	-65%	1	1	0%	1,179	3,476	+195%	0	0	—
case-22 After an HTML page artifact successfully passes this initial structure validation gate, what processing step follows next in the multi-page workflow?	fail→pass	11,194	2,941	-74%	1	1	0%	1,648	3,473	+111%	0	0	—
case-23 If an HTML document skips directly from an h1 heading to an h4 heading, what validation result is generated?	pass→pass	6,741	2,786	-59%	1	1	0%	1,065	3,465	+225%	0	0	—
case-24 What word count threshold is checked under Content Structure to verify the main content area has text?	pass→pass	12,292	2,106	-83%	1	1	0%	1,841	3,327	+81%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 24 cases were attempted, and 22 counted toward the lift figure. The other 2 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +50 percentage points is the difference between those two pass rates over the 22 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 41.7%
Pass rate with the skill: 91.7%
Cases attempted: 24
Cases counted toward lift: 22
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/22/2026, 05:17 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Prompt

Run an accessibility audit on `04_page_02.html` using axe-core or WCAG 2.1 AA screen reader rules to check contrast ratios and screen reader accessibility labels.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run92

Live evalNeeds ≥20 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+171% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 7 days ago

Other measured skills in the registry, with their headline benchmark lift.