# semantic-html-and-seo
A skill that steers your coding agent toward semantic HTML5, proper meta tags, alt text and progressive enhancement. Useful when you build UI or review existing markup.
- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 901 installs · ★ 165
- Author: dembrandt
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dembrandt/dembrandt-skills/tree/HEAD/skills/semantic-html-and-seo/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/semantic-html-and-seo
## What it does
The skill activates while the agent writes or audits page markup. It lays out document structure rules: `header`, `nav`, `main`, `article`, `section`, `aside`, `footer`, a single `h1` per page, and heading levels that never skip. For anything clickable it pushes the native element over a `div` with ARIA bolted on.
Images get their own section. Every `` needs an `alt`, and what goes inside depends on the image's job: describe an informative one, leave a decorative one empty, pair a complex chart with a caption in `figcaption`. Then come the meta tags — `title` at 50–60 characters, `description` at 120–160, a canonical URL, Open Graph and Twitter cards, and JSON-LD blocks with types such as `Product` and `FAQPage`.
Progressive enhancement is covered as layers: content and forms must work without JavaScript, and scripts only improve on that. On SPAs the skill is blunt — single-page apps break browser defaults that search and accessibility rely on, so you fix them by hand. It triggers on path patterns `**/*.html`, `**/*.tsx`, `**/*.vue`, `**/*.svelte` and the `app/**`, `pages/**`, `src/**` folders, so a project without those files never wakes it up.
## Install
### Claude Code (native platform)
1. **Skills CLI (Vercel)**
```bash
npx skills add dembrandt/dembrandt-skills --skill semantic-html-and-seo -a claude-code
```
2. **Manually: put the files in place**
- File: `~/.claude/skills/semantic-html-and-seo/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/semantic-html-and-seo/
### Codex
1. **Skills CLI (Vercel)**
```bash
npx skills add dembrandt/dembrandt-skills --skill semantic-html-and-seo -a codex
```
2. **Manually: put the files in place**
- File: `.agents/skills/semantic-html-and-seo/SKILL.md` — For all projects use ~/.agents/skills/
### Cursor
1. **Skills CLI (Vercel)**
```bash
npx skills add dembrandt/dembrandt-skills --skill semantic-html-and-seo -a cursor
```
2. **Manually: put the files in place**
- File: `.cursor/skills/semantic-html-and-seo/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/
### GitHub Copilot
1. **GitHub CLI**
```bash
gh skill install dembrandt/dembrandt-skills semantic-html-and-seo
```
2. **Manually: put the files in place**
- File: `.github/skills/semantic-html-and-seo/SKILL.md`
### Gemini CLI
1. **Skills CLI (Vercel)**
```bash
npx skills add dembrandt/dembrandt-skills --skill semantic-html-and-seo -a gemini-cli
```
2. **Platform CLI**
```bash
gemini skills install https://github.com/dembrandt/dembrandt-skills --path skills/semantic-html-and-seo
```
### Windsurf (Devin Desktop)
**Manually: put the files in place**
- File: `.devin/skills/semantic-html-and-seo/SKILL.md` — The legacy .windsurf/skills/ path still works
### OpenCode
**Skills CLI (Vercel)**
```bash
npx skills add dembrandt/dembrandt-skills --skill semantic-html-and-seo -a opencode
```
### Claude.ai
**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills
Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dembrandt/dembrandt-skills/tree/HEAD/skills/semantic-html-and-seo/SKILL.md
## When to use it
- replace div wrappers with semantic page structure
- write alt text for every image on a page
- set up meta tags and Open Graph for link sharing
- add JSON-LD so search shows a rich snippet
- make a single-page app readable for crawlers and screen readers
## Example prompts
- add proper meta tags to this page
- write semantic html for this component
- how do I make this SPA SEO friendly
## Source text · SKILL.md · MIT
Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c25c2152c0e900ab.
BEGIN THIRD-PARTY FILE c25c2152c0e900ab
````text
---
name: semantic-html-and-seo
description: Semantic HTML5, SEO basics, alt text, progressive enhancement and SPA concerns. Use when building web UI, reviewing markup or optimising for search.
metadata:
priority: 8
pathPatterns:
- "**/*.html"
- "**/*.tsx"
- "**/*.jsx"
- "**/*.vue"
- "**/*.svelte"
- "app/**"
- "pages/**"
- "src/**"
promptSignals:
phrases:
- "seo"
- "semantic html"
- "alt text"
- "meta tags"
- "progressive enhancement"
- "spa"
- "open graph"
- "structured data"
- "html5"
- "localstorage"
- "sessionstorage"
- "personalization"
- "remember user preference"
retrieval:
aliases:
- seo
- semantic html
- alt text
- progressive enhancement
- html5 best practices
- meta tags
- open graph
- structured data
- spa seo
- client-side storage
- localStorage personalization
intents:
- improve seo
- add alt texts
- write semantic html
- optimise for search engines
- add open graph tags
- make spa crawlable
- persist user preferences client-side
- personalise based on stored state
examples:
- add proper meta tags to this page
- write semantic html for this component
- how do I make this SPA SEO friendly
- add alt texts to all images
- remember the user's last view with localStorage
- personalise this returning-user experience
---
# Semantic HTML and SEO
Good HTML is not just markup — it is the contract between your content, search engines, assistive technologies, and the browser. Semantic HTML, correct metadata, and progressive enhancement make UI resilient, findable, and accessible by default.
---
## Semantic HTML5
Use the element that describes the content's meaning, not just its appearance.
### Document structure
```html