Kelly SEO

Overview

Use this skill as Kelly's SEO + GEO desk. A Busabase-backed App-in-Skill holds Google Search Console search analytics (clicks, impressions, CTR, position for queries and pages across configured site properties) and an agent-prepared SEO opportunities review queue: title/meta rewrites, internal-link suggestions, new-content briefs, and page-issue fixes that the user approves, edits, or blocks.

It also covers the AI-search side (GEO — Generative Engine Optimization): an AI-visibility tracker showing whether AI answer engines (ChatGPT / Perplexity / Gemini / Claude / Copilot) cite the brand for a set of tracked prompts, a GEO content-optimization review queue (agent-drafted rewrites that make a page more citable, each scored by the geo-qa quality gate), and a brand-entity / knowledge-panel readiness checklist (Wikidata, schema.org Organization/Person, consistent NAP, sameAs links). GEO opportunities and entity signals flow through the same Busabase Bases and the same five-state review model as SEO opportunities.

Pulling Search Console analytics is a genuine external operation a browser cannot perform (it needs a Google service-account key or OAuth token): scripts/sync_gsc.mjs is the only place analytics data enters the system. The AirApp itself only reads Busabase and writes review decisions (approve / request changes / block / revise) directly onto the opportunity, GEO opportunity, or entity-signal record; scripts/execute_decisions.mjs records the planned follow-up for approved SEO opportunities, and the agent performs the actual site edit outside the app after explicit approval.

Default behavior is AirApp-first. Unless the user explicitly asks only for explanation, sync what's due and give the user the clickable AirApp URL (or the local preview URL when local preview is explicitly requested). Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar.

App UI Screenshots

<table> <tr> <td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly SEO overview"></td> <td width="50%"><img src="assets/screenshots/queries.webp" alt="Kelly SEO queries"></td> </tr> <tr> <td><strong>Overview</strong><br>Search Console KPI cards with daily clicks/impressions chart, top movers, and per-site freshness.</td> <td><strong>Queries</strong><br>Top queries with clicks, impressions, CTR, position, period deltas, and opportunity badges.</td> </tr> <tr> <td width="50%"><img src="assets/screenshots/pages.webp" alt="Kelly seo pages"></td> <td width="50%"><img src="assets/screenshots/opportunities.webp" alt="Kelly seo opportunities"></td> </tr> <tr> <td><strong>Pages</strong><br>Page-level click and impression table with top growth and decline movers for prioritizing content updates.</td> <td><strong>Opportunities</strong><br>Ranked SEO opportunity queue with impact, effort, evidence, and recommended next actions.</td> </tr> <tr> <td width="50%"><img src="assets/screenshots/geo.webp" alt="Kelly SEO AI visibility"></td> <td width="50%"><img src="assets/screenshots/optimize.webp" alt="Kelly SEO GEO optimizer"></td> </tr> <tr> <td><strong>AI visibility (GEO)</strong><br>An engines×prompts matrix of where the brand is cited across ChatGPT, Perplexity, Gemini, Claude, and Copilot, with an overall visibility score and trend.</td> <td><strong>GEO optimizer</strong><br>Agent-proposed rewrites that make pages more citable by AI engines, gated by geo-qa — one blocked for a fabricated stat.</td> </tr> <tr> <td width="50%"><img src="assets/screenshots/entity.webp" alt="Kelly seo entity readiness"></td> </tr> <tr> <td><strong>Entity readiness</strong><br>Entity readiness checklist showing schema coverage, citation signals, and blocked/ready status for AI answer engines.</td> </tr> </table>

Mandatory Dependencies

1. Read and follow $kelly-app-skill-creator for product behavior, visual quality, responsive layout, and the complete canonical content/kelly-seo-app/ artifact.
2. Read and follow $busabase for connection, target Space, node discovery, ChangeRequests, review, and merge behavior.
3. Read and follow $busabase-app-creator for resource modeling, AirApp runtime limits, security, validation, and deployment.

If a dependency is unavailable, preserve this skill's artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.

Boundary

• Pulling Search Console data is a trusted-script-only operation: scripts/sync_gsc.mjs calls the read-only GSC API and writes normalized site/query/page records into Busabase. It never mutates Search Console properties, submits sitemaps, or requests indexing.
• The AirApp reads and writes Busabase records only. It never calls the GSC API, edits site content, or mutates any remote system.
• Site-content edits happen only through approved opportunities, executed by the agent OUTSIDE the app (editing the site's repo/CMS), after scripts/execute_decisions.mjs marks the opportunity ready_for_agent. GEO content changes follow the same rule: approved in #/optimize, published by the agent outside the app.
• AI-visibility data is observational: the agent gathers whether engines cite the brand and writes it into the ai-visibility Base directly (via busabase-sdk, following references/seo-schema.md's field slugs). Never fabricate a citation, an answer position, or a stat — the geo-qa gate BLOCKs ungrounded claims for exactly this reason.
• No Google credentials live in this repo. The service-account key path or OAuth token is referenced by env var name only (KELLY_SEO_GSC_SERVICE_ACCOUNT_FILE, KELLY_SEO_GSC_ACCESS_TOKEN). Never commit config.local.json, env files, service-account keys, or access tokens.

Busabase Resources

Eight Bases under one application Folder (kelly-seo), declared in content/kelly-seo-app/app/js/config.js and the generated template sidecars under content/:

• sites: configured Search Console properties with 28d totals and a daily trend series, synced by scripts/sync_gsc.mjs.
• queries: top queries with deltas, opportunity badges, top pages, and a trend series (capped at 100 rows by clicks).
• pages: top pages with deltas, indexing/canonical issues, top queries, and a trend series (capped at 100 rows by clicks).
• opportunities: the SEO review queue — title/meta rewrite, internal links, content brief, or page-issue fix, with the human decision and execution marker on the same row.
• geo-opportunities: the GEO content-optimization review queue — citable rewrite, quotable stats, Q&A block, or schema markup, gated by geo-qa (recomputed live from the draft on every read).
• ai-visibility: tracked AI-answer-engine prompts with per-engine mentions and a visibility trend.
• entity-signals: the brand-entity / knowledge-panel readiness checklist.
• settings: one row (record-id: "config") with the brand, GSC sync window/read-only config, last-sync range, warnings, and the AI-visibility score baseline.

Resources provision lazily through an idempotent Busabase ChangeRequest the first time the app runs in a Space; see references/seo-schema.md for exact field shapes. Metrics, the AI-visibility score, and the entity-readiness score are recomputed client-side from the stored rows on every read (content/kelly-seo-app/app/js/seo-model.js's buildSnapshot/assembleSnapshot), so the desk is always fresh regardless of when a browser session loads it relative to the last sync.

First Run And Onboarding

On invocation, check the sites Base. If it is empty, guide setup before syncing real data: ask which site properties to track (property_url, a short site_id, verification type) and which auth method to use. Never ask the user to paste keys or tokens into chat.

Private config priority (read only by the trusted scripts/sync_gsc.mjs, never by the AirApp):

1. KELLY_SEO_CONFIG=/absolute/path/to/config.json
2. skills/kelly-seo/config.local.json
3. ~/.config/kelly-seo/config.json

Env priority:

1. Existing environment variables
2. KELLY_SEO_ENV_FILE=/absolute/path/to/.env
3. Repository root .env
4. skills/kelly-seo/.env.local
5. ~/.config/kelly-seo/.env

config.local.json shape: { "sites": [{ "site_id", "property_url", "verification_type" }], "auth": { "method", "service_account_file_env", "access_token_env" }, "sync": { "window_days", "row_limit" } }.

Auth methods (choose one):

• Service account (recommended for recurring syncs): the user creates a Google Cloud service account, downloads its JSON key, and adds the service account's email address as a user on each Search Console property (Settings → Users and permissions → Add user, Full or Restricted read access). Point KELLY_SEO_GSC_SERVICE_ACCOUNT_FILE at the key file path in a local env file.
• Plain OAuth access token (for quick manual runs): put a short-lived token with scope https://www.googleapis.com/auth/webmasters.readonly in KELLY_SEO_GSC_ACCESS_TOKEN.

Local App

Default behavior is AirApp-first — give the user the clickable AirApp URL. Start pnpm --dir content/kelly-seo-app dev only when local preview/debugging is explicitly requested.

Required app views (hash routes):

• #/overview: SEO command desk. Per-site KPI cards (clicks, impressions, CTR, average position, 28d vs previous 28d deltas), a daily clicks/impressions trend, top movers (queries with the biggest click gains and losses), site freshness (last sync), and the human-attention panel for opportunities needing review.
• #/queries: top queries table with clicks, impressions, CTR, position, deltas vs the previous period, and opportunity badges such as "position 8-15" or "CTR below expected". Selecting a row opens #/queries/<id> with a per-query trend, top pages for the query, and agent notes.
• #/pages: top pages table with URL, clicks, impressions, CTR, position, deltas, and indexing/canonical warnings when present. Detail at #/pages/<id> shows the per-page trend and top queries for the page.
• #/opportunities: review queue with workflow states needs_review, changes_requested, approved, done, and blocked. Each agent-proposed action (title/meta rewrite with draft, internal-link suggestion, new-content brief, fix-page issue) carries a reason, expected impact, an editable draft, decision buttons (approve / request changes / block), a Review note textarea, and a stable reference such as Opportunity #1. Decisions write directly onto the opportunity record through busabase-sdk.
• #/geo: AI-visibility tracker. An engines × prompts matrix showing, for each tracked prompt, which AI answer engines (ChatGPT / Perplexity / Gemini / Claude / Copilot) cite the brand, at what answer position, with what sentiment and cited page, plus an overall AI-visibility score and a visibility-over-time trend.
• #/optimize: GEO content-optimization review queue with the same needs_review / changes_requested / approved / done / blocked states. Each agent-proposed change (citable rewrite, quotable stats, Q&A block, schema markup) carries a target prompt, reason, expected impact, an editable draft, kb-style grounding lines, and a live geo-qa gate verdict (SHIP / FIX / BLOCK). A change the gate BLOCKs (for example a fabricated stat) cannot be approved until the failing checks are resolved.
• #/entity: entity / knowledge-panel readiness checklist of brand-entity signals (Wikidata entity, Wikipedia/notability, schema.org Organization, sameAs links, consistent NAP, founder/person entity) with a present / partial / missing status, an agent-proposed fix for each gap, and an overall readiness score.
• #/sites: configured properties with property URL, verification type, last sync, and 28d totals per site. The site switcher filters overview/queries/pages.
• #/settings: sanitized config summary — brand, locale, sync window/row-limit/read-only, read live off the Settings Base.

Demo mode:

• ?demo=1 opens a deterministic mock SEO desk ("Featherlog" persona) for documentation and screenshots.
• ?demo=overview, ?demo=queries, ?demo=pages, ?demo=opportunities, ?demo=geo, ?demo=optimize, ?demo=entity, and ?demo=detail select named mock scenes.
• lang=en or lang=zh forces UI chrome language for screenshots.
• Demo mode never reads or writes Busabase. Decisions stay in the browser only.

UI language: support English and Chinese chrome with Auto default. Keep queries, page URLs, and imported search data in their original language.

Sync Workflow

1. Detect mode. Default to AirApp.
2. Load private config. If config.local.json is missing, enter onboarding.
3. If the user asks to sync, confirm the scope: which properties and the date window (default last 28 days plus the previous 28 days for deltas).
4. Run node skills/kelly-seo/scripts/sync_gsc.mjs. The script pulls Search Analytics dimensioned by query, by page, and by date for both windows, normalizes and upserts sites/queries/pages into Busabase (capped at the top 100 queries/pages by clicks — records.list's server-side limit), and merges the sync-owned fields (window/row-limit/range/warnings) onto the settings row. It never touches opportunities, geo-opportunities, ai-visibility, or entity-signals.
5. Give the user the AirApp URL.
6. GSC data lags about two days; the sync window ends two days before today. Surface API errors and missing-property warnings in settings.warnings, never as silent failures.

scripts/sync_gsc.mjs fails gracefully with setup guidance when neither KELLY_SEO_GSC_SERVICE_ACCOUNT_FILE nor KELLY_SEO_GSC_ACCESS_TOKEN is usable. It is never required for demo mode or app startup.

Opportunities Workflow

1. After a sync, analyze the queries/pages Bases for striking-distance queries (position 8-15), CTR below the expected curve for the position, pages losing clicks, internal-link gaps, and page issues. Write proposed actions into the opportunities Base with stable ids, sequential ref numbers, a reason, an expected impact, and an editable draft (via busabase-sdk, following references/seo-schema.md).
2. Send the user to #/opportunities to review. The user approves, edits drafts, requests changes with a note, or blocks — each verdict writes status/decision-action/decision-note/decision-draft/decided-at directly onto the opportunity record.
3. On explicit user request to execute, run node skills/kelly-seo/scripts/execute_decisions.mjs (dry-run by default). It re-reads status: "approved" opportunities and, with --apply, writes execution-status: "ready_for_agent" plus the concrete operation (rewrite_title, add_internal_links, create_content_brief, fix_page_issue) and target — no external side effects either way.
4. The agent then performs the approved edits in the site's repo/CMS outside the app, and marks the executed opportunity status: "done" by writing the field directly (via busabase-sdk).

GEO (AI-search) Workflow

1. GEO state lives in the ai-visibility (tracked prompts × engines with position + sentiment + trend), geo-opportunities (agent-proposed citable rewrites), and entity-signals (the readiness checklist) Bases. Route all reads/writes through busabase-sdk — never bypass it.
2. For each agent-proposed GEO change written to geo-opportunities, the geo-qa gate (evaluateGeoGate() in content/kelly-seo-app/app/js/seo-model.js) is recomputed live from draft/claims/has-schema/has-qa-block on every read — it returns SHIP / FIX / BLOCK with a GEO Quality Score and per-check notes. The primary failure is an ungrounded/fabricated stat — a number in the copy with no matching entry in claims carrying a source. A BLOCK is a hard gate: the app rejects an approve before any write until the change is fixed.
3. Send the user to #/optimize to review. Approvals write status/decision-* directly onto the GEO opportunity record. Execution semantics: operation: publish_geo_change — the agent publishes the approved citable content in the site's repo/CMS OUTSIDE the app, then marks the item done by writing the field directly.
4. Entity-readiness edits from #/entity write status/detail directly onto the entity-signals record. The agent then earns the real signal (create the Wikidata item, add the sameAs links, standardize the brand name) outside the app.
5. Never invent an AI-visibility number, a citation, or a stat. If a claim in a GEO draft is not grounded in a real source, the gate must BLOCK it — do not ship content that an AI engine would then quote verbatim.

Safety Defaults

• Treat anything that changes live site content, metadata, redirects, canonical tags, or robots rules as approval-required via the opportunities queue.
• Prefer the read-only GSC scope; never store key file contents or tokens in Busabase, logs, UI state, or reports — expose only env readiness booleans.
• Keep stored data minimal: top queries/pages and aggregates, not raw exports beyond what the dashboard needs.
• Use stable ids and refs so repeated syncs and executions are idempotent.
• If GSC totals and per-dimension rows disagree (sampling/privacy filtering), do not invent corrections; add a settings.warnings entry explaining the gap.