docs-seo

name

docs-seo

description

Audit and improve the discoverability of the timepicker-ui documentation site (docs-app/) across the full modern discoverability stack — SEO (ranking), AEO (answer engines / featured snippets), GEO (citations inside ChatGPT/Gemini/Perplexity/Claude), and AIO (Google AI Overviews). Use when the user wants to optimize docs SEO, improve Google ranking/positioning, win featured snippets or AI-answer boxes, get the docs cited by AI engines, add or fix sitemap/robots/manifest, fill in page metadata, add Open Graph/Twitter cards, answer-first copy, or JSON-LD (FAQPage/SoftwareApplication/TechArticle/BreadcrumbList). Drives the seo-optimizer subagent with an audit → approve → apply flow.

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:

1. SEO — technical files (sitemap / robots / manifest / metadataBase)
2. SEO — per-page metadata (the missing/duplicate titles + descriptions)
3. SEO — root + Open Graph / Twitter (+ OG image)
4. AEO — answer-first copy + question-formatted headings + FAQPage on Q&A pages
5. GEO — consistent entity footprint + concrete facts + SoftwareApplication/JSON-LD
6. 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 mandates the two 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). The subagent MUST, every run, in both audit and apply mode:

• Check the web first. Derive today's real date (date +%Y-%m-%d) 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. 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 uses lucide-react — 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 (lucide or none). It keeps the entity footprint consistent across hero copy, metadata, OG, and JSON-LD.

Phase 4 — Verify & report

• Offer to run cd docs-app && npm run build to confirm the site still builds (don't assume — the user may prefer to run it). If you run it, 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 every run from today's real date, never from memory or a hardcoded year — for all four layers. A run today and a run 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 lucide-react).
• Keep this skill and the agent file in CRLF; for docs-app/ source files, match 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.