Agent skill

semantic-html

Semantic HTML5 markup patterns for meaningful, accessible, and SEO-optimized content structure

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/pluginagentmarketplace/custom-plugin-html/tree/main/skills/semantic-html

SKILL.md

Semantic HTML Skill

Transform markup from presentation-focused to meaning-focused, enabling accessibility, SEO, and AI/voice interface compatibility.

🎯 Purpose

Provide atomic, single-responsibility operations for:

  • Document outline and structure semantics
  • Content sectioning (<article>, <section>, <nav>)
  • Landmark roles and ARIA mapping
  • Microdata and structured data hints
  • SEO and accessibility improvements

📥 Input Schema

typescript
interface SemanticHtmlInput {
  operation: 'analyze' | 'convert' | 'validate' | 'suggest';
  content_type: ContentType;
  markup?: string;           // Existing HTML to analyze/convert
  context?: {
    page_type: 'homepage' | 'article' | 'product' | 'contact' | 'search';
    has_sidebar: boolean;
    has_comments: boolean;
  };
  options?: {
    semantic_level: 'strict' | 'moderate' | 'minimal';
    include_landmarks: boolean;
    preserve_classes: boolean;
  };
}

type ContentType =
  | 'article'     // Blog post, news article
  | 'navigation'  // Nav menus, breadcrumbs
  | 'sidebar'     // Aside content
  | 'header'      // Page/section headers
  | 'footer'      // Page/section footers
  | 'section'     // Generic thematic sections
  | 'figure'      // Images, diagrams, code blocks
  | 'list'        // Lists of items
  | 'table';      // Tabular data

📤 Output Schema

typescript
interface SemanticHtmlOutput {
  success: boolean;
  markup: string;
  semantic_score: number;      // 0-100
  improvements: Improvement[];
  landmark_map: LandmarkMap;
  outline: DocumentOutline;
}

interface Improvement {
  original: string;
  suggested: string;
  reason: string;
  impact: 'critical' | 'high' | 'medium' | 'low';
}

🛠️ Core Operations

1. Semantic Element Selection

┌─────────────────────────────────────────────────────────────┐
│                    Semantic Element Decision Tree            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Is it the main content?                                     │
│  └── Yes → <main>                                            │
│  └── No ↓                                                    │
│                                                              │
│  Is it independently distributable?                          │
│  └── Yes → <article>                                         │
│  └── No ↓                                                    │
│                                                              │
│  Is it a thematic grouping with a heading?                   │
│  └── Yes → <section>                                         │
│  └── No ↓                                                    │
│                                                              │
│  Is it navigation links?                                     │
│  └── Yes → <nav>                                             │
│  └── No ↓                                                    │
│                                                              │
│  Is it tangentially related content?                         │
│  └── Yes → <aside>                                           │
│  └── No ↓                                                    │
│                                                              │
│  Is it introductory or navigational content?                 │
│  └── Yes → <header>                                          │
│  └── No ↓                                                    │
│                                                              │
│  Is it footer/meta information?                              │
│  └── Yes → <footer>                                          │
│  └── No → <div>                                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

2. Landmark Mapping

HTML5 Element ARIA Landmark Role Implicit Role
<header> (page) banner Yes
<nav> navigation Yes
<main> main Yes
<aside> complementary Yes
<footer> (page) contentinfo Yes
<section> region If has accessible name
<article> article Yes
<form> form If has accessible name

3. Page Structure Patterns

Blog/Article Page

html
<body>
  <header>
    <nav aria-label="Main">...</nav>
  </header>

  <main>
    <article>
      <header>
        <h1>Article Title</h1>
        <p>By <a rel="author" href="/author">Author</a></p>
        <time datetime="2025-01-15">January 15, 2025</time>
      </header>

      <section aria-labelledby="intro">
        <h2 id="intro">Introduction</h2>
        <p>Content...</p>
      </section>

      <section aria-labelledby="main-content">
        <h2 id="main-content">Main Content</h2>
        <p>Content...</p>
      </section>

      <footer>
        <p>Tags: <a href="/tag/html" rel="tag">HTML</a></p>
      </footer>
    </article>

    <aside aria-label="Related articles">
      <h2>Related Articles</h2>
      <ul>...</ul>
    </aside>
  </main>

  <footer>
    <nav aria-label="Footer">...</nav>
    <p>&copy; 2025</p>
  </footer>
</body>

E-commerce Product Page

html
<body>
  <header>
    <nav aria-label="Main">...</nav>
    <nav aria-label="Breadcrumb">
      <ol>
        <li><a href="/">Home</a></li>
        <li><a href="/products">Products</a></li>
        <li><a href="/products/widgets" aria-current="page">Widget</a></li>
      </ol>
    </nav>
  </header>

  <main>
    <article itemscope itemtype="https://schema.org/Product">
      <h1 itemprop="name">Product Name</h1>

      <figure>
        <img itemprop="image" src="product.jpg" alt="Product description">
      </figure>

      <section aria-labelledby="description">
        <h2 id="description">Description</h2>
        <p itemprop="description">Product details...</p>
      </section>

      <section aria-labelledby="pricing">
        <h2 id="pricing">Pricing</h2>
        <p itemprop="offers" itemscope itemtype="https://schema.org/Offer">
          <span itemprop="price" content="29.99">$29.99</span>
        </p>
      </section>
    </article>

    <aside aria-label="Related products">
      <h2>You May Also Like</h2>
      <ul>...</ul>
    </aside>
  </main>

  <footer>...</footer>
</body>

⚠️ Error Handling

Error Codes

Code Description Recovery
SH001 Missing document outline Add proper heading hierarchy
SH002 No main landmark Wrap primary content in <main>
SH003 Multiple main elements Keep only one <main>
SH004 Section without heading Add heading or use <div>
SH005 Article without heading Add <h1>-<h6>
SH006 Nav without label Add aria-label
SH007 Div soup detected Suggest semantic alternatives

Recovery Procedures

Analyze Input → Identify Anti-Patterns → Suggest Fixes → Validate → Report
       ↓
 [If conversion requested]
       ↓
 Apply automatic fixes → Re-validate → Return improved markup

🔍 Troubleshooting

Problem: Screen reader announces wrong structure

Debug Checklist:
□ Is <main> present and unique?
□ Are headings in logical order (h1→h2→h3)?
□ Do sections have accessible names?
□ Are nav elements labeled uniquely?
□ Is banner/contentinfo outside main?

Problem: SEO not picking up content structure

Debug Checklist:
□ Is <article> used for main content?
□ Is author/date marked with rel/datetime?
□ Are headings used (not just styled divs)?
□ Is structured data (schema.org) present?
□ Are images in <figure> with <figcaption>?

Problem: "Div soup" - too many divs

Conversion Guide:
<div class="header">      → <header>
<div class="nav">         → <nav>
<div class="main">        → <main>
<div class="article">     → <article>
<div class="sidebar">     → <aside>
<div class="footer">      → <footer>
<div class="section">     → <section>
<div class="figure">      → <figure>

📊 Semantic Score Calculation

Factor Weight Measurement
Landmark coverage 25% banner, main, contentinfo present
Heading hierarchy 25% Correct h1→h6 nesting
Semantic ratio 20% semantic / (semantic + div + span)
Accessible names 15% Labeled sections and navs
Article structure 15% Proper article markup

Score Interpretation:

  • 90-100: Excellent semantic structure
  • 70-89: Good, minor improvements possible
  • 50-69: Moderate, significant improvements needed
  • <50: Poor, major restructuring required

📋 Usage Examples

yaml
# Analyze existing markup
skill: semantic-html
operation: analyze
markup: "<div class='main'><div class='post'>...</div></div>"

# Convert to semantic HTML
skill: semantic-html
operation: convert
content_type: article
markup: "<div class='blog-post'>...</div>"
options:
  semantic_level: strict
  include_landmarks: true

# Suggest improvements
skill: semantic-html
operation: suggest
content_type: navigation
context:
  page_type: homepage
  has_sidebar: true

🔗 References

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

pluginagentmarketplace/custom-plugin-html

html-basics

Core HTML5 elements, document structure, and foundational markup patterns

1 0
Explore
pluginagentmarketplace/custom-plugin-html

accessibility

WCAG 2.2 AA compliance, ARIA patterns, screen reader compatibility, and inclusive design patterns

1 0
Explore
pluginagentmarketplace/custom-plugin-html

forms

HTML5 forms, Constraint Validation API, accessible form patterns, and modern input types

1 0
Explore
pluginagentmarketplace/custom-plugin-ai-data-scientist

deep-learning

Neural networks, CNNs, RNNs, Transformers with TensorFlow and PyTorch. Use for image classification, NLP, sequence modeling, or complex pattern recognition.

4 1
Explore
pluginagentmarketplace/custom-plugin-ai-data-scientist

model-optimization

Quantization, pruning, AutoML, hyperparameter tuning, and performance optimization. Use for improving model performance, reducing size, or automated ML.

4 1
Explore
pluginagentmarketplace/custom-plugin-ai-data-scientist

mlops-deployment

Docker, Kubernetes, CI/CD, model monitoring, and cloud platforms. Use for deploying ML models to production, setting up pipelines, or infrastructure.

4 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results