Docs Discoverability (SEO + AEO + GEO + AIO)
Make docs-app/ (the Next.js 16 documentation site for timepicker-ui) found, read,
and cited by people, search crawlers, and AI answer engines — so it is the answer a
developer, Google, and ChatGPT all reach for when someone wants a time picker. This skill
is a thin orchestrator: the real work is done by the seo-optimizer subagent (which
covers the full four-layer stack, not just classic SEO). The skill exists to manage the
human approval gate the subagent can't do itself.
Default production URL: https://timepicker-ui.vercel.app (use unless the user gives another).
This is a fully public open-source site: everything here is meant to be indexed and
cited. There is no private data and no protected branding. The subagent's guardrail is
truthfulness (never describe a feature the library lacks) and quality (no AI slop),
not privacy.
Arguments (optional)
- A focus area narrows the run, e.g.
/docs-seo metadata, /docs-seo sitemap,
/docs-seo structured-data, /docs-seo opengraph, /docs-seo aeo (answer-first + FAQ),
/docs-seo geo (entity footprint + citations). No argument = full audit of all layers.
--apply-all skips the per-area approval prompt and applies every audited change (still
reports at the end). Use only when the user explicitly wants unattended changes.
Workflow
Phase 1 — Audit (read-only)
Dispatch the seo-optimizer subagent (Task tool, subagent_type: seo-optimizer) in audit
mode. Brief it with the production URL and the focus area (if any), and tell it to discover
the current state for itself rather than trusting any baseline — what was missing last run
may already be fixed. Ask it to return a prioritized, file-level change plan grouped into:
- SEO — technical files (sitemap / robots / manifest / metadataBase)
- SEO — per-page metadata (the missing/duplicate titles + descriptions)
- SEO — root + Open Graph / Twitter (+ OG image)
- AEO — answer-first copy + question-formatted headings +
FAQPage on Q&A pages
- GEO — consistent entity footprint + concrete facts +
SoftwareApplication/JSON-LD
- AIO / AI-crawler / Core Web Vitals flags (llms.txt + robots AI user-agents are the
owner's call; default is to welcome AI crawlers on a public OSS site)
The subagent's own definition already sets the checks below — this is the reminder to
put in its brief, not a second source of truth (if the agent's rules change, its file wins).
- Today's date from your context: the agent has no Bash to look it up.
- Check the web first in audit mode (in apply mode only when an approved item rests on a
fact it doubts). Use today's date from the brief and web-search the
current best practice across all four layers — Next.js APIs, Google ranking + AI-slop +
AI-features guidance, AEO/GEO/AIO tactics, the AI-crawler /
llms.txt state — rather than
optimizing from memory. Live sources win over anything hardcoded; it cites sources + dates.
- Run the AI-slop check on text AND icons in both modes. Scan existing and proposed titles/descriptions/
FAQ copy for slop and long dashes (
—/–), and the SEO/OG surface for stray Unicode emojis
or native/system icons (the site draws its few icons as inline SVG in components/icons.tsx;
emoji/native icons are a defect to flag, not ship).
It makes NO edits in this phase.
Phase 2 — Present & approve (gate)
Relay the audit plan to the user concisely (counts + the concrete titles/descriptions/FAQ Q&A
and files per group). Then use AskUserQuestion to let the user choose which groups (and,
where it matters, which items) to apply. AskUserQuestion caps at 4 options per question, so
present the six groups as a multi-select batched into two questions when needed, then a
follow-up for item-level choices where it matters. This is a mandatory gate — do not skip it
unless --apply-all was passed. Capture the approved set.
Phase 3 — Apply
Dispatch the seo-optimizer subagent again in apply mode with the exact approved list
(files + the decided titles/descriptions/answer-first copy/structured data). It implements the
changes under docs-app/ using real Next 16 typed APIs, keeping titles/descriptions unique,
on-keyword, answer-first where it's a docs page, and written like a human — short, specific, no
AI slop, no long dashes, and no emojis/native icons (the site's own SVG icons or none). It keeps the entity
footprint consistent across hero copy, metadata, OG, and JSON-LD.
Phase 4 — Verify & report
- Run
cd docs-app && npm run build to confirm the site still builds, then /verify per HARD
RULES §5. Report pass/fail honestly with output.
- Summarize what changed, grouped by the six areas, with the file list.
- Give the manual verification checklist: open
/sitemap.xml, /robots.txt,
/manifest.webmanifest; view-source a couple of routes for <title>, OG/Twitter tags, and
JSON-LD; validate structured data with Google Rich Results Test / Schema.org validator. Note
that AEO/GEO wins (featured snippets, AI-Overview appearance, ChatGPT/Perplexity citations)
show up over time and are tracked separately from classic rankings.
- Note that git is the user's job — propose a commit message but do not commit.
Guardrails
- The subagent edits ONLY
docs-app/; it never touches the library in app/ or dist/.
- Truthfulness over reach. Metadata, keywords, FAQ answers, and JSON-LD must match the real
library — a fabricated fact is what gets the entity distrusted by AI engines and demoted by
Google. When unsure a feature exists, verify against
app/src/types/options.d.ts or the docs.
- Don't regress existing good metadata/JSON-LD — extend it (FAQ/TechArticle JSON-LD already ships).
- Best practices are re-derived live in every audit from today's real date, never from memory or a
hardcoded year — for all four layers. An audit today and one months from now both research the
current guidance.
- The generated copy is human, short, slop-free: no filler openers or empty intensifiers, no
keyword stuffing, no long dashes (
—/–, use short hyphens), and no Unicode emojis or
native icons (use the SVG icons in components/icons.tsx, or none).
- Keep this skill, the agent file and
docs-app/ files in CRLF; otherwise follow docs-app's
own conventions.
- One run optimizes discoverability; it does not redesign the site. Visual/content rewrites
beyond SEO/answer-first copy belong to the
docs-site agent.