docs-seo

The full skill.

Original instructions from the publisher’s SKILL.md

# 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.