static-seo
Audits and improves SEO for static HTML sites. Use when the user asks to audit, set up, or improve SEO on a static site (Hugo, Jekyll, 11ty, Gatsby, Next.js static export, hand-rolled HTML, or `wp-static-clone` output), or mentions head metadata, structured data, JSON-LD, sitemaps, IndexNow, Open Graph images, schema endpoints, NLWeb, hreflang, or search engine indexing for a static site. For Astro projects, use `astro-seo` instead — its recipes produce less hand-rolled boilerplate by routing through `@jdevalk/astro-seo-graph`.
jdevalk · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jdevalk/skills --skill static-seoAbout this skill
name: static-seo
description: >
Audits and improves SEO for static HTML sites. Use when the user asks to
audit, set up, or improve SEO on a static site (Hugo, Jekyll, 11ty,
Gatsby, Next.js static export, hand-rolled HTML, or wp-static-clone
output), or mentions head metadata, structured data, JSON-LD, sitemaps,
IndexNow, Open Graph images, schema endpoints, NLWeb, hreflang, or
search engine indexing for a static site. For Astro projects, use
astro-seo instead — its recipes produce less hand-rolled boilerplate
by routing through @jdevalk/astro-seo-graph.
Static SEO
Audits and improves the SEO setup of a static HTML site against nine categories — head metadata, structured data, content quality, Open Graph images, sitemaps and indexing, agent discovery, performance, redirects, and CI validation. Recipes are platform-neutral: raw <meta> tags, raw JSON-LD, hand-rolled sitemap.xml, generic CI tooling. Audit framework parallels astro-seo but without the @jdevalk/astro-seo-graph spine.
Code recipes live in AGENTS.md — read it when you need to implement a specific fix. This file has the workflow and audit checklist.
Workflow
- Detect the project — confirm this is a static site, identify the build tool, find where to apply changes.
- Audit — score nine categories and produce actionable findings.
- Improve — generate or modify files to close the gaps. Recipes are in
AGENTS.md. - Metadata pass — invoke
metadata-checkon every short string the skill generated (titles, descriptions, schemadescriptionfields, FAQ answers). - Verify — run any build, validate the output, remind the user about non-file tasks (Search Console, Bing Webmaster Tools, IndexNow key submission).
Phase 0: Detect the project
Confirm the basics before auditing:
- It is actually a static site. Look for built HTML —
index.htmlat the repo root, or under_site/(Jekyll),public/(Hugo / 11ty / Gatsby),dist/(Vite / Astro static),out/(Next.js withoutput: export). If everything is server-rendered (Express, PHP, dynamic routes), this is the wrong skill — point atastro-seofor Astro,wp-readme-optimizerfor WP plugin pages, or recommend a generic SEO audit instead. - Source build tool. Drives where to apply head metadata changes:
_config.yml/_layouts/→ Jekyllconfig.toml/config.yaml/themes/→ Hugo.eleventy.js/_includes/→ 11tygatsby-config.js/src/components/SEO.*→ Gatsbynext.config.jswithoutput: 'export'andpages/_document.tsx→ Next.js static exportastro.config.mjs→ Astro (in which case useastro-seoinstead)- No build config, just HTML files → hand-rolled or scraped (e.g.
wp-static-cloneoutput). Edit the HTML directly or use a post-process script.
- Canonical site URL. Search the repo for the production origin — typically in
_config.yml,config.toml,astro.config, or hardcoded into a layout. If it's missing, empty, orlocalhost, flag as a blocking issue before anything else. Canonicals, sitemaps, OG image URLs, and JSON-LD@idvalues all derive from this. - Deployment target. Read
vercel.json,netlify.toml,wrangler.toml, orpublic/_headersto determine the host. Drives redirect and header syntax in Phase 2. - Is the site multilingual? Check for locale subdirectories (
/en/,/nl/,/de/) or build-tool i18n config. If yes, hreflang matters; if no, skip it. - What's already in
<head>? Open one built HTML file and inventory: title, description, canonical, robots, Open Graph, Twitter cards, JSON-LD, hreflang. The audit in Phase 1 is faster if you can reference what's there.
Ask only what you can't detect.
Phase 1: Audit
Score each category out of 10. For each, give 2–4 specific findings that quote the actual HTML, config, or template. Within each category, checks are tiered:
- Must — ship blockers. A failure causes visible SEO regression.
- Should — standard practice. Skipping costs reach.
- Nice — forward-looking or situational. Useful but not baseline for every site.
Skip Nice checks for small personal sites unless the user asks for the full treatment.
1. Head metadata (/10)
- Must — every page has a
<title>and<meta name="description">. - Must —
<link rel="canonical">set, with tracking parameters stripped, derived from the production origin. - Must — canonical omitted when the page is
noindex(per Google's recommendation). - Must —
<title>length 30–65 characters,<meta name="description">length 70–200 characters (the SERP-truncation bounds; same asmetadata-checkdefaults). - Should —
<meta name="robots">includesmax-snippet:-1,max-image-preview:large,max-video-preview:-1. - Should — Open Graph (
og:title,og:description,og:image,og:url,og:type,og:site_name) on every page. - Should — Twitter Card tags (
twitter:card) suppressed when they duplicate Open Graph (Twitter falls back automatically). - Should —
hreflangalternates on multilingual sites. Skip if monolingual. - Should — single
<meta name="robots">and singleog:imageper page (legacy tooling sometimes emits duplicates).
2. Structured data / JSON-LD (/10)
- Must — at least one
<script type="application/ld+json">block on every important page. - Should — linked
@graphrather than a flatArticleobject — entities wired with@idreferences so aBlogPostingcan point at itsPersonauthor andWebPageparent. - Should —
WebSite,Blog/WebPage,Person/Organization,BlogPosting/Article,BreadcrumbList,ImageObjectall present where relevant. - Should — trust signals:
publishingPrinciples,copyrightHolder,copyrightYear,knowsAbout,SearchAction. - Must — validates in Rich Results Test an