spb/ultra-sharp-agent-skills Public
Ultra-Sharp Agent Skills — a research-first skill-authoring system + 72 production-ready skills for AI agents.
Python 100%
1---2name: structuring-semantic-html3description: Structures HTML documents semantically — landmarks, heading hierarchy, meaningful lists/tables/figures, and SEO/meta/Open Graph tags. Use when the user asks to write or review the HTML structure of a page, fix heading levels, add landmarks, improve SEO markup or social previews, or decide between a div and a semantic element. Do not use for ARIA attributes, keyboard, or screen-reader work (ensuring-accessibility) or for parsing/editing existing HTML files programmatically (processing-html).4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Structuring Semantic HTML1213## When to use / when NOT to use14- **Use for:** authoring or reviewing page structure — landmarks, headings, sectioning, lists/tables/figures, `<head>` metadata, Open Graph/Twitter cards.15- **Do NOT use for:** ARIA roles/states, focus management, screen-reader testing (→ ensuring-accessibility); programmatic parsing or bulk editing of HTML files (→ processing-html); visual styling.1617## Core rules18191. **One `<main>` per page, every byte of content inside a landmark.**20 - ✅ `<header>` → `<nav>` → `<main>` → `<footer>`, asides in `<aside>`21 - ❌ Content floating in `<body>` between landmark regions22232. **Exactly one `<h1>`; heading levels never skip down.**24 - ✅ `h1 → h2 → h3`, next section starts back at `h2`25 - ❌ `h1 → h3` because the h3 "looks right" — fix size with CSS, not level26273. **Element by meaning, div only when no element carries the meaning.**28 - ✅ `<button>` for actions, `<a href>` for navigation, `<time datetime="2026-08-05">`, `<address>`, `<dl>` for key–value pairs29 - ❌ `<div class="button" onclick=…>`, `<span class="date">`30314. **Tables for data, never for layout; always `<caption>` + `<th scope>`.**32 - ✅ `<table><caption>Q2 revenue</caption><thead><tr><th scope="col">…`33 - ❌ A grid of divs presenting tabular data, or a table used to position content34355. **Sectioning: `<article>` = self-contained/syndicatable, `<section>` = titled thematic group (must contain a heading), `<div>` = styling hook only.**36376. **`<figure>` + `<figcaption>` for any image/chart/code the text refers to.**38 - ✅ `<figure><img src="chart.png" alt="Revenue grew 40% in Q2"><figcaption>Fig 1. Quarterly revenue</figcaption></figure>`39 - ❌ An image and an italic paragraph pretending to be a caption40417. **Minimum viable `<head>`:** `<meta charset="utf-8">`, `<meta name="viewport" content="width=device-width, initial-scale=1">`, unique `<title>` (≤60 chars, page-specific first), `<meta name="description">` (≤160 chars), canonical URL. Add Open Graph (`og:title`, `og:description`, `og:image` 1200×630, `og:url`, `og:type`) and `<meta name="twitter:card" content="summary_large_image">` for any shareable page.42438. **Navigation is a list.**44 - ✅ `<nav aria-label="Main"><ul><li><a …>` (the `aria-label` here names the landmark; deeper ARIA belongs to ensuring-accessibility)45 - ❌ A row of bare `<a>` tags or divs4647## Workflow48491. Outline the content hierarchy first (what is the one h1; what are the sections) — before writing any tags.502. Lay down landmarks, then headings, then flow content, choosing elements by rule 3.513. Fill the `<head>` per rule 7.524. Self-review: exactly one `<h1>`? No skipped heading levels (grep `<h[1-6]` and read the sequence)? All content inside landmarks? Every `<section>` has a heading? Title and description unique and within length?5354## Edge cases & failure modes55- **Single-page apps:** the rules apply to the rendered DOM — verify the hydrated output, not just the template.56- **Multiple h1s from a CMS/theme:** demote all but the page's main topic; adjust sizes in CSS.57- **No semantic element fits** (pure styling wrapper): use `<div>` without guilt — forcing `<section>` everywhere is as wrong as div-soup.58- **Legacy layout tables:** convert to CSS layout only when asked; otherwise flag it and move on.5960## References61Copy-paste page skeletons, meta blocks, and data-table patterns: see [references/patterns.md](references/patterns.md)62